@lakutata/core 1.0.59 → 3.0.0-beta.0

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

@@ -0,0 +1,445 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createContainer = createContainer;
+const util = __importStar(require("util"));
+const Errors_js_1 = require("./Errors.js");
+const Lifetime_js_1 = require("./Lifetime.js");
+const ListModules_js_1 = require("./ListModules.js");
+const LoadModuleNative_js_1 = require("./LoadModuleNative.js");
+const LoadModules_js_1 = require("./LoadModules.js");
+const Resolvers_js_1 = require("./Resolvers.js");
+const Utils_js_1 = require("./Utils.js");
+const ObjectLifetime_js_1 = require("./ObjectLifetime.js");
+const As_1 = require("@lakutata/utils/As");
+const ObjectWeakRefs_js_1 = require("./ObjectWeakRefs.js");
+/**
+ * Family tree symbol.
+ */
+const FAMILY_TREE = Symbol('familyTree');
+/**
+ * Roll Up Registrations symbol.
+ */
+const ROLL_UP_REGISTRATIONS = Symbol('rollUpRegistrations');
+/**
+ * The string representation when calling toString.
+ */
+const CRADLE_STRING_TAG = 'DependencyInjectionContainerCradle';
+/**
+ * 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.
+ */
+function createContainer(options = {}) {
+    return createContainerInternal(options);
+}
+function createContainerInternal(options, parentContainer, parentResolutionStack) {
+    options = {
+        strict: false,
+        ...options
+    };
+    /**
+     * Tracks the names and lifetimes of the modules being resolved. Used to detect circular
+     * dependencies and, in strict mode, lifetime leakage issues.
+     */
+    const resolutionStack = parentResolutionStack ?? [];
+    // Internal registration store for this container.
+    const registrations = {};
+    /**
+     * The `Proxy` that is passed to functions so they can resolve their dependencies without
+     * knowing where they come from. I call it the "cradle" because
+     * it is where registered things come to life at resolution-time.
+     */
+    const cradle = new Proxy({
+        [util.inspect.custom]: toStringRepresentationFn
+    }, {
+        /**
+         * The `get` handler is invoked whenever a get-call for `container.cradle.*` is made.
+         *
+         * @param  {object} _target
+         * The proxy target. Irrelevant.
+         *
+         * @param  {string} name
+         * The property name.
+         *
+         * @return {*}
+         * Whatever the resolve call returns.
+         */
+        get: (_target, name) => resolve(name),
+        /**
+         * Setting things on the cradle throws an error.
+         *
+         * @param  {object} target
+         * @param  {string} name
+         */
+        set: (_target, name) => {
+            throw new Error(`Attempted setting property "${name}" on container cradle - this is not allowed.`);
+        },
+        /**
+         * Used for `Object.keys`.
+         */
+        ownKeys() {
+            return Array.from(cradle);
+        },
+        /**
+         * Used for `Object.keys`.
+         */
+        getOwnPropertyDescriptor(target, key) {
+            const regs = rollUpRegistrations();
+            if (Object.getOwnPropertyDescriptor(regs, key)) {
+                return {
+                    enumerable: true,
+                    configurable: true
+                };
+            }
+            return undefined;
+        }
+    });
+    // The container being exposed.
+    const container = {
+        options,
+        cradle,
+        inspect,
+        cache: new Map(),
+        loadModules,
+        createScope,
+        register: register,
+        build,
+        resolve,
+        hasRegistration,
+        dispose,
+        getRegistration,
+        [util.inspect.custom]: inspect,
+        // tslint:disable-next-line
+        [ROLL_UP_REGISTRATIONS]: rollUpRegistrations,
+        get registrations() {
+            return rollUpRegistrations();
+        }
+    };
+    // Track the family tree.
+    const familyTree = parentContainer
+        ? [container].concat((0, As_1.As)(parentContainer)[FAMILY_TREE])
+        : [container];
+    container[FAMILY_TREE] = familyTree;
+    return container;
+    /**
+     * Used by util.inspect (which is used by console.log).
+     */
+    function inspect() {
+        return `[DependencyInjectionContainer (${parentContainer ? 'scoped, ' : ''}registrations: ${Object.keys(container.registrations).length})]`;
+    }
+    /**
+     * Rolls up registrations from the family tree.
+     *
+     * This can get pretty expensive. Only used when
+     * iterating the cradle proxy, which is not something
+     * that should be done in day-to-day use, mostly for debugging.
+     *
+     * Forces a recomputation.
+     *
+     * @return {object}
+     * The merged registrations object.
+     */
+    function rollUpRegistrations() {
+        return {
+            ...(parentContainer && parentContainer[ROLL_UP_REGISTRATIONS]()),
+            ...registrations
+        };
+    }
+    /**
+     * Used for providing an iterator to the cradle.
+     */
+    function* cradleIterator() {
+        const registrations = rollUpRegistrations();
+        for (const registrationName in registrations) {
+            yield registrationName;
+        }
+    }
+    /**
+     * Creates a scoped container.
+     *
+     * @return {object}
+     * The scoped container.
+     */
+    function createScope() {
+        return createContainerInternal(options, container, resolutionStack);
+    }
+    /**
+     * Adds a registration for a resolver.
+     */
+    function register(arg1, arg2) {
+        const obj = (0, Utils_js_1.nameValueToObject)(arg1, arg2);
+        const keys = [...Object.keys(obj), ...Object.getOwnPropertySymbols(obj)];
+        for (const key of keys) {
+            const resolver = obj[key];
+            // If strict mode is enabled, check to ensure we are not registering a singleton on a non-root
+            // container.
+            if (options.strict && resolver.lifetime === Lifetime_js_1.Lifetime.SINGLETON) {
+                if (parentContainer) {
+                    throw new Errors_js_1.DependencyInjectionRegistrationError(key, 'Cannot register a singleton on a scoped container.');
+                }
+            }
+            registrations[key] = resolver;
+        }
+        return container;
+    }
+    /**
+     * Returned to `util.inspect` and Symbol.toStringTag when attempting to resolve
+     * a custom inspector function on the cradle.
+     */
+    function toStringRepresentationFn() {
+        return Object.prototype.toString.call(cradle);
+    }
+    /**
+     * 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.
+     */
+    function getRegistration(name) {
+        const resolver = registrations[name];
+        if (resolver) {
+            return resolver;
+        }
+        if (parentContainer) {
+            return parentContainer.getRegistration(name);
+        }
+        return null;
+    }
+    /**
+     * Resolves the registration with the given name.
+     * @param name
+     * @param resolveOpts
+     */
+    function resolve(name, resolveOpts) {
+        resolveOpts = resolveOpts || {};
+        try {
+            // Grab the registration by name.
+            const resolver = getRegistration(name);
+            // Cache-first: an already cached singleton or scoped value needs neither cycle detection nor construction
+            if (resolver && !options.strict) {
+                const cachedLifetime = resolver.lifetime || Lifetime_js_1.Lifetime.TRANSIENT;
+                if (cachedLifetime !== Lifetime_js_1.Lifetime.TRANSIENT) {
+                    const cachedEntry = container.cache.get(name);
+                    if (cachedEntry !== undefined)
+                        return cachedEntry.value;
+                }
+            }
+            for (let index = 0; index < resolutionStack.length; index++) {
+                if (resolutionStack[index].name === name) {
+                    throw new Errors_js_1.DependencyInjectionResolutionError(name, resolutionStack, 'Cyclic dependencies detected.');
+                }
+            }
+            // Used in JSON.stringify.
+            if (name === 'toJSON') {
+                return toStringRepresentationFn;
+            }
+            // Used in console.log.
+            if (name === 'constructor') {
+                return createContainer;
+            }
+            if (!resolver) {
+                // Checks for some edge cases.
+                switch (name) {
+                    // The following checks ensure that console.log on the cradle does not
+                    // throw an error (issue #7).
+                    case util.inspect.custom:
+                    case 'inspect':
+                    case 'toString':
+                        return toStringRepresentationFn;
+                    case Symbol.toStringTag:
+                        return CRADLE_STRING_TAG;
+                    // Edge case: Promise unwrapping will look for a "then" property and attempt to call it.
+                    // Return undefined so that we won't cause a resolution error. (issue #109)
+                    case 'then':
+                        return undefined;
+                    // When using `Array.from` or spreading the cradle, this will
+                    // return the registration names.
+                    case Symbol.iterator:
+                        return cradleIterator;
+                }
+                if (resolveOpts.allowUnregistered) {
+                    return undefined;
+                }
+                throw new Errors_js_1.DependencyInjectionResolutionError(name, resolutionStack);
+            }
+            const lifetime = resolver.lifetime || Lifetime_js_1.Lifetime.TRANSIENT;
+            // if we are running in strict mode, this resolver is not explicitly marked leak-safe, and any
+            // of the parents have a shorter lifetime than the one requested, throw an error.
+            if (options.strict && !resolver.isLeakSafe) {
+                const maybeLongerLifetimeParentIndex = resolutionStack.findIndex(({ lifetime: parentLifetime }) => (0, Lifetime_js_1.isLifetimeLonger)(parentLifetime, lifetime));
+                if (maybeLongerLifetimeParentIndex > -1) {
+                    throw new Errors_js_1.DependencyInjectionResolutionError(name, resolutionStack, `Dependency '${name.toString()}' has a shorter lifetime than its ancestor: '${resolutionStack[maybeLongerLifetimeParentIndex].name.toString()}'`);
+                }
+            }
+            // Pushes the currently-resolving module information onto the stack
+            resolutionStack.push({ name, lifetime });
+            // Do the thing
+            let cached;
+            let resolved;
+            switch (lifetime) {
+                case Lifetime_js_1.Lifetime.TRANSIENT:
+                    // Transient lifetime means resolve every time.
+                    resolved = resolver.resolve(container);
+                    break;
+                case Lifetime_js_1.Lifetime.SINGLETON:
+                    //Outside container class will handle it, just implement as SCOPED in here
+                    cached = container.cache.get(name);
+                    if (cached !== undefined) {
+                        // We found one!
+                        resolved = cached.value;
+                        break;
+                    }
+                    // If we still have not found one, we need to resolve and cache it.
+                    resolved = resolver.resolve(container);
+                    container.cache.set(name, { resolver, value: resolved });
+                    break;
+                case Lifetime_js_1.Lifetime.SCOPED:
+                    // Scoped lifetime means that the container
+                    // that resolves the registration also caches it.
+                    // If this container cache does not have it,
+                    // resolve and cache it rather than using the parent
+                    // container's cache.
+                    cached = container.cache.get(name);
+                    if (cached !== undefined) {
+                        // We found one!
+                        resolved = cached.value;
+                        break;
+                    }
+                    // If we still have not found one, we need to resolve and cache it.
+                    resolved = resolver.resolve(container);
+                    container.cache.set(name, { resolver, value: resolved });
+                    break;
+                default:
+                    throw new Errors_js_1.DependencyInjectionResolutionError(name, resolutionStack, `Unknown lifetime "${resolver.lifetime}"`);
+            }
+            // Pop it from the stack again, ready for the next resolution
+            resolutionStack.pop();
+            /**
+             * 用于加载配置对象至注入项目内
+             */
+            //判断是否为瞬态模式的注册项目调用，若为瞬态模式的注册项目调用，则应找个地方记录下来，以便在容器销毁时对残留的瞬态对象实例销毁
+            if ((0, ObjectLifetime_js_1.getObjectLifetime)(resolved.constructor) === Lifetime_js_1.Lifetime.TRANSIENT)
+                (0, ObjectWeakRefs_js_1.appendObjectWeakRefs)(this, resolved);
+            return resolved;
+        }
+        catch (err) {
+            // When we get an error we need to reset the stack. Mutate the existing array rather than
+            // updating the reference to ensure all parent containers' stacks are also updated.
+            resolutionStack.length = 0;
+            throw err;
+        }
+    }
+    /**
+     * Checks if the registration with the given name exists.
+     * @param name
+     */
+    function hasRegistration(name) {
+        return !!getRegistration(name);
+    }
+    /**
+     * Given a registration, class or function, builds it up and returns it.
+     * Does not cache it, this means that any lifetime configured in case of passing
+     * a registration will not be used.
+     * @param targetOrResolver
+     * @param opts
+     */
+    function build(targetOrResolver, opts) {
+        if (targetOrResolver && targetOrResolver.resolve) {
+            return targetOrResolver.resolve(container);
+        }
+        const funcName = 'build';
+        const paramName = 'targetOrResolver';
+        Errors_js_1.DependencyInjectionTypeError.assert(targetOrResolver, funcName, paramName, 'a registration, function or class', targetOrResolver);
+        Errors_js_1.DependencyInjectionTypeError.assert(typeof targetOrResolver === 'function', funcName, paramName, 'a function or class', targetOrResolver);
+        const resolver = (0, Utils_js_1.isClass)(targetOrResolver)
+            ? (0, Resolvers_js_1.asClass)(targetOrResolver, opts)
+            : (0, Resolvers_js_1.asFunction)(targetOrResolver, opts);
+        return resolver.resolve(container);
+    }
+    /**
+     * Binds `lib/loadModules` to this container, and provides
+     * real implementations of its dependencies.
+     *
+     * Additionally, any modules using the `dependsOn` API
+     * will be resolved.
+     *
+     * @see lib/loadModules.js documentation.
+     */
+    function loadModules(globPatterns, opts) {
+        const _loadModulesDeps = {
+            require: options.require ||
+                function (uri) {
+                    //The synchronous loading of the CommonJS modules (awilix)
+                    // eslint-disable-next-line @typescript-eslint/no-require-imports
+                    return require(uri);
+                },
+            listModules: ListModules_js_1.listModules,
+            container
+        };
+        if (opts?.esModules) {
+            _loadModulesDeps.require = LoadModuleNative_js_1.importModule;
+            return (0, LoadModules_js_1.loadModules)(_loadModulesDeps, globPatterns, opts).then(() => container);
+        }
+        else {
+            (0, LoadModules_js_1.loadModules)(_loadModulesDeps, globPatterns, opts);
+            return container;
+        }
+    }
+    /**
+     * Disposes this container and it's children, calling the disposer
+     * on all disposable registrations and clearing the cache.
+     */
+    async function dispose() {
+        const entries = Array.from(container.cache.entries());
+        container.cache.clear();
+        return Promise.all(entries.map(async ([, entry]) => {
+            const { resolver, value } = entry;
+            const disposable = resolver;
+            if (disposable.dispose) {
+                await Promise.resolve();
+                return disposable.dispose(value);
+            }
+            return Promise.resolve();
+        })).then(() => undefined);
+    }
+}

