@lakutata/core 1.0.60 → 3.0.0-beta.0

package/dist/cjs/lib/base/internal/ObjectOptionsCheck.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkObjectOptions = checkObjectOptions;
+const LoadObjectOptions_js_1 = require("../../../options/LoadObjectOptions.js");
+const ObjectConfiguration_js_1 = require("./ObjectConfiguration.js");
+const DTO_js_1 = require("../../dto/DTO.js");
+const InvalidValueException_js_1 = require("../../../exceptions/dto/InvalidValueException.js");
+const InvalidObjectOptionsException_js_1 = require("../../../exceptions/di/InvalidObjectOptionsException.js");
+const ThrowWarning_js_1 = require("../../foundation/ThrowWarning.js");
+const As_1 = require("@lakutata/utils/As");
+/**
+ * The options of the declarations which are not options of the object
+ */
+const DECLARATION_OPTIONS = new Set(['class', 'id']);
+/**
+ * Check the options of the objects declared in a module, before any of them is created (an object never created is
+ * checked too): an invalid value of a configurable property is an error, an option which is not a configurable property
+ * and which the class does not accept (see BaseObject.acceptsOption()) is a warning. The values are validated as the
+ * objects validate them, without their transforms. The options not given are not checked (they may be given when the
+ * object is got), nor the properties validated asynchronously (by external rules), which the object validates
+ * @param loadOptions
+ * @constructor
+ */
+function checkObjectOptions(loadOptions) {
+    const errors = [];
+    const warnings = [];
+    for (const declaration of loadOptions) {
+        if (typeof declaration !== 'object' || !declaration || typeof declaration.class !== 'function')
+            continue;
+        const target = declaration.class;
+        const id = declaration[LoadObjectOptions_js_1.OBJECT_ID];
+        const object = typeof id === 'string' ? `"${id}" (${target.name})` : target.name;
+        const properties = (0, ObjectConfiguration_js_1.getObjectConfigurableProperties)((0, As_1.As)(target.prototype));
+        for (const name of Object.keys(declaration)) {
+            const value = declaration[name];
+            if (DECLARATION_OPTIONS.has(name) || value === undefined)
+                continue;
+            const property = properties.get(name);
+            if (!property) {
+                if (!target.acceptsOption(name, value))
+                    warnings.push(unknownOptionMessage(object, name, properties));
+                continue;
+            }
+            try {
+                DTO_js_1.DTO.validate(value, property.schema, { targetName: name });
+            }
+            catch (e) {
+                //Not an invalid value: a schema with external rules, which only the asynchronous validation runs
+                if (!(e instanceof InvalidValueException_js_1.InvalidValueException))
+                    continue;
+                errors.push(`The option "${name}" of ${object} is invalid: ${e.message}`);
+            }
+        }
+    }
+    warnings.forEach((warning) => (0, ThrowWarning_js_1.throwWarning)(warning));
+    if (errors.length)
+        throw new InvalidObjectOptionsException_js_1.InvalidObjectOptionsException(errors.join('\n'));
+}
+/**
+ * The warning of an option which is not a configurable property
+ * @param object
+ * @param name
+ * @param properties
+ * @constructor
+ */
+function unknownOptionMessage(object, name, properties) {
+    const names = [...properties.keys()].filter((key) => typeof key === 'string').sort();
+    const hint = names.length ? `its configurable properties: ${names.join(', ')}` : 'it has no configurable property';
+    return `The option "${name}" of ${object} is not a configurable property, it is ignored (${hint})`;
+}

package/dist/cjs/lib/base/internal/ObjectStartup.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Run the startup of an object, after its initialization: the objects getting it wait for its startup, except the
+ * call chain of its startup itself, which gets it at once (initialized, not started yet)
+ * @param object The object.
+ * @param startup Its startup.
+ * @returns The startup, its failure handled (it is delivered to the objects getting the object).
+ * @internal
+ */
+export declare function runObjectStartup(object: object, startup: () => Promise<void>): Promise<void>;
+/**
+ * Tell whether the current call chain belongs to the startup of an object
+ * @param object The object.
+ * @returns true within its startup.
+ * @internal
+ */
+export declare function isInObjectStartup(object: object): boolean;
+/**
+ * Wait for the startup of an object given to a requester (at once without startup, or within its startup)
+ * @param object The object.
+ * @returns Resolves once it started, rejects with the error of its startup.
+ * @internal
+ */
+export declare function waitForObjectStartup(object: object): Promise<void>;
+/**
+ * The end of the startup of an object, its failure ignored (its teardown waits for it): none when it has no startup
+ * running, or within its startup, so that its teardown goes on in the same turn
+ * @param object The object.
+ * @returns Resolves once its startup ended; undefined when there is nothing to wait for.
+ * @internal
+ */
+export declare function waitForObjectStartupEnd(object: object): Promise<void> | undefined;

