@lakutata/core 1.0.59 → 3.0.0-beta.0

package/dist/cjs/lib/foundation/Exception.js

@@ -0,0 +1,165 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Exception = void 0;
+exports.exceptionParams = exceptionParams;
+const node_util_1 = require("node:util");
+const BasicInfo_js_1 = require("./BasicInfo.js");
+const Templating_1 = require("@lakutata/utils/Templating");
+const As_1 = require("@lakutata/utils/As");
+const CamelCase_1 = require("@lakutata/utils/CamelCase");
+const DevNull_1 = require("@lakutata/utils/DevNull");
+/**
+ * The placeholders of util.format() consuming an argument
+ */
+const PLACEHOLDERS = 'sdifjoOc';
+/**
+ * Format the placeholders of a message as util.format() of Node.js (%s, %d, %i, %f, %j, %o, %O, %c, %%): an unknown
+ * placeholder, a placeholder without argument and a % alone are kept; the arguments left are not appended (they are
+ * the data of the templates too); a placeholder its argument cannot be formatted by (%j of a bigint) is kept, the
+ * creation of an exception never throws
+ * @param template
+ * @param args
+ */
+function format(template, ...args) {
+    if (!args.length)
+        return template;
+    let result = '';
+    let lastPosition = 0;
+    let argument = 0;
+    for (let i = 0; i < template.length - 1; i++) {
+        if (template[i] !== '%')
+            continue;
+        const placeholder = template[++i];
+        if (argument < args.length && PLACEHOLDERS.includes(placeholder)) {
+            let formatted;
+            try {
+                formatted = placeholder === 'c' ? '' : (0, node_util_1.format)(`%${placeholder}`, args[argument]);
+            }
+            catch {
+                formatted = `%${placeholder}`;
+            }
+            result += template.slice(lastPosition, i - 1) + formatted;
+            argument++;
+            lastPosition = i + 1;
+        }
+        else if (placeholder === '%') {
+            result += template.slice(lastPosition, i);
+            lastPosition = i + 1;
+        }
+    }
+    return result + template.slice(lastPosition);
+}
+/**
+ * The parameters of the template of the message of an exception
+ */
+const PARAMS = Symbol('EXCEPTION.PARAMS');
+/**
+ * Read the parameters an exception's message template was formatted with (`new XxxException('Order {id} not found',
+ * {id: 1})`), to translate the message into another language with the same values.
+ * @param exception The error to read; any error is accepted.
+ * @returns The object given as the single parameter, the parameters as an array when several (or a single non-object
+ * one) were given, or undefined when the exception was created without parameters or is not an {@link Exception}.
+ * @example
+ * ```typescript
+ * import {Exception, exceptionParams} from 'lakutata'
+ *
+ * class OrderNotFoundException extends Exception {
+ *     public errno: string = 'E_ORDER_NOT_FOUND'
+ * }
+ *
+ * const error: OrderNotFoundException = new OrderNotFoundException('Order {id} not found', {id: 1})
+ * console.log(error.message) //Order 1 not found
+ * console.log(exceptionParams(error)) //{id: 1}
+ * ```
+ */
+function exceptionParams(exception) {
+    return exception[PARAMS];
+}
+/**
+ * The base class of the framework's exceptions, and of the applications' own: extend it, set its `errno` and, for the
+ * errors sent to clients, its `statusCode`. The entrypoints send `errno`, `errMsg` and `statusCode` to the clients, and
+ * the HTTP adapters reply with `statusCode`.
+ *
+ * The message is built from the constructor arguments:
+ * - `new XxxException('Order {id} not found', {id: 1})`: a template, its `{name}` placeholders filled from an object, or
+ *   its `{0}`, `{1}` placeholders from the parameters given one by one (`new XxxException('{0} of {1}', a, b)`) or from
+ *   an array; the `util.format()` placeholders (`%s`, `%d`, `%j`…) are filled from the parameters too. A missing value
+ *   leaves its placeholder in the message; building the message never throws.
+ * - `new XxxException('Order not found')`: the message as given.
+ * - `new XxxException(error)`: the message of another error.
+ * - `new XxxException()`: a message made from the class name.
+ *
+ * The template parameters are kept for the translation of the message, see {@link exceptionParams}.
+ * @example
+ * ```typescript
+ * import {Exception} from 'lakutata'
+ *
+ * export class OrderNotFoundException extends Exception {
+ *     public errno: string = 'E_ORDER_NOT_FOUND'
+ *
+ *     public readonly statusCode: number = 404
+ * }
+ *
+ * export function findOrder(id: number): never {
+ *     throw new OrderNotFoundException('Order {id} not found', {id: id})
+ * }
+ * ```
+ */
+class Exception extends Error {
+    constructor(a, ...b) {
+        super();
+        /**
+         * The ID of the application the exception was created in, "Unknown" before the application's options are loaded.
+         */
+        this.appId = (0, BasicInfo_js_1.getAppId)();
+        /**
+         * The name of the application the exception was created in, "Unknown" before the application's options are loaded.
+         */
+        this.appName = (0, BasicInfo_js_1.getAppName)();
+        /**
+         * The HTTP status the HTTP entrypoints reply with when the exception fails a request; a subclass overrides it
+         * (404 for a missing resource…).
+         * @default 500
+         */
+        this.statusCode = 500;
+        if (b.length) {
+            const template = a;
+            const templatingArgs = b.length > 1 ? b : b[0];
+            //Kept for the translations of the message, not an enumerable property (the errors sent are not changed)
+            Object.defineProperty(this, PARAMS, { value: b.length > 1 || typeof b[0] !== 'object' || b[0] === null ? b : b[0], enumerable: false });
+            try {
+                this.message = (0, Templating_1.templating)(template, templatingArgs, { ignoreMissing: true });
+            }
+            catch (e) {
+                this.message = template;
+                (0, DevNull_1.DevNull)(e);
+            }
+            this.message = format(this.message, ...b);
+        }
+        else if (a) {
+            if (typeof (a) === 'string') {
+                //Error message
+                this.message = a;
+            }
+            else {
+                //Error instance
+                this.message = (0, As_1.As)(a).message;
+            }
+        }
+        else {
+            //Empty message
+            const message = (0, CamelCase_1.camelCase)(this.name).toLowerCase();
+            this.message = `${message.charAt(0).toUpperCase()}${message.slice(1)}`;
+        }
+        this.errMsg = this.message;
+        this.err = this.name;
+    }
+    /**
+     * The name of the exception: the name of its class.
+     * @returns The class name.
+     */
+    get name() {
+        return this.constructor.name;
+    }
+}
+exports.Exception = Exception;