package/dist/cjs/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/cjs/lib/ioc/Errors.js

@@ -0,0 +1,115 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DependencyInjectionRegistrationError = exports.DependencyInjectionResolutionError = exports.DependencyInjectionTypeError = exports.ExtendableError = void 0;
+const DependencyInjectionException_js_1 = require("../../exceptions/di/DependencyInjectionException.js");
+const ConstructorSymbol_js_1 = require("./ConstructorSymbol.js");
+const As_1 = require("@lakutata/utils/As");
+const IsSymbol_1 = require("@lakutata/utils/IsSymbol");
+/**
+ * 可扩展错误类
+ */
+class ExtendableError extends DependencyInjectionException_js_1.DependencyInjectionException {
+    /**
+     * 可扩展错误类构造函数
+     * @param message
+     */
+    constructor(message) {
+        super(message);
+        Object.defineProperty(this, 'message', {
+            enumerable: false,
+            value: message
+        });
+        Object.defineProperty(this, 'name', {
+            enumerable: false,
+            value: this.constructor.name
+        });
+        if ('captureStackTrace' in Error) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+        else {
+            Object.defineProperty(this, 'stack', {
+                enumerable: false,
+                value: Error(message).stack,
+                writable: true,
+                configurable: true
+            });
+        }
+    }
+}
+exports.ExtendableError = ExtendableError;
+/**
+ * 抛出的错误，用于指示类型不匹配
+ */
+class DependencyInjectionTypeError extends ExtendableError {
+    /**
+     * 构造函数，接受函数名称、期望的类型和给定的类型，以生成错误
+     * @param funcDescription
+     * @param paramName
+     * @param expectedType
+     * @param givenType
+     */
+    constructor(funcDescription, paramName, expectedType, givenType) {
+        super(`${funcDescription}: expected ${paramName} to be ${expectedType}, but got ${givenType}.`);
+    }
+    /**
+     * 断言给定的条件，否则抛出错误
+     * @param condition
+     * @param funcDescription
+     * @param paramName
+     * @param expectedType
+     * @param givenType
+     */
+    static assert(condition, funcDescription, paramName, expectedType, givenType) {
+        if (!condition) {
+            throw new DependencyInjectionTypeError(funcDescription, paramName, expectedType, givenType);
+        }
+        return condition;
+    }
+}
+exports.DependencyInjectionTypeError = DependencyInjectionTypeError;
+/**
+ * 一个友好的错误类，以便我们可以进行 instanceof 检查
+ */
+class DependencyInjectionResolutionError extends ExtendableError {
+    /**
+     * 构造函数，接受注册的模块和未解析的标记，以创建一条消息
+     * @param name
+     * @param resolutionStack
+     * @param message
+     */
+    constructor(name, resolutionStack, message) {
+        if ((0, IsSymbol_1.isSymbol)(name))
+            name = (0, ConstructorSymbol_js_1.resolveConstructorNameBySymbol)(name).toString();
+        const purifiedName = name.split('_$$').reverse()[0];
+        resolutionStack = resolutionStack.map((val) => (0, IsSymbol_1.isSymbol)(val) ? (0, ConstructorSymbol_js_1.resolveConstructorNameBySymbol)(val).toString() : val.name);
+        resolutionStack.push((0, As_1.As)(purifiedName));
+        const resolutionPathString = resolutionStack.join(' -> ');
+        let msg = `Could not resolve '${purifiedName}'.`;
+        if (message)
+            msg = `${msg} ${message}`;
+        msg = `${msg} Resolution path: ${resolutionPathString}`;
+        super(msg);
+    }
+}
+exports.DependencyInjectionResolutionError = DependencyInjectionResolutionError;
+/**
+ * A nice error class, so we can do an instanceOf check.
+ */
+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, message) {
+        const stringName = name.toString();
+        let msg = `Could not register '${stringName}'.`;
+        if (message) {
+            msg += ` ${message}`;
+        }
+        super(msg);
+    }
+}
+exports.DependencyInjectionRegistrationError = DependencyInjectionRegistrationError;

package/dist/cjs/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/cjs/lib/ioc/Lifetime.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Lifetime = void 0;
+exports.isLifetimeLonger = isLifetimeLonger;
+/**
+ * Lifetime types.
+ */
+exports.Lifetime = {
+    /**
+     * The registration will be resolved once and only once by the container which registered it.
+     * @type {String}
+     */
+    SINGLETON: 'SINGLETON',
+    /**
+     * The registration will be resolved every time (never cached).
+     * @type {String}
+     */
+    TRANSIENT: 'TRANSIENT',
+    /**
+     * The registration will be resolved once per scope.
+     * @type {String}
+     */
+    SCOPED: 'SCOPED'
+};
+/**
+ * Returns true if and only if the first lifetime is strictly longer than the second.
+ */
+function isLifetimeLonger(a, b) {
+    return ((a === exports.Lifetime.SINGLETON && b !== exports.Lifetime.SINGLETON) ||
+        (a === exports.Lifetime.SCOPED && b === exports.Lifetime.TRANSIENT));
+}