package/dist/cjs/lib/base/internal/ObjectStartup.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runObjectStartup = runObjectStartup;
+exports.isInObjectStartup = isInObjectStartup;
+exports.waitForObjectStartup = waitForObjectStartup;
+exports.waitForObjectStartupEnd = waitForObjectStartupEnd;
+const node_async_hooks_1 = require("node:async_hooks");
+const DevNull_1 = require("@lakutata/utils/DevNull");
+/**
+ * The objects whose startup the current asynchronous call chain belongs to: the objects they get (directly, or through
+ * the objects they create) are given to them without waiting for their own startup
+ */
+const startupFrames = new node_async_hooks_1.AsyncLocalStorage();
+/**
+ * The startup of each object (the last one, for a reloaded object)
+ */
+const startups = new WeakMap();
+/**
+ * Run the startup of an object, after its initialization: the objects getting it wait for its startup, except the
+ * call chain of its startup itself, which gets it at once (initialized, not started yet)
+ * @param object The object.
+ * @param startup Its startup.
+ * @returns The startup, its failure handled (it is delivered to the objects getting the object).
+ * @internal
+ */
+function runObjectStartup(object, startup) {
+    const frame = { object: object, active: true };
+    const running = startupFrames.run([...(startupFrames.getStore() ?? []), frame], async () => {
+        try {
+            await startup();
+        }
+        finally {
+            //The work it began (servers, timers…) keeps the call chain: it no longer skips the wait once started
+            frame.active = false;
+        }
+    });
+    const record = { promise: running, ended: false };
+    running.catch(DevNull_1.DevNull).finally(() => record.ended = true);
+    startups.set(object, record);
+    return running;
+}
+/**
+ * Tell whether the current call chain belongs to the startup of an object
+ * @param object The object.
+ * @returns true within its startup.
+ * @internal
+ */
+function isInObjectStartup(object) {
+    return !!startupFrames.getStore()?.some((frame) => frame.active && frame.object === object);
+}
+/**
+ * Wait for the startup of an object given to a requester (at once without startup, or within its startup)
+ * @param object The object.
+ * @returns Resolves once it started, rejects with the error of its startup.
+ * @internal
+ */
+async function waitForObjectStartup(object) {
+    const startup = startups.get(object);
+    if (!startup || isInObjectStartup(object))
+        return;
+    await startup.promise;
+}
+/**
+ * The end of the startup of an object, its failure ignored (its teardown waits for it): none when it has no startup
+ * running, or within its startup, so that its teardown goes on in the same turn
+ * @param object The object.
+ * @returns Resolves once its startup ended; undefined when there is nothing to wait for.
+ * @internal
+ */
+function waitForObjectStartupEnd(object) {
+    const startup = startups.get(object);
+    if (!startup || startup.ended || isInObjectStartup(object))
+        return undefined;
+    return startup.promise.catch(DevNull_1.DevNull);
+}

package/dist/cjs/lib/base/internal/ObjectType.d.ts

@@ -0,0 +1,37 @@
+import { IBaseObjectConstructor } from '../../../interfaces/IBaseObjectConstructor.js';
+import { ClassDecorator } from '../../../types/ClassDecorator.js';
+/**
+ * Object Type
+ */
+export declare enum ObjectType {
+    Unknown = "Unknown",
+    Object = "Object",
+    Provider = "Provider",
+    Component = "Component",
+    Module = "Module"
+}
+/**
+ * Register BaseObject
+ * @param constructor
+ * @constructor
+ */
+export declare function registerBaseObject(constructor: Function): void;
+/**
+ * Class Decorator
+ * @param type
+ * @constructor
+ */
+export declare function DefineObjectType<ClassConstructor extends IBaseObjectConstructor>(type: ObjectType): ClassDecorator<ClassConstructor>;
+/**
+ * Set object type
+ * @param target
+ * @param type
+ * @constructor
+ */
+export declare function setObjectType<ClassConstructor extends IBaseObjectConstructor>(target: ClassConstructor, type: ObjectType): ClassConstructor;
+/**
+ * Get object type
+ * @param target
+ * @constructor
+ */
+export declare function getObjectType<ClassConstructor extends IBaseObjectConstructor>(target: ClassConstructor): ObjectType;

