@lakutata/core 1.0.60 → 3.0.0-beta.0

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

@@ -0,0 +1,31 @@
+/**
+ * The command of the migrations of the databases given to the application by its environment
+ */
+export type MigrationCommand = {
+    /**
+     * generate (MIGRATION_GENERATE, the directory of the migrations), run (MIGRATION_RUN), revert (MIGRATION_REVERT) or
+     * show (MIGRATION_SHOW)
+     */
+    action: 'generate' | 'run' | 'revert' | 'show';
+    /**
+     * The directory of the migrations generated
+     */
+    path?: string;
+    /**
+     * The database of the command (MIGRATION_DATABASE, the name of its component or provider), all by default
+     */
+    database?: string;
+    /**
+     * The transactions of the migrations run or reverted (MIGRATION_TRANSACTION: all, none or each)
+     */
+    transaction?: 'all' | 'none' | 'each';
+    /**
+     * The migrations marked as run or reverted without being executed (MIGRATION_FAKE)
+     */
+    fake: boolean;
+};
+/**
+ * The command of the migrations given by the environment, its variables named in any case
+ * @param env
+ */
+export declare function readMigrationCommand(env: NodeJS.ProcessEnv): MigrationCommand | undefined;

package/dist/cjs/lib/app/MigrationCommand.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readMigrationCommand = readMigrationCommand;
+/**
+ * The command of the migrations given by the environment, its variables named in any case
+ * @param env
+ */
+function readMigrationCommand(env) {
+    const variables = new Map();
+    for (const name in env)
+        if (name.toUpperCase().startsWith('MIGRATION_') && env[name] !== undefined)
+            variables.set(name.toUpperCase(), env[name]);
+    const flag = (name) => ['1', 'true', 'yes'].includes((variables.get(name) ?? '').toLowerCase());
+    const transaction = variables.get('MIGRATION_TRANSACTION') || undefined;
+    if (transaction !== undefined && transaction !== 'all' && transaction !== 'none' && transaction !== 'each')
+        throw new Error(`MIGRATION_TRANSACTION is all, none or each, not "${transaction}"`);
+    const common = {
+        database: variables.get('MIGRATION_DATABASE') || undefined,
+        transaction: transaction,
+        fake: flag('MIGRATION_FAKE')
+    };
+    if (variables.get('MIGRATION_GENERATE'))
+        return { action: 'generate', path: variables.get('MIGRATION_GENERATE'), ...common };
+    if (flag('MIGRATION_RUN'))
+        return { action: 'run', ...common };
+    if (flag('MIGRATION_REVERT'))
+        return { action: 'revert', ...common };
+    if (flag('MIGRATION_SHOW'))
+        return { action: 'show', ...common };
+    return undefined;
+}

package/dist/cjs/lib/base/BaseObject.d.ts

