@lakutata/core 1.0.60 → 3.0.0-beta.0

package/dist/types/lib/foundation/EndProcess.d.ts

@@ -0,0 +1,14 @@
+/**
+ * End the process with a code: it exits by itself, its work done (process.exitCode), else it is ended after a moment
+ * (an object keeping it running). Ended by process.exit at once, node crashes on Windows while the connections of fetch
+ * close (libuv: UV_HANDLE_CLOSING); the process exits by itself as soon as they are closed. The code given first is the
+ * exit code: the code still running once the application is destroyed (its launch going on after its exit) does not
+ * change it
+ * @param code
+ * @param grace the time it is given to exit by itself
+ */
+export declare function endProcess(code: number, grace?: number): void;
+/**
+ * Whether the process is ending: the errors of the code still running are not the ones of the application
+ */
+export declare function isEnding(): boolean;

package/dist/types/lib/foundation/Exception.d.ts

@@ -0,0 +1,88 @@
+/**
+ * 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}
+ * ```
+ */
+export declare function exceptionParams(exception: Error): Record<string, unknown> | unknown[] | undefined;
+/**
+ * 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})
+ * }
+ * ```
+ */
+export declare abstract class Exception extends Error {
+    /**
+     * The error number or code identifying the error to the clients and the logs (`'E_ORDER_NOT_FOUND'`); each
+     * subclass sets it.
+     */
+    abstract errno: number | string;
+    /**
+     * The ID of the application the exception was created in, "Unknown" before the application's options are loaded.
+     */
+    readonly appId: string;
+    /**
+     * The name of the application the exception was created in, "Unknown" before the application's options are loaded.
+     */
+    readonly appName: string;
+    /**
+     * The formatted message, a copy of `message` kept as an own property (sent with the error by the entrypoints).
+     */
+    readonly errMsg: string;
+    /**
+     * The name of the exception's class (`'OrderNotFoundException'`), a copy of `name` kept as an own property.
+     */
+    readonly err: string;
+    /**
+     * 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
+     */
+    readonly statusCode: number;
+    constructor(template: string, ...params: any[]);
+    constructor(message: string);
+    constructor(error: Error);
+    constructor();
+    /**
+     * The name of the exception: the name of its class.
+     * @returns The class name.
+     */
+    get name(): string;
+}

package/dist/types/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/types/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/types/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/types/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/types/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/types/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>;

package/dist/types/lib/ioc/Errors.d.ts

@@ -0,0 +1,59 @@
+import { ResolutionStack } from './DependencyInjectionContainer.js';
+import { DependencyInjectionException } from '../../exceptions/di/DependencyInjectionException.js';
+/**
+ * 可扩展错误类
+ */
+export declare class ExtendableError extends DependencyInjectionException {
+    /**
+     * 可扩展错误类构造函数
+     * @param message
+     */
+    constructor(message: string);
+}
+/**
+ * 抛出的错误，用于指示类型不匹配
+ */
+export declare class DependencyInjectionTypeError extends ExtendableError {
+    /**
+     * 构造函数，接受函数名称、期望的类型和给定的类型，以生成错误
+     * @param funcDescription
+     * @param paramName
+     * @param expectedType
+     * @param givenType
+     */
+    constructor(funcDescription: string, paramName: string, expectedType: string, givenType: any);
+    /**
+     * 断言给定的条件，否则抛出错误
+     * @param condition
+     * @param funcDescription
+     * @param paramName
+     * @param expectedType
+     * @param givenType
+     */
+    static assert<T>(condition: T, funcDescription: string, paramName: string, expectedType: string, givenType: any): NonNullable<T>;
+}
+/**
+ * 一个友好的错误类，以便我们可以进行 instanceof 检查
+ */
+export declare class DependencyInjectionResolutionError extends ExtendableError {
+    /**
+     * 构造函数，接受注册的模块和未解析的标记，以创建一条消息
+     * @param name
+     * @param resolutionStack
+     * @param message
+     */
+    constructor(name: string | symbol, resolutionStack: ResolutionStack, message?: string);
+}
+/**
+ * A nice error class, so we can do an instanceOf check.
+ */
+export declare class DependencyInjectionRegistrationError extends ExtendableError {
+    /**
+     * Constructor, takes the registered modules and unresolved tokens
+     * to create a message.
+     *
+     * @param {string|symbol} name
+     * The name of the module that could not be registered.
+     */
+    constructor(name: string | symbol, message?: string);
+}

package/dist/types/lib/ioc/Lifetime.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Lifetime type.
+ */
+export type LifetimeType = 'SINGLETON' | 'TRANSIENT' | 'SCOPED';
+/**
+ * Lifetime types.
+ */
+export declare const Lifetime: Record<LifetimeType, LifetimeType>;
+/**
+ * Returns true if and only if the first lifetime is strictly longer than the second.
+ */
+export declare function isLifetimeLonger(a: LifetimeType, b: LifetimeType): boolean;

package/dist/types/lib/ioc/ListModules.d.ts