package/dist/cjs/lib/base/internal/ObjectType.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectType = void 0;
+exports.registerBaseObject = registerBaseObject;
+exports.DefineObjectType = DefineObjectType;
+exports.setObjectType = setObjectType;
+exports.getObjectType = getObjectType;
+const ObjectParentConstructors_1 = require("@lakutata/utils/ObjectParentConstructors");
+const IsSubclassOf_1 = require("@lakutata/utils/IsSubclassOf");
+/**
+ * Internal unique symbol
+ */
+const OBJECT_TYPE = Symbol('OBJECT.TYPE');
+/**
+ * Object Type
+ */
+var ObjectType;
+(function (ObjectType) {
+    ObjectType["Unknown"] = "Unknown";
+    ObjectType["Object"] = "Object";
+    ObjectType["Provider"] = "Provider";
+    ObjectType["Component"] = "Component";
+    ObjectType["Module"] = "Module";
+})(ObjectType || (exports.ObjectType = ObjectType = {}));
+/**
+ * BaseObject, registered by its module once it is defined: this module does not import it, BaseObject is decorated by
+ * DefineObjectType while it is defined (an import would be a cycle, which fails when the first module loaded imports
+ * BaseObject through this module)
+ */
+let baseObjectConstructor;
+/**
+ * Register BaseObject
+ * @param constructor
+ * @constructor
+ */
+function registerBaseObject(constructor) {
+    baseObjectConstructor = constructor;
+}
+/**
+ * Class Decorator
+ * @param type
+ * @constructor
+ */
+function DefineObjectType(type) {
+    return (target) => setObjectType(target, type);
+}
+/**
+ * Set object type
+ * @param target
+ * @param type
+ * @constructor
+ */
+function setObjectType(target, type) {
+    //BaseObject itself is not its own subclass: it is not registered yet when it is decorated
+    Reflect.defineMetadata(OBJECT_TYPE, baseObjectConstructor && (0, IsSubclassOf_1.isSubclassOf)(target, baseObjectConstructor) ? type : ObjectType.Unknown, target);
+    return target;
+}
+/**
+ * Get object type
+ * @param target
+ * @constructor
+ */
+function getObjectType(target) {
+    if (Reflect.hasOwnMetadata(OBJECT_TYPE, target))
+        return Reflect.getOwnMetadata(OBJECT_TYPE, target);
+    let objectType = ObjectType.Unknown;
+    for (const parentConstructor of (0, ObjectParentConstructors_1.objectParentConstructors)(target)) {
+        if (Reflect.hasOwnMetadata(OBJECT_TYPE, parentConstructor)) {
+            objectType = Reflect.getOwnMetadata(OBJECT_TYPE, parentConstructor);
+            break;
+        }
+    }
+    setObjectType(target, objectType);
+    return getObjectType(target);
+}

package/dist/cjs/lib/core/Alias.d.ts

@@ -0,0 +1,48 @@
+export declare class Alias {
+    protected aliasNameRegExp: RegExp;
+    protected readonly aliasMap: Map<string, string>;
+    /**
+     * Constructor
+     */
+    constructor();
+    /**
+     * Init alias manager, must init it before application instance init
+     */
+    static init(): void;
+    /**
+     * Get alias manager instance
+     */
+    static getAliasInstance(): Alias;
+    /**
+     * Register alias
+     * @param aliasName
+     * @param aliasPath
+     */
+    set(aliasName: string, aliasPath: string): void;
+    /**
+     * Register alias
+     * @param aliasName
+     * @param aliasPath
+     * @param override
+     */
+    set(aliasName: string, aliasPath: string, override: boolean): void;
+    /**
+     * Resolve alias
+     * @param aliasName
+     */
+    get(aliasName: string): string;
+    /**
+     * Whether an alias exists
+     * @param aliasName
+     */
+    has(aliasName: string): boolean;
+    /**
+     * Resolve string and replace alias name to alias value inside the string
+     * @param containAliasPath
+     */
+    resolve(containAliasPath: string): string;
+    /**
+     * List aliases
+     */
+    list(): Record<string, string>;
+}

