App API reference

import type { Knex } from 'knex';
import { Auth, type AuthOptions } from '../auth/index.js';
import { Cache } from '../cache/index.js';
import { Config, type ConfigValues } from '../config/index.js';
import { Database, type DatabaseOptions } from '../db/index.js';
import { Events } from '../events/index.js';
import { UrlGenerator, type UrlGeneratorOptions } from '../url/index.js';
import { Queue, type QueueOptions } from '../queue/index.js';
import { Log, type LoggingOptions } from '../logging/index.js';
import { Storage, type StorageOptions } from '../storage/index.js';
import { Scheduler } from '../scheduler/index.js';
import { Security } from '../security/index.js';
import { Serializer, type SerializerOptions } from '../serialization/index.js';
import { MediaManager } from '../media/index.js';
import { RequestContext } from './RequestContext.js';
export interface AppOptions {
    db?: Knex;
    dbOptions?: DatabaseOptions;
    auth?: Omit<AuthOptions<any>, 'db' | 'requestContext'>;
    config?: ConfigValues | Config;
    /** Application logging configuration or injectable logger driver. */
    log?: LoggingOptions;
    /** Canonical application URL configuration used across all runtimes. */
    url?: UrlGeneratorOptions;
    queue?: QueueOptions;
    /** Serializable classes and ActiveRecord models registered with app().serializer. */
    serializer?: SerializerOptions;
    storage?: StorageOptions;
}
/**
 * Application service hub.
 *
 * Keep this as the place where top-level framework capabilities are discovered
 * and wired, not where domain logic itself accumulates.
 */
export declare class App {
    protected readonly options: AppOptions;
    private readonly services;
    /**
     * Creates an application service hub and validates configured startup security.
     *
     * @param options - Framework services and application configuration.
     */
    constructor(options?: AppOptions);
    get db(): Database;
    get auth(): Auth<any>;
    get requestContext(): RequestContext;
    /**
     * Returns the configured application cache.
     *
     * Cache driver selection lives under `config.cache`, keeping backend
     * connection details out of application code.
     *
     * @returns Cache service using the configured named store.
     */
    get cache(): Cache;
    /**
     * Returns the typed in-process application event dispatcher.
     *
     * @returns Event service shared by framework and application code.
     */
    get events(): Events;
    /**
     * Returns the application logger shared by framework and app services.
     *
     * @returns Pino-backed logging service with app lifecycle ownership.
     */
    get log(): Log;
    /**
     * Returns the canonical application URL generator.
     *
     * This is independent of any concrete Fastify, Express, or other server
     * instance so background processes resolve the same public application URL.
     *
     * @returns Shared canonical URL generator.
     */
    get url(): UrlGenerator;
    /**
     * Returns the configured app config repository.
     */
    get config(): Config;
    get queue(): Queue;
    /**
     * Returns the application scheduler and attaches queue lifecycle recording.
     *
     * @returns Scheduler backed by the active database and queue services.
     */
    get scheduler(): Scheduler;
    /**
     * Returns the central application security service.
     *
     * @returns Shared authenticated encryption service.
     */
    get security(): Security;
    /**
     * Returns the application serializer and its scoped class/model registry.
     *
     * @returns Strict serializer configured for this application process.
     */
    get serializer(): Serializer;
    /**
     * Returns the configured file storage service.
     */
    get storage(): Storage;
    /**
     * Returns the configured media manager.
     *
     * Media options are resolved from `config.media`, allowing applications to
     * place derived image variants on a disposable storage disk.
     *
     * @returns Media manager backed by configured durable and temporary storage.
     */
    get media(): MediaManager;
    /**
     * Registers a concrete service instance.
     *
     * Useful for tests and for services that are built by a provider.
     */
    set<TService>(name: string, service: TService): this;
    /**
     * Returns a configured service, creating and caching it on first access.
     */
    service<TService>(name: string, factory: () => TService): TService;
    /**
     * Closes shared resources owned by the default app.
     */
    close(): Promise<void>;
    private resolveDbConnection;
    private resolveDatabaseOptions;
}

import type { Knex } from 'knex';
import type { App } from './App.js';
import type { RequestContext } from './RequestContext.js';
export interface AppDatabaseProvider {
    db: {
        knex: Knex;
    };
    requestContext?: RequestContext;
}
/**
 * Registers the active app for framework services that need app-scoped access.
 */
export declare function setActiveApp(app: AppDatabaseProvider): AppDatabaseProvider;
/**
 * Returns the active application service hub.
 *
 * Framework and application jobs use this accessor to resolve services when
 * their handle methods run inside a bootstrapped worker process.
 *
 * @returns Active application instance.
 */
export declare function app<TApp extends AppDatabaseProvider = App>(): TApp;
/**
 * Clears the active app when the caller owns the current active instance.
 */
export declare function clearActiveApp(app?: AppDatabaseProvider): void;
/**
 * Returns the active app database connection when an app is registered.
 */
export declare function activeAppDatabase(): Knex | null;
/**
 * Returns the active app request context when an app is registered.
 */
export declare function activeAppRequestContext(): RequestContext | null;

export type RequestContextValues = Map<string, unknown> | Record<string, unknown> | Iterable<readonly [string, unknown]>;
/**
 * Request-scoped key/value context.
 *
 * Values are isolated with AsyncLocalStorage so the app singleton can expose
 * request data without sharing it across concurrent requests.
 */
export declare class RequestContext {
    private readonly storage;
    /**
     * Returns true when code is running inside a request context.
     */
    get active(): boolean;
    /**
     * Runs a callback inside an isolated request context.
     */
    run<TResult>(callback: () => TResult, initialValues?: RequestContextValues): TResult;
    /**
     * Reads a value from the active request context.
     */
    get<TValue = unknown>(key: string): TValue | undefined;
    /**
     * Returns true when the active request context contains a value for the key.
     */
    has(key: string): boolean;
    /**
     * Stores a value on the active request context.
     */
    set<TValue>(key: string, value: TValue): TValue;
    /**
     * Returns an existing request value or stores the factory result for reuse.
     */
    remember<TValue>(key: string, factory: () => TValue): TValue;
    /**
     * Deletes a value from the active request context.
     */
    delete(key: string): boolean;
    /**
     * Normalises initial request values into the internal map store.
     */
    private initialStore;
}