package/dist/cjs/lib/foundation/LifecycleErrorReporter.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A reporter of the errors of the lifecycle of the objects which have no caller to throw them to: the errors of a
+ * cascaded destruction (owner or scope teardown) and of the launched() hooks
+ */
+export type LifecycleErrorReporter = (error: Error, message: string) => void;
+/**
+ * Set the reporter of the errors of the lifecycle of the objects, pass nothing to restore the default reporter
+ * (process warning)
+ * @param reporter
+ * @constructor
+ */
+export declare function setLifecycleErrorReporter(reporter?: LifecycleErrorReporter): void;
+/**
+ * Report an error raised by cascaded destruction
+ * @param error
+ * @param objectName name of the object whose teardown failed
+ * @constructor
+ */
+export declare function reportDestroyError(error: unknown, objectName?: string): void;
+/**
+ * Report an error raised by the launched() hook of an object
+ * @param error
+ * @param objectName
+ * @constructor
+ */
+export declare function reportLaunchedError(error: unknown, objectName: string): void;

package/dist/cjs/lib/foundation/LifecycleErrorReporter.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setLifecycleErrorReporter = setLifecycleErrorReporter;
+exports.reportDestroyError = reportDestroyError;
+exports.reportLaunchedError = reportLaunchedError;
+const ThrowWarning_js_1 = require("./ThrowWarning.js");
+const defaultLifecycleErrorReporter = (error, message) => {
+    (0, ThrowWarning_js_1.throwWarning)(`${message}: ${error.stack ? error.stack : error.message}`);
+};
+let lifecycleErrorReporter = defaultLifecycleErrorReporter;
+/**
+ * Set the reporter of the errors of the lifecycle of the objects, pass nothing to restore the default reporter
+ * (process warning)
+ * @param reporter
+ * @constructor
+ */
+function setLifecycleErrorReporter(reporter) {
+    lifecycleErrorReporter = reporter ? reporter : defaultLifecycleErrorReporter;
+}
+/**
+ * Flatten aggregated errors, keeping the message of every enclosing aggregate as context
+ * @param error
+ * @param context
+ */
+function flatten(error, context) {
+    if (error instanceof AggregateError)
+        return error.errors.flatMap((item) => flatten(item, error.message));
+    const item = error instanceof Error ? error : new Error(String(error));
+    return [context ? new Error(`${context}: ${item.message}`, { cause: item }) : item];
+}
+/**
+ * Report errors, a reporter failure never breaks the lifecycle
+ * @param errors
+ * @param message
+ */
+function report(errors, message) {
+    for (const error of errors) {
+        try {
+            lifecycleErrorReporter(error, message);
+        }
+        catch {
+            //A broken reporter must not break the lifecycle
+        }
+    }
+}
+/**
+ * Report an error raised by cascaded destruction
+ * @param error
+ * @param objectName name of the object whose teardown failed
+ * @constructor
+ */
+function reportDestroyError(error, objectName) {
+    const context = objectName && !(error instanceof AggregateError) ? `Failed to destroy object "${objectName}"` : undefined;
+    report(flatten(error, context), 'An error occurred while destroying an object');
+}
+/**
+ * Report an error raised by the launched() hook of an object
+ * @param error
+ * @param objectName
+ * @constructor
+ */
+function reportLaunchedError(error, objectName) {
+    report(flatten(error, `Failed to run the launched() hook of object "${objectName}"`), 'An error occurred in the launched() hook of an object');
+}

