@lakutata/core 1.0.60 → 3.0.0-beta.1

package/dist/cjs/lib/app/Application.d.ts

@@ -0,0 +1,346 @@
+import { Module } from '../core/Module.js';
+import { ApplicationConfigLoader } from './ApplicationConfigLoader.js';
+import { ApplicationOptions } from '../../options/ApplicationOptions.js';
+import { Alias } from '../core/Alias.js';
+import { ILogger } from '../../interfaces/ILogger.js';
+import { SynchronousEventEmitter } from '../base/EventEmitter.js';
+import { type ApplicationExitReason } from '../../types/ApplicationExitReason.js';
+import { ModuleOptions } from '../../options/ModuleOptions.js';
+/**
+ * The handler of `Application.onLaunched()`: called with the application and its logger once it has launched.
+ */
+export type LaunchedHandler = {
+    handler(app: Application, logger: ILogger): void | Promise<void>;
+}['handler'];
+/**
+ * The handler of `Application.onDone()`: called with the application, its logger and the reason of its exit.
+ */
+export type DoneHandler = {
+    handler(app: Application, logger: ILogger, reason: ApplicationExitReason): void | Promise<void>;
+}['handler'];
+/**
+ * The handler of `Application.onUncaughtException()`: called with an uncaught error and the logger.
+ */
+export type UncaughtExceptionHandler = {
+    handler(error: Error, logger: ILogger): void | Promise<void>;
+}['handler'];
+/**
+ * The handler of `Application.onFatalException()`: called with the error which stopped the launch and the logger;
+ * returns the exit code of the process (1 when it returns none).
+ */
+export type FatalExceptionHandler = {
+    handler(error: Error, logger: ILogger): number | undefined | void | Promise<number | undefined | void>;
+}['handler'];
+/**
+ * The events of the application's lifecycle.
+ */
+export declare enum ApplicationState {
+    Launched = "LAUNCHED",
+    Done = "DONE",
+    UncaughtException = "UNCAUGHT_EXCEPTION",
+    FatalException = "FATAL_EXCEPTION"
+}
+/**
+ * The application: the root module, created and launched by the static fluent API. `Application.run()` gives its
+ * options (its identity and its components, providers, objects and bootstrap); the other static calls set its
+ * environment variables, path aliases and lifecycle handlers. The application launches once, in the turn of the event
+ * loop following the first calls; the calls made once its launch started only add their handlers (`env()`, `alias()`
+ * and `run()` have no effect then):
+ * 1. the environment variables are set, the aliases registered (`@runtime` being the working directory);
+ * 2. the options are read (from the getter given to `run()`, which may be async) and validated, the identity applied
+ *    (`process.title` is the application ID, the time zone and the mode set);
+ * 3. the application is created in a new root container: its objects are registered and its bootstrap runs in order;
+ * 4. the `onLaunched()` handlers and the objects' `launched()` hooks run.
+ *
+ * A failure of steps 1 to 3 is a fatal exception: the `onFatalException()` handler runs (or the error is logged), then
+ * the process exits (code 1 by default). The application ends by `app.exit()` or a shutdown signal (`shutdownSignals`
+ * option): the `onDone()` handlers run, the objects are destroyed, then the process exits.
+ *
+ * The objects of the application are reached with `@Inject`, or with `app.getObject()`.
+ * @example
+ * ```typescript
+ * import {Application, Component} from 'lakutata'
+ *
+ * class Greeter extends Component {
+ *     public greet(name: string): string {
+ *         return `Hello, ${name}`
+ *     }
+ * }
+ *
+ * Application
+ *     .env({TZ_NAME: 'Asia/Shanghai'})
+ *     .alias({'@data': './data'}, true)
+ *     .run(() => ({
+ *         id: 'greeter.app',
+ *         name: 'Greeter',
+ *         components: {
+ *             greeter: {class: Greeter}
+ *         },
+ *         bootstrap: ['greeter']
+ *     }))
+ *     .onLaunched(async (app, logger): Promise<void> => {
+ *         const greeter: Greeter = await app.getObject<Greeter>('greeter')
+ *         logger.info(greeter.greet(app.appName))
+ *     })
+ *     .onDone((app, logger, reason): void => logger.info('Exiting with the code %d', reason.code))
+ *     .onFatalException((error, logger): number => {
+ *         logger.error(error)
+ *         return 2
+ *     })
+ * ```
+ */
+export declare class Application extends Module {
+    #private;
+    /**
+     * The emitter of the lifecycle events, shared by the application class.
+     * @protected
+     */
+    protected static readonly eventEmitter: SynchronousEventEmitter;
+    /**
+     * The application once launched; undefined before, or when its launch failed.
+     * @protected
+     */
+    protected static readonly appInstance: Application | undefined;
+    /**
+     * The environment variables given by `env()`, set at launch.
+     * @protected
+     */
+    protected static readonly environmentVariableMap: Map<string, string>;
+    /**
+     * The path aliases given by `alias()`, registered at launch.
+     * @protected
+     */
+    protected static readonly aliasDeclarations: {
+        alias: Record<string, string>;
+        createIfNotExist: boolean;
+    }[];
+    /**
+     * The options given to `run()`, or the function returning them.
+     * @protected
+     */
+    protected static readonly launchOptions: ApplicationOptions | (() => ApplicationOptions | Promise<ApplicationOptions>);
+    /**
+     * The timer of the launch, restarted by each call of the fluent API so that a chain launches once.
+     * @protected
+     */
+    protected static launchTimeout: NodeJS.Timeout;
+    /**
+     * Whether the launch of the application started (the calls of the fluent API after it do not launch it again)
+     * @protected
+     */
+    protected static launchStarted: boolean;
+    /**
+     * The options preset for the applications, see `preset()`.
+     * @protected
+     */
+    protected static readonly presetOptions: ModuleOptions;
+    /**
+     * Preset the options of the applications, before they run: the packages assembling the framework preset their
+     * components (the `lakutata` package presets its Logger as `log` and its Entrypoint as `entrypoint`). An object
+     * given to `run()` under a preset name replaces the preset one when it gives its class, or completes its options
+     * when it gives none (`log: {level: 'debug'}`); the preset bootstrap steps run first. Each call adds to the preset:
+     * its components, providers and named objects replace the preset ones of the same name, its anonymous objects and
+     * bootstrap steps are appended. Does not launch the application.
+     * @param options The objects and bootstrap steps to preset.
+     * @returns The application class, to chain the other calls.
+     * @example
+     * ```typescript
+     * import {Application, Component} from 'lakutata'
+     *
+     * class Metrics extends Component {
+     * }
+     *
+     * //Every application of this process gets the "metrics" component, started at launch
+     * Application.preset({
+     *     components: {
+     *         metrics: {class: Metrics}
+     *     },
+     *     bootstrap: ['metrics']
+     * })
+     * ```
+     */
+    static preset(options: ModuleOptions): typeof Application;
+    /**
+     * The logger: the application's `log` component, or a console logger when there is no application or no `log`
+     * component.
+     * @returns The logger.
+     * @protected
+     */
+    protected static getLogger(): Promise<ILogger>;
+    /**
+     * The console logger ({@link ConsoleLogger}), created once.
+     * @returns The console logger.
+     * @protected
+     */
+    protected static getConsoleLogger(): Promise<ILogger>;
+    /**
+     * Set environment variables, written to `process.env` at launch, before the options getter given to `run()` is
+     * called (it may read them). Each call adds to the previous ones.
+     * @param env The variables, by name; the values are strings.
+     * @returns The application class, to chain the other calls.
+     * @throws {InvalidMethodAcceptException} When a value is not a string.
+     */
+    static env(env: Record<string, string>): typeof Application;
+    /**
+     * Register path aliases at launch: an alias (`@data`) in a path given to `path.resolve()` of Node.js or to
+     * `app.alias.resolve()` is replaced with its path. The alias `@runtime` (the working directory) is
+     * registered by the application. An invalid alias name (`@` followed by letters and digits only) or an alias
+     * registered twice fails the launch (a fatal exception). Each call adds to the previous ones.
+     * @param alias The paths, by alias name (`{'@data': '/var/lib/app'}`).
+     * @param createIfNotExist Create the directories of the aliases which do not exist; false by default.
+     * @returns The application class, to chain the other calls.
+     * @throws {InvalidMethodAcceptException} When a path is not a string.
+     */
+    static alias(alias: Record<string, string>, createIfNotExist?: boolean): typeof Application;
+    /**
+     * Add a handler called once the application has launched (its bootstrap completed), or at once when it has
+     * launched already. An async handler is not awaited; its rejection is an unhandled rejection.
+     * @param handler The function called with the application and its logger.
+     * @returns The application class, to chain the other calls.
+     */
+    static onLaunched(handler: LaunchedHandler): typeof Application;
+    /**
+     * Add a handler called when the application exits (`app.exit()`, a shutdown signal): it runs, awaited, before the
+     * entrypoints stop and the objects are destroyed, the application still working. A handler failing makes the
+     * process exit with the code 1.
+     * @param handler The function called with the application, its logger and why it exits (its exit code, the
+     * signal ending it).
+     * @returns The application class, to chain the other calls.
+     */
+    static onDone(handler: DoneHandler): typeof Application;
+    /**
+     * Add a handler of the process' uncaught exceptions (`process.on('uncaughtException')`), the application keeping
+     * running. Without handler, the exception is logged as a warning. Every handler added is called.
+     * @param handler The function called with the error and the logger.
+     * @returns The application class, to chain the other calls.
+     */
+    static onUncaughtException(handler: UncaughtExceptionHandler): typeof Application;
+    /**
+     * Set the handler of a fatal exception: an error stopping the launch (invalid options or aliases, an object failing
+     * to initialize, a bootstrap step failing). The process exits after it, with the code it returns (1 when it returns
+     * none). Without handler, the error is logged and the process exits with the code 1. Only the first handler added
+     * is called.
+     * @param handler The function called with the error and the logger, returning the exit code.
+     * @returns The application class, to chain the other calls.
+     */
+    static onFatalException(handler: FatalExceptionHandler): typeof Application;
+    /**
+     * Give the application options and launch it (in the next turn of the event loop, once the chain of calls is
+     * complete). The options are validated at launch: invalid options are a fatal exception.
+     * @param options The application's identity (`id`, `name`), its objects and its bootstrap.
+     * @returns The application class, to chain the other calls.
+     */
+    static run(options: ApplicationOptions): typeof Application;
+    /**
+     * Give the function returning the application options, called at launch once the environment variables and the
+     * aliases are set, and launch the application (in the next turn of the event loop). A getter failing, or invalid
+     * options, are a fatal exception.
+     * @param optionsGetter The function returning the options, or their promise.
+     * @returns The application class, to chain the other calls.
+     */
+    static run(optionsGetter: () => ApplicationOptions | Promise<ApplicationOptions>): typeof Application;
+    /**
+     * Schedule the launch for the next turn of the event loop, replacing the launch already scheduled.
+     * @returns The application class.
+     * @protected
+     */
+    protected static launch(): typeof Application;
+    /**
+     * Handle an uncaught exception: the handlers of `onUncaughtException()`, else a warning of the logger (the console
+     * when the logger cannot be got).
+     * @param error The uncaught error.
+     * @returns Resolves once handled.
+     * @protected
+     */
+    protected static processUncaughtException(error: Error): Promise<void>;
+    /**
+     * Handle a fatal exception: the handler of `onFatalException()`, else an error of the logger (the console when the
+     * logger cannot be got), then the process exits (with the code 1 by default, as Node.js on an uncaught exception):
+     * the application cannot run, and the objects already created (a server listening, a connection) would keep the
+     * process alive. Ignored once the process is ending.
+     * @param error The error.
+     * @protected
+     */
+    protected static processFatalException(error: Error): void;
+    /**
+     * End the application gracefully on the signals: its exit (the done handlers, the requests running complete, the
+     * objects destroyed, the code 0); a second signal, or a signal received while it launches, ends the process at
+     * once with the code 128 + the signal number.
+     * @param signals The signals to listen to.
+     * @protected
+     */
+    protected static listenShutdownSignals(signals: NodeJS.Signals[]): void;
+    /**
+     * Launch the application: environment variables, aliases, options (or the database migration command given by the
+     * `MIGRATION_*` environment variables), then the application created in a new root container.
+     * @returns The application, once its bootstrap has completed.
+     * @protected
+     */
+    protected static launchApplication(): Promise<Application>;
+    /**
+     * The class reading the application options, which also applies its identity (ID, name, time zone, mode).
+     * @protected
+     */
+    protected ConfigLoader: typeof ApplicationConfigLoader;
+    /**
+     * The application's own declarations: a copy of the preset options (see `preset()`), the options given to `run()`
+     * being merged over them.
+     * @protected
+     */
+    protected options: Partial<ApplicationOptions>;
+    /**
+     * A copy of the preset options, for an application.
+     * @returns The copy.
+     * @protected
+     */
+    protected static copyPresetOptions(): ModuleOptions;
+    /**
+     * The logger of the application: its `log` component, or a console logger when it has none.
+     * @returns The logger.
+     * @protected
+     */
+    protected getLogger(): Promise<ILogger>;
+    /**
+     * The path alias manager, shared by the process: `resolve()` replaces the aliases in a path, `get()`, `set()`,
+     * `has()` and `list()` manage them.
+     */
+    get alias(): Alias;
+    /**
+     * The ID of the application (its `id` option), readable before the application is created; "Unknown" until its
+     * options are loaded.
+     */
+    static get appId(): string;
+    /**
+     * The name of the application (its `name` option), readable before the application is created; "Unknown" until
+     * its options are loaded.
+     */
+    static get appName(): string;
+    /**
+     * The ID of the application (its `id` option).
+     */
+    get appId(): string;
+    /**
+     * The name of the application (its `name` option).
+     */
+    get appName(): string;
+    /**
+     * The time zone of the application: its `timezone` option, or the system's (`auto`); the `TZ` environment
+     * variable.
+     */
+    get timezone(): string;
+    /**
+     * The time the process has been running, in seconds (rounded down).
+     */
+    get uptime(): number;
+    /**
+     * Exit the application gracefully: the `onDone()` handlers run, the entrypoints stop (the requests running
+     * complete), the objects are destroyed, then the process exits with the code. Returns at once.
+     * @param exitCode The exit code of the process (0 for success).
+     */
+    exit(exitCode: number): void;
+    /**
+     * Exit the process at once with the code 2, without the done handlers nor the teardown of the objects.
+     * @param force true.
+     */
+    exit(force: true): void;
+}