@@ -0,0 +1,42 @@
+import { BuildResolverOptions } from './Resolvers.js';
+import { LifetimeType } from './Lifetime.js';
+/**
+ * The options when invoking listModules().
+ * @interface ListModulesOptions
+ */
+export interface ListModulesOptions {
+    cwd?: string;
+    glob?: (pattern: string, options: {
+        cwd: string;
+    }) => string[];
+}
+/**
+ * An object containing the module name and path (full path to module).
+ *
+ * @interface ModuleDescriptor
+ */
+export interface ModuleDescriptor {
+    name: string;
+    path: string;
+    opts: any;
+}
+/**
+ * A glob pattern with associated registration options.
+ */
+export type GlobWithOptions = [string] | [string, BuildResolverOptions<any> | LifetimeType];
+/**
+ * Returns a list of {name, path} pairs,
+ * where the name is the module name, and path is the actual
+ * full path to the module.
+ *
+ * @param  {String|Array<String>} globPatterns
+ * The glob pattern as a string or an array of strings.
+ *
+ * @param  {String} opts.cwd
+ * Current working directory, used for resolving filepaths.
+ * Defaults to `process.cwd()`.
+ *
+ * @return {[{name, path}]}
+ * An array of objects with the module names and paths.
+ */
+export declare function listModules(globPatterns: string | Array<string | GlobWithOptions>, opts?: ListModulesOptions): ModuleDescriptor[];

package/dist/types/lib/ioc/LoadModuleNative.d.ts

@@ -0,0 +1 @@
+export function importModule(path: any): Promise<any>;

package/dist/types/lib/ioc/LoadModules.d.ts

@@ -0,0 +1,49 @@
+import { IDependencyInjectionContainer } from './DependencyInjectionContainer.js';
+import { GlobWithOptions, ModuleDescriptor, listModules } from './ListModules.js';
+import { BuildResolverOptions } from './Resolvers.js';
+/**
+ * Metadata of the module as well as the loaded module itself.
+ * @interface LoadedModuleDescriptor
+ */
+export interface LoadedModuleDescriptor extends ModuleDescriptor {
+    value: unknown;
+}
+/**
+ * The options when invoking loadModules().
+ * @interface LoadModulesOptions
+ */
+export interface LoadModulesOptions<ESM extends boolean = false> {
+    cwd?: string;
+    formatName?: NameFormatter | BuiltInNameFormatters;
+    resolverOptions?: BuildResolverOptions<any>;
+    esModules?: ESM;
+}
+/**
+ * Name formatting options when using loadModules().
+ * @type BuiltInNameFormatters
+ */
+export type BuiltInNameFormatters = 'camelCase';
+/**
+ * Takes in the filename of the module being loaded as well as the module descriptor,
+ * and returns a string which is used to register the module in the container.
+ *
+ * `descriptor.name` is the same as `name`.
+ *
+ * @type {NameFormatter}
+ */
+export type NameFormatter = (name: string, descriptor: LoadedModuleDescriptor) => string;
+/**
+ * Dependencies for `loadModules`
+ */
+export interface LoadModulesDeps {
+    listModules: typeof listModules;
+    container: IDependencyInjectionContainer;
+    require(path: string): any | Promise<any>;
+}
+/**
+ * The list of loaded modules
+ */
+export interface LoadModulesResult {
+    loadedModules: Array<ModuleDescriptor>;
+}
+export declare function loadModules<ESM extends boolean = false>(dependencies: LoadModulesDeps, globPatterns: string | Array<string | GlobWithOptions>, opts?: LoadModulesOptions<ESM>): ESM extends true ? Promise<LoadModulesResult> : LoadModulesResult;

package/dist/types/lib/ioc/ObjectLifetime.d.ts

@@ -0,0 +1,22 @@
+import { IConstructor } from '../../interfaces/IConstructor.js';
+import { LifetimeType } from './Lifetime.js';
+/**
+ * Get Object's lifetime
+ * @param target
+ * @constructor
+ */
+export declare function getObjectLifetime<ClassConstructor extends IConstructor>(target: ClassConstructor): LifetimeType;
+/**
+ * Get whether Object's lifetime is locked
+ * @param target
+ * @constructor
+ */
+export declare function getObjectLifetimeLocked<ClassConstructor extends IConstructor>(target: ClassConstructor): boolean;
+/**
+ * Set Object's lifetime
+ * @param target
+ * @param lifetime
+ * @param lock
+ * @constructor
+ */
+export declare function setObjectLifetime<ClassConstructor extends IConstructor>(target: ClassConstructor, lifetime: LifetimeType, lock?: boolean): ClassConstructor;

package/dist/types/lib/ioc/ObjectWeakRefs.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Get object weak refs
+ * @param target
+ * @constructor
+ */
+export declare function getObjectWeakRefs<ObjectInstance extends object>(target: any): Set<WeakRef<ObjectInstance>>;
+/**
+ * Append object weak refs
+ * @param target
+ * @param instance
+ * @constructor
+ */
+export declare function appendObjectWeakRefs<ObjectInstance extends object>(target: any, instance: ObjectInstance): void;
+/**
+ * Clear transient object weak refs
+ * @param target
+ * @constructor
+ */
+export declare function clearObjectWeakRefs(target: any): void;