package/dist/cjs/lib/foundation/Packaging.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Tell whether the application runs packed: bundled by `lakutata package bundle`, or inside a single executable built by
+ * `lakutata package exe`.
+ * @returns `true` when packed, `false` when it runs from its sources or its build (in development).
+ * @example
+ * ```typescript
+ * import {isPackaged} from 'lakutata'
+ *
+ * //The updates are only checked by the released builds
+ * if (isPackaged()) console.log('Running the released build')
+ * ```
+ */
+export declare function isPackaged(): boolean;
+/**
+ * Get the directory of the resources of a packed application: the files declared by the `lakutata.resources` field of
+ * its package.json, at their `to` paths (extracted first when it runs in a single executable).
+ * @returns The absolute path of the directory, or `undefined` when the application does not run packed: it then locates
+ * its resources itself (in development, the directory they are built in).
+ * @example
+ * ```typescript
+ * import path from 'node:path'
+ * import {resourcesPath} from 'lakutata'
+ *
+ * //The web UI served by the application: its packed copy, or its build in development
+ * const resources: string | undefined = resourcesPath()
+ * const ui: string = resources ? path.join(resources, 'ui') : path.resolve('ui', 'dist')
+ * ```
+ */
+export declare function resourcesPath(): string | undefined;

package/dist/cjs/lib/foundation/Packaging.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isPackaged = isPackaged;
+exports.resourcesPath = resourcesPath;
+/**
+ * The global symbol the packed applications (the bundles and the executables of lakutata) are given by their first
+ * code: the directory of their resources
+ */
+const PACKAGED = Symbol.for('lakutata.packaged');
+/**
+ * Tell whether the application runs packed: bundled by `lakutata package bundle`, or inside a single executable built by
+ * `lakutata package exe`.
+ * @returns `true` when packed, `false` when it runs from its sources or its build (in development).
+ * @example
+ * ```typescript
+ * import {isPackaged} from 'lakutata'
+ *
+ * //The updates are only checked by the released builds
+ * if (isPackaged()) console.log('Running the released build')
+ * ```
+ */
+function isPackaged() {
+    return !!globalThis[PACKAGED];
+}
+/**
+ * Get the directory of the resources of a packed application: the files declared by the `lakutata.resources` field of
+ * its package.json, at their `to` paths (extracted first when it runs in a single executable).
+ * @returns The absolute path of the directory, or `undefined` when the application does not run packed: it then locates
+ * its resources itself (in development, the directory they are built in).
+ * @example
+ * ```typescript
+ * import path from 'node:path'
+ * import {resourcesPath} from 'lakutata'
+ *
+ * //The web UI served by the application: its packed copy, or its build in development
+ * const resources: string | undefined = resourcesPath()
+ * const ui: string = resources ? path.join(resources, 'ui') : path.resolve('ui', 'dist')
+ * ```
+ */
+function resourcesPath() {
+    return globalThis[PACKAGED]?.resources();
+}

package/dist/cjs/lib/foundation/ThrowWarning.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Throw warning message through process
+ * @param message
+ * @constructor
+ */
+export declare function throwWarning(message: string): boolean;