package/dist/cjs/lib/core/Alias.js

@@ -0,0 +1,100 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Alias = void 0;
+const path_1 = __importDefault(require("path"));
+const InvalidAliasNameException_js_1 = require("../../exceptions/alias/InvalidAliasNameException.js");
+const AliasExistsException_js_1 = require("../../exceptions/alias/AliasExistsException.js");
+const AliasNotFoundException_js_1 = require("../../exceptions/alias/AliasNotFoundException.js");
+class Alias {
+    /**
+     * Constructor
+     */
+    constructor() {
+        this.aliasNameRegExp = /^@[a-zA-Z0-9]+$/;
+        this.aliasMap = new Map();
+        const oldPathResolve = path_1.default.resolve;
+        path_1.default.resolve = (...paths) => {
+            const resolvedPaths = paths.map((value) => this.resolve(value));
+            return oldPathResolve(...resolvedPaths);
+        };
+    }
+    /**
+     * Init alias manager, must init it before application instance init
+     */
+    static init() {
+        const instance = new this();
+        Reflect.defineMetadata(this, instance, this);
+    }
+    /**
+     * Get alias manager instance
+     */
+    static getAliasInstance() {
+        if (!Reflect.hasOwnMetadata(this, this))
+            this.init();
+        return Reflect.getMetadata(this, this);
+    }
+    set(aliasName, aliasPath, override = false) {
+        if (!this.aliasNameRegExp.test(aliasName))
+            throw new InvalidAliasNameException_js_1.InvalidAliasNameException('The alias should start with \'@\' and only contain characters a-z|A-Z|0-9. The current alias \'{aliasName}\' does not comply with this rule.', { aliasName });
+        if (this.aliasMap.has(aliasName) && !override)
+            throw new AliasExistsException_js_1.AliasExistsException('The alias \'{aliasName}\' already exists.', { aliasName });
+        this.aliasMap.set(aliasName, aliasPath);
+    }
+    /**
+     * Resolve alias
+     * @param aliasName
+     */
+    get(aliasName) {
+        if (!this.aliasNameRegExp.test(aliasName))
+            throw new InvalidAliasNameException_js_1.InvalidAliasNameException('The alias should start with \'@\' and only contain characters a-z|A-Z|0-9. The current alias \'{aliasName}\' does not comply with this rule.', { aliasName });
+        if (!this.aliasMap.has(aliasName))
+            throw new AliasNotFoundException_js_1.AliasNotFoundException('The alias \'{aliasName}\' not found.', { aliasName });
+        const aliasPath = this.aliasMap.get(aliasName);
+        return this.resolve(aliasPath);
+    }
+    /**
+     * Whether an alias exists
+     * @param aliasName
+     */
+    has(aliasName) {
+        if (!this.aliasNameRegExp.test(aliasName))
+            throw new InvalidAliasNameException_js_1.InvalidAliasNameException('The alias should start with \'@\' and only contain characters a-z|A-Z|0-9. The current alias \'{aliasName}\' does not comply with this rule.', { aliasName });
+        return this.aliasMap.has(aliasName);
+    }
+    /**
+     * Resolve string and replace alias name to alias value inside the string
+     * @param containAliasPath
+     */
+    resolve(containAliasPath) {
+        let isContainsAlias = true;
+        const aliases = [];
+        this.aliasMap.forEach((aliasPath, aliasName) => aliases.push({
+            name: aliasName,
+            path: aliasPath
+        }));
+        aliases.sort((a, b) => a.name.length < b.name.length ? 1 : -1);
+        while (isContainsAlias) {
+            let _isContainsAlias = false;
+            aliases.forEach(({ name, path }) => {
+                if (containAliasPath.includes(name)) {
+                    _isContainsAlias = true;
+                    containAliasPath = containAliasPath.replace(name, path);
+                }
+            });
+            isContainsAlias = _isContainsAlias;
+        }
+        return path_1.default.normalize(containAliasPath);
+    }
+    /**
+     * List aliases
+     */
+    list() {
+        const aliasList = {};
+        this.aliasMap.forEach((aliasValue, aliasKey) => Reflect.set(aliasList, aliasKey, aliasValue));
+        return aliasList;
+    }
+}
+exports.Alias = Alias;