@@ -0,0 +1,343 @@
+import { AsyncConstructor } from './async-constructor/AsyncConstructor.js';
+import { IBaseObjectConstructor } from '../../interfaces/IBaseObjectConstructor.js';
+import { Module } from '../core/Module.js';
+/**
+ * Internal init function symbol
+ */
+export declare const __init: unique symbol;
+/**
+ * Internal destroy function symbol
+ */
+export declare const __destroy: unique symbol;
+/**
+ * Symbol of the method that makes a destroyed object ready to be initialized again (reload)
+ */
+export declare const __revive: unique symbol;
+/**
+ * Anonymous ID symbol, the default id value if object's id not defined in runtime
+ */
+export declare const anonymousId: symbol;
+/**
+ * The base class of every object managed by the container (the {@link Provider}, {@link Component}, {@link Module} and
+ * {@link Application} classes extend it). Extend it for a plain object; its lifetime is `@Transient`: a new instance
+ * each time it is requested.
+ *
+ * An object is never created with `new`: the container creates it (`getObject()`, `buildObject()`, the module options),
+ * asynchronously: its `@Inject` properties are resolved, its `@Configurable` properties get their configured values
+ * (validated and transformed by their schemas; a property not configured keeps its initializer, else the default of
+ * its schema), then its `init()` runs, then its `startup()` (the object is given to its requesters once started, except
+ * to the call chain of its startup). Once its application has launched, its `launched()` runs. At its teardown
+ * (`dispose()`, or the teardown of the object, scope or application which created it) its `beforeDestroy()` runs, then
+ * the objects it created are destroyed, then its `destroy()` runs. Each object owns a container: the objects it
+ * creates are destroyed with it.
+ * @example
+ * ```typescript
+ * import {BaseObject, Container, DTO} from 'lakutata'
+ * import {Configurable} from 'lakutata/decorator/di'
+ *
+ * class Counter extends BaseObject {
+ *     @Configurable(DTO.Number().integer().min(0))
+ *     protected readonly start: number = 0
+ *
+ *     #value: number = 0
+ *
+ *     protected async init(): Promise<void> {
+ *         this.#value = this.start
+ *     }
+ *
+ *     public increment(): number {
+ *         return ++this.#value
+ *     }
+ * }
+ *
+ * const container: Container = new Container()
+ * const counter: Counter = await container.build(Counter, {start: 10})
+ * console.log(counter.increment()) //11
+ * await counter.dispose()
+ * ```
+ */
+export declare class BaseObject extends AsyncConstructor {
+    #private;
+    /**
+     * Called by the container only: an object is created through a container (see the class description), never with
+     * `new`.
+     * @param cradleProxy The container's resolution proxy.
+     */
+    constructor(cradleProxy: Record<string | symbol, any>);
+    /**
+     * The name of the class.
+     */
+    static get className(): string;
+    /**
+     * Whether the class accepts an option which is not one of its `@Configurable` properties (an option it reads with
+     * `getConfigurableRecords()`): the modules check the options of the objects they declare and warn of the options
+     * the classes do not accept. Override it in the classes reading options without configurable properties.
+     * @param name The option name.
+     * @param value The option value.
+     * @returns true when the option is accepted; false by default.
+     */
+    static acceptsOption(name: string, value: unknown): boolean;
+    /**
+     * The name of the object's class.
+     */
+    get className(): string;
+    /**
+     * The framework's initializer: injects the dependencies, applies the configured values, runs the hooks, then
+     * `init()`. Override `init()` instead.
+     * @param hooks The steps the framework's subclasses run before `init()`.
+     * @returns Resolves once the object is ready.
+     * @throws {ObjectDestroyedException} When the object has been destroyed (before or during its initialization).
+     * @protected
+     */
+    protected [__init](...hooks: (() => Promise<void>)[]): Promise<void>;
+    /**
+     * Make a destroyed object ready to be initialized again (its reload); its dependencies, destroyed with it, are
+     * injected again. Does nothing when the object is not destroyed.
+     * @throws {ObjectDestroyedException} When the parent's container has been destroyed (or is being destroyed).
+     * @protected
+     */
+    protected [__revive](): void;
+    /**
+     * The framework's destroyer: `beforeDestroy()`, the objects created by this object, the hooks, then `destroy()`;
+     * runs once whatever starts it. Override `beforeDestroy()` and `destroy()` instead.
+     * @param hooks The steps the framework's subclasses run before `destroy()`.
+     * @returns Resolves once the object is destroyed.
+     * @throws {Error} The error of `beforeDestroy()`, a hook or `destroy()` (an `AggregateError` when several fail), to
+     * the first caller only.
+     * @protected
+     */
+    protected [__destroy](...hooks: (() => Promise<void>)[]): Promise<void>;
+    /**
+     * Initialize the object, once its dependencies are injected and its configured values applied; override it. The
+     * object is returned to its requester once it completes; an error thrown here fails the object's creation.
+     * @returns Resolves once initialized.
+     * @protected
+     */
+    protected init(): Promise<void>;
+    /**
+     * Start the object's work once it is initialized and can be got by the other objects (listen on a port, start the
+     * adapters of an entrypoint); override it. The objects getting it (`getObject()`, `@Inject`, a bootstrap step, the
+     * container's `get()` and `set()`) wait until it completes, and fail with its error; but the objects got from
+     * within it, directly or through the objects they create, get the object at once (initialized, not started yet),
+     * so an object it gets may inject it. Its `launched()` runs once it completed (not when it failed); its teardown
+     * waits for it to end. A module's runs once its bootstrap ran (the application's, once it launched). The name of
+     * the hook is `startup` so that the classes having a `start()` method of their own (a container of Docker) are not
+     * started by the framework.
+     * @returns Resolves once the object started.
+     * @protected
+     * @example
+     * ```typescript
+     * import {createServer, type Server} from 'node:http'
+     * import {Component} from 'lakutata'
+     *
+     * export class StatusServer extends Component {
+     *     #server: Server = createServer((_request, response): void => void response.end('ok'))
+     *
+     *     //The objects getting the server get it listening; a port in use fails them
+     *     protected async startup(): Promise<void> {
+     *         await new Promise<void>((resolve, reject): void => {
+     *             this.#server.once('error', reject).listen(8080, resolve)
+     *         })
+     *     }
+     *
+     *     protected async destroy(): Promise<void> {
+     *         await new Promise((resolve): unknown => this.#server.close(resolve))
+     *     }
+     * }
+     * ```
+     */
+    protected startup(): Promise<void>;
+    /**
+     * Called once the object's application has launched (its objects are created and its bootstrap ran), as the
+     * mounted hook of a Vue component: the object starts the work which needs the whole application; override it. An
+     * object created once the application has launched, or without application (in a bare container), is called right
+     * after its initialization; an object destroyed before is not called, a reloaded object is called again. Its errors
+     * are reported through the application's logger, they do not stop the application.
+     * @returns Resolves once the work is started; not awaited by the application.
+     * @protected
+     */
+    protected launched(): Promise<void>;
+    /**
+     * Called when the object's teardown starts, before the objects it created are destroyed (as the parent-first
+     * beforeDestroy of a Vue component): the object stops its work, such as receiving requests, while the objects it
+     * uses are still alive; override it. Called once per teardown, whatever starts it.
+     * @returns Resolves once the work is stopped.
+     * @protected
+     */
+    protected beforeDestroy(): Promise<void>;
+    /**
+     * Release the object's resources (connections, timers…), called once the objects it created are destroyed;
+     * override it. Its error is thrown to the caller of `dispose()`, or reported when a parent's teardown destroys it.
+     * @returns Resolves once released.
+     * @protected
+     */
+    protected destroy(): Promise<void>;
+    /**
+     * Get an object registered by its class, from this object's container or its parents (the module's registrations,
+     * the application's), as {@link Container.get}. The objects it creates are destroyed with this object.
+     * @param constructor The class the object was registered with (or an `@Autoload` class).
+     * @param configurableRecords The options of the object (the values of its `@Configurable` properties and the options
+     * it reads), merged over the ones it was registered with. Ignored, with a warning outside production, when the
+     * cached singleton or scoped instance already exists; a scoped object requested with options is a new instance
+     * owned by this object.
+     * @returns The object, once created and initialized.
+     * @throws {ObjectDestroyedException} When this object has been destroyed.
+     * @throws {Error} When nothing is registered under it, or the object fails to be created.
+     * @protected
+     */
+    protected getObject<T extends BaseObject>(constructor: IBaseObjectConstructor<T>, configurableRecords?: Record<string, any>): Promise<T>;
+    /**
+     * Get an object registered under a name (its key in the module options), as {@link BaseObject.getObject} by class.
+     * @param name The registration name.
+     * @param configurableRecords The options of the object (the values of its `@Configurable` properties and the options
+     * it reads), merged over the ones it was registered with. Ignored, with a warning outside production, when the
+     * cached singleton or scoped instance already exists; a scoped object requested with options is a new instance
+     * owned by this object.
+     * @returns The object, once created and initialized.
+     * @throws {ObjectDestroyedException} When this object has been destroyed.
+     * @throws {Error} When nothing is registered under it, or the object fails to be created.
+     * @protected
+     */
+    protected getObject<T extends BaseObject>(name: string, configurableRecords?: Record<string, any>): Promise<T>;
+    /**
+     * Get an object registered under a symbol, as {@link BaseObject.getObject} by class.
+     * @param name The registration symbol.
+     * @param configurableRecords The options of the object (the values of its `@Configurable` properties and the options
+     * it reads), merged over the ones it was registered with. Ignored, with a warning outside production, when the
+     * cached singleton or scoped instance already exists; a scoped object requested with options is a new instance
+     * owned by this object.
+     * @returns The object, once created and initialized.
+     * @throws {ObjectDestroyedException} When this object has been destroyed.
+     * @throws {Error} When nothing is registered under it, or the object fails to be created.
+     * @protected
+     */
+    protected getObject<T extends BaseObject>(name: symbol, configurableRecords?: Record<string, any>): Promise<T>;
+    /**
+     * Get an object registered under a name or a symbol, as {@link BaseObject.getObject} by class.
+     * @param name The registration name or symbol.
+     * @param configurableRecords The options of the object (the values of its `@Configurable` properties and the options
+     * it reads), merged over the ones it was registered with. Ignored, with a warning outside production, when the
+     * cached singleton or scoped instance already exists; a scoped object requested with options is a new instance
+     * owned by this object.
+     * @returns The object, once created and initialized.
+     * @throws {ObjectDestroyedException} When this object has been destroyed.
+     * @throws {Error} When nothing is registered under it, or the object fails to be created.
+     * @protected
+     */
+    protected getObject<T extends BaseObject>(name: string | symbol, configurableRecords?: Record<string, any>): Promise<T>;
+    /**
+     * Get an object registered under a name, a symbol or by its class, as {@link BaseObject.getObject} by class.
+     * @param nameOrConstructor The registration name, symbol or class.
+     * @param configurableRecords The options of the object (the values of its `@Configurable` properties and the options
+     * it reads), merged over the ones it was registered with. Ignored, with a warning outside production, when the
+     * cached singleton or scoped instance already exists; a scoped object requested with options is a new instance
+     * owned by this object.
+     * @returns The object, once created and initialized.
+     * @throws {ObjectDestroyedException} When this object has been destroyed.
+     * @throws {Error} When nothing is registered under it, or the object fails to be created.
+     * @protected
+     */
+    protected getObject<T extends BaseObject>(nameOrConstructor: string | symbol | IBaseObjectConstructor<T>, configurableRecords?: Record<string, any>): Promise<T>;
+    /**
+     * Create a new object of a class without registering it, whatever its lifetime, as {@link Container.build}; it is
+     * destroyed with this object (unless disposed before).
+     * @param constructor The class, registered or not.
+     * @param configurableRecords The options of the object.
+     * @returns The new object, once created and initialized.
+     * @throws {ObjectDestroyedException} When this object has been destroyed.
+     * @throws {Error} When the object fails to be created.
+     * @protected
+     */
+    protected buildObject<T extends BaseObject>(constructor: IBaseObjectConstructor<T>, configurableRecords?: Record<string, any>): Promise<T>;
+    /**
+     * The options the object was created with, as they were given: the values of its configurable properties before
+     * their validation, and the options which are not configurable properties.
+     * @returns A copy of the options.
+     * @protected
+     */
+    protected getConfigurableRecords(): Record<string, any>;
+    /**
+     * The object which created this object (the module or component whose container created it).
+     * @returns The parent, or undefined for an object created by a container without owner (the root container).
+     * @protected
+     */
+    protected getParent(): BaseObject | undefined;
+    /**
+     * The nearest module among the object's parents (its module, or the application).
+     * @returns The module; undefined (despite the type) for an object created outside any module.
+     * @protected
+     */
+    protected getModule(): Module;
+    /**
+     * A random UUID identifying the instance.
+     */
+    get $uuid(): string;
+    /**
+     * The name the object was registered under (its key in the module options), or a symbol of its class for an object
+     * registered by its class or built without registration.
+     */
+    get $id(): string | symbol;
+    /**
+     * A symbol unique to the instance (made from its `$uuid`), created on first read.
+     */
+    get $symbol(): symbol;
+    /**
+     * Set a property of the object; the value is not validated, even for a `@Configurable` property.
+     * @param propertyKey The property name.
+     * @param value The value.
+     */
+    setProperty(propertyKey: string, value: any): void;
+    /**
+     * Read an own property of the object.
+     * @param propertyKey The property name.
+     * @param defaultValue The value returned when the object has no own property of this name.
+     * @returns The property value, or the default value.
+     */
+    getProperty<T = any>(propertyKey: string, defaultValue?: T): T;
+    /**
+     * Whether the object has an own property (not a method or accessor of its class) of this name or symbol.
+     * @param propertyKey The property name or symbol.
+     * @returns true when the property exists.
+     */
+    hasProperty(propertyKey: string | symbol): boolean;
+    /**
+     * The symbols of the object's own properties.
+     * @returns The symbols.
+     */
+    propertySymbols(): symbol[];
+    /**
+     * The names of the object's own properties (not its class's methods and accessors).
+     * @returns The names.
+     */
+    propertyNames(): string[];
+    /**
+     * Whether the object has a method of this name or symbol (a function of its class, not an own property).
+     * @param name The method name or symbol.
+     * @returns true when the method exists.
+     */
+    hasMethod(name: string | symbol): boolean;
+    /**
+     * Get a method bound to the object, to call it by name.
+     * @param name The method name or symbol.
+     * @param throwExceptionIfNotFound Throw when the method does not exist, instead of returning a function doing
+     * nothing; false by default.
+     * @returns The bound method, or a function doing nothing (returning undefined) when it does not exist.
+     * @throws {MethodNotFoundException} When the method does not exist and `throwExceptionIfNotFound` is true.
+     */
+    getMethod(name: string | symbol, throwExceptionIfNotFound?: boolean): (...args: any[]) => any | Promise<any>;
+    /**
+     * Destroy the object: its `beforeDestroy()`, the objects it created, then its `destroy()`. Calling it more than once
+     * destroys once. A disposed singleton or scoped object is dropped from its container, which creates a new one on
+     * the next request. Using a destroyed object (`getObject()`, `buildObject()`) throws an
+     * {@link ObjectDestroyedException}.
+     * @returns Resolves once the object is destroyed.
+     * @throws {Error} The error of the object's own `beforeDestroy()` or `destroy()` (an `AggregateError` when several
+     * fail); the errors of the objects it created are reported through the application's logger instead.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Dispose the object at the end of an `await using` block, as {@link BaseObject.dispose}.
+     * @returns Resolves once the object is destroyed.
+     */
+    [Symbol.asyncDispose](): Promise<void>;
+}