package/dist/cjs/lib/foundation/ThrowWarning.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.throwWarning = throwWarning;
+class Warning extends Error {
+    get name() {
+        return this.constructor.name;
+    }
+}
+/**
+ * Throw warning message through process
+ * @param message
+ * @constructor
+ */
+function throwWarning(message) {
+    return process.emit('warning', new Warning(message));
+}

package/dist/cjs/lib/helpers/internal/WithCause.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Set the cause of an exception (the error it wraps) and return the exception
+ * @param exception
+ * @param cause
+ */
+export declare function withCause<T extends Error>(exception: T, cause: unknown): T;

package/dist/cjs/lib/helpers/internal/WithCause.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.withCause = withCause;
+/**
+ * Set the cause of an exception (the error it wraps) and return the exception
+ * @param exception
+ * @param cause
+ */
+function withCause(exception, cause) {
+    exception.cause = cause;
+    return exception;
+}

package/dist/cjs/lib/ioc/ConstructorSymbol.d.ts

@@ -0,0 +1,3 @@
+import { IConstructor } from '../../interfaces/IConstructor.js';
+export declare function constructorSymbol<T>(constructor: IConstructor<T>): symbol;
+export declare function resolveConstructorNameBySymbol(symbol: symbol): string | symbol;

package/dist/cjs/lib/ioc/ConstructorSymbol.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.constructorSymbol = constructorSymbol;
+exports.resolveConstructorNameBySymbol = resolveConstructorNameBySymbol;
+const DIMetadataKey_js_1 = require("../../constants/DIMetadataKey.js");
+const node_crypto_1 = require("node:crypto");
+const symbolConstructorMap = new Map();
+function constructorSymbol(constructor) {
+    if (!Reflect.hasOwnMetadata(DIMetadataKey_js_1.DI_TARGET_CONSTRUCTOR_SYMBOL, constructor)) {
+        const uuidSymbol = Symbol((0, node_crypto_1.randomUUID)());
+        symbolConstructorMap.set(uuidSymbol, constructor.name);
+        Reflect.defineMetadata(DIMetadataKey_js_1.DI_TARGET_CONSTRUCTOR_SYMBOL, uuidSymbol, constructor);
+    }
+    return Reflect.getOwnMetadata(DIMetadataKey_js_1.DI_TARGET_CONSTRUCTOR_SYMBOL, constructor);
+}
+function resolveConstructorNameBySymbol(symbol) {
+    const realName = symbolConstructorMap.get(symbol);
+    if (realName)
+        return realName;
+    return symbol;
+}

package/dist/cjs/lib/ioc/DependencyInjectionContainer.d.ts

@@ -0,0 +1,178 @@
+import { type LifetimeType } from './Lifetime.js';
+import { GlobWithOptions } from './ListModules.js';
+import { LoadModulesOptions } from './LoadModules.js';
+import { BuildResolverOptions, Constructor, Resolver } from './Resolvers.js';
+/**
+ * The container returned from createContainer has some methods and properties.
+ * @interface IDependencyInjectionContainer
+ */
+export interface IDependencyInjectionContainer<Cradle extends object = any> {
+    /**
+     * Options the container was configured with.
+     */
+    options: ContainerOptions;
+    /**
+     * The proxy injected when using `PROXY` injection mode.
+     * Can be used as-is.
+     */
+    readonly cradle: Cradle;
+    /**
+     * Getter for the rolled up registrations that merges the container family tree.
+     */
+    readonly registrations: RegistrationHash;
+    /**
+     * Resolved modules cache.
+     */
+    readonly cache: Map<string | symbol, CacheEntry>;
+    /**
+     * Creates a scoped container with this one as the parent.
+     */
+    createScope<T extends object = object>(): IDependencyInjectionContainer<Cradle & T>;
+    /**
+     * Used by `util.inspect`.
+     */
+    inspect(depth: number, opts?: any): string;
+    /**
+     * Binds `lib/loadModules` to this container, and provides
+     * real implementations of its dependencies.
+     *
+     * Additionally, any modules using the `dependsOn` API
+     * will be resolved.
+     *
+     * @see src/load-modules.ts documentation.
+     */
+    loadModules<ESM extends boolean = false>(globPatterns: Array<string | GlobWithOptions>, options?: LoadModulesOptions<ESM>): ESM extends false ? this : Promise<this>;
+    /**
+     * Adds a single registration that using a pre-constructed resolver.
+     */
+    register<T>(name: string | symbol, registration: Resolver<T>): this;
+    /**
+     * Pairs resolvers to registration names and registers them.
+     */
+    register(nameAndRegistrationPair: NameAndRegistrationPair<Cradle>): this;
+    /**
+     * Resolves the registration with the given name.
+     *
+     * @param  {string} name
+     * The name of the registration to resolve.
+     *
+     * @return {*}
+     * Whatever was resolved.
+     */
+    resolve<K extends keyof Cradle>(name: K, resolveOptions?: ResolveOptions): Cradle[K];
+    /**
+     * Resolves the registration with the given name.
+     *
+     * @param  {string} name
+     * The name of the registration to resolve.
+     *
+     * @return {*}
+     * Whatever was resolved.
+     */
+    resolve<T>(name: string | symbol, resolveOptions?: ResolveOptions): T;
+    /**
+     * Checks if the registration with the given name exists.
+     *
+     * @param {string | symbol} name
+     * The name of the registration to resolve.
+     *
+     * @return {boolean}
+     * Whether or not the registration exists.
+     */
+    hasRegistration(name: string | symbol): boolean;
+    /**
+     * Recursively gets a registration by name if it exists in the
+     * current container or any of its' parents.
+     *
+     * @param name {string | symbol} The registration name.
+     */
+    getRegistration<K extends keyof Cradle>(name: K): Resolver<Cradle[K]> | null;
+    /**
+     * Recursively gets a registration by name if it exists in the
+     * current container or any of its' parents.
+     *
+     * @param name {string | symbol} The registration name.
+     */
+    getRegistration<T = unknown>(name: string | symbol): Resolver<T> | null;
+    /**
+     * Given a resolver, class or function, builds it up and returns it.
+     * Does not cache it, this means that any lifetime configured in case of passing
+     * a resolver will not be used.
+     *
+     * @param {Resolver|Class|Function} targetOrResolver
+     * @param {ResolverOptions} opts
+     */
+    build<T>(targetOrResolver: ClassOrFunctionReturning<T> | Resolver<T>, opts?: BuildResolverOptions<T>): T;
+    /**
+     * Disposes this container and it's children, calling the disposer
+     * on all disposable registrations and clearing the cache.
+     * Only applies to registrations with `SCOPED` or `SINGLETON` lifetime.
+     */
+    dispose(): Promise<void>;
+}
+/**
+ * Optional resolve options.
+ */
+export interface ResolveOptions {
+    /**
+     * If `true` and `resolve` cannot find the requested dependency,
+     * returns `undefined` rather than throwing an error.
+     */
+    allowUnregistered?: boolean;
+}
+/**
+ * Cache entry.
+ */
+export interface CacheEntry<T = any> {
+    /**
+     * The resolver that resolved the value.
+     */
+    resolver: Resolver<T>;
+    /**
+     * The resolved value.
+     */
+    value: T;
+}
+/**
+ * Register a Registration
+ * @interface NameAndRegistrationPair
+ */
+export type NameAndRegistrationPair<T> = {
+    [U in keyof T]?: Resolver<T[U]>;
+};
+/**
+ * Function that returns T.
+ */
+export type FunctionReturning<T> = (...args: Array<any>) => T;
+/**
+ * A class or function returning T.
+ */
+export type ClassOrFunctionReturning<T> = FunctionReturning<T> | Constructor<T>;
+/**
+ * The options for the createContainer function.
+ */
+export interface ContainerOptions {
+    require?: (id: string) => any;
+    strict?: boolean;
+}
+/**
+ * Contains a hash of registrations where the name is the key.
+ */
+export type RegistrationHash = Record<string | symbol | number, Resolver<any>>;
+export type ResolutionStack = Array<{
+    name: string | symbol;
+    lifetime: LifetimeType;
+}>;
+/**
+ * Creates an DI container instance.
+ *
+ * @param {Function} options.require The require function to use. Defaults to require.
+ *
+ * Dependencies are always provided through the cradle proxy.
+ *
+ * @param {boolean} options.strict True if the container should run in strict mode with additional
+ * validation for resolver configuration correctness. Defaults to false.
+ *
+ * @return {IDependencyInjectionContainer<T>} The container.
+ */
+export declare function createContainer<T extends object = any>(options?: ContainerOptions): IDependencyInjectionContainer<T>;