@lakutata/core 1.0.60 → 3.0.0-beta.1

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

@@ -0,0 +1,409 @@
+import * as util from 'util';
+import { DependencyInjectionRegistrationError, DependencyInjectionResolutionError, DependencyInjectionTypeError } from './Errors.js';
+import { Lifetime, isLifetimeLonger } from './Lifetime.js';
+import { listModules } from './ListModules.js';
+import { importModule } from './LoadModuleNative.js';
+import { loadModules as realLoadModules } from './LoadModules.js';
+import { asClass, asFunction } from './Resolvers.js';
+import { isClass, nameValueToObject } from './Utils.js';
+import { getObjectLifetime } from './ObjectLifetime.js';
+import { As } from '@lakutata/utils/As';
+import { appendObjectWeakRefs } from './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.
+ */
+export 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(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 = 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.SINGLETON) {
+                if (parentContainer) {
+                    throw new 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.TRANSIENT;
+                if (cachedLifetime !== 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 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 DependencyInjectionResolutionError(name, resolutionStack);
+            }
+            const lifetime = resolver.lifetime || 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 }) => isLifetimeLonger(parentLifetime, lifetime));
+                if (maybeLongerLifetimeParentIndex > -1) {
+                    throw new 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.TRANSIENT:
+                    // Transient lifetime means resolve every time.
+                    resolved = resolver.resolve(container);
+                    break;
+                case 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.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 DependencyInjectionResolutionError(name, resolutionStack, `Unknown lifetime "${resolver.lifetime}"`);
+            }
+            // Pop it from the stack again, ready for the next resolution
+            resolutionStack.pop();
+            /**
+             * 用于加载配置对象至注入项目内
+             */
+            //判断是否为瞬态模式的注册项目调用，若为瞬态模式的注册项目调用，则应找个地方记录下来，以便在容器销毁时对残留的瞬态对象实例销毁
+            if (getObjectLifetime(resolved.constructor) === Lifetime.TRANSIENT)
+                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';
+        DependencyInjectionTypeError.assert(targetOrResolver, funcName, paramName, 'a registration, function or class', targetOrResolver);
+        DependencyInjectionTypeError.assert(typeof targetOrResolver === 'function', funcName, paramName, 'a function or class', targetOrResolver);
+        const resolver = isClass(targetOrResolver)
+            ? asClass(targetOrResolver, opts)
+            : 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,
+            container
+        };
+        if (opts?.esModules) {
+            _loadModulesDeps.require = importModule;
+            return realLoadModules(_loadModulesDeps, globPatterns, opts).then(() => container);
+        }
+        else {
+            realLoadModules(_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/esm/lib/ioc/Errors.js

@@ -0,0 +1,108 @@
+import { DependencyInjectionException } from '../../exceptions/di/DependencyInjectionException.js';
+import { resolveConstructorNameBySymbol } from './ConstructorSymbol.js';
+import { As } from '@lakutata/utils/As';
+import { isSymbol } from '@lakutata/utils/IsSymbol';
+/**
+ * 可扩展错误类
+ */
+export class ExtendableError extends 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
+            });
+        }
+    }
+}
+/**
+ * 抛出的错误，用于指示类型不匹配
+ */
+export 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;
+    }
+}
+/**
+ * 一个友好的错误类，以便我们可以进行 instanceof 检查
+ */
+export class DependencyInjectionResolutionError extends ExtendableError {
+    /**
+     * 构造函数，接受注册的模块和未解析的标记，以创建一条消息
+     * @param name
+     * @param resolutionStack
+     * @param message
+     */
+    constructor(name, resolutionStack, message) {
+        if (isSymbol(name))
+            name = resolveConstructorNameBySymbol(name).toString();
+        const purifiedName = name.split('_$$').reverse()[0];
+        resolutionStack = resolutionStack.map((val) => isSymbol(val) ? resolveConstructorNameBySymbol(val).toString() : val.name);
+        resolutionStack.push(As(purifiedName));
+        const resolutionPathString = resolutionStack.join(' -> ');
+        let msg = `Could not resolve '${purifiedName}'.`;
+        if (message)
+            msg = `${msg} ${message}`;
+        msg = `${msg} Resolution path: ${resolutionPathString}`;
+        super(msg);
+    }
+}
+/**
+ * A nice error class, so we can do an instanceOf check.
+ */
+export 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);
+    }
+}

package/dist/esm/lib/ioc/Lifetime.js

@@ -0,0 +1,27 @@
+/**
+ * Lifetime types.
+ */
+export const 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.
+ */
+export function isLifetimeLonger(a, b) {
+    return ((a === Lifetime.SINGLETON && b !== Lifetime.SINGLETON) ||
+        (a === Lifetime.SCOPED && b === Lifetime.TRANSIENT));
+}

package/dist/esm/lib/ioc/ListModules.js

@@ -0,0 +1,68 @@
+import { GlobSync } from '@lakutata/utils/Glob';
+import * as path from 'path';
+import { flatten } from './Utils.js';
+/**
+ * Default glob: matches files only, follows symbolic links and matches the case, like the fast-glob lookup of 2.x
+ * (case sensitive on every platform)
+ * @param pattern
+ * @param options
+ */
+function defaultGlob(pattern, options) {
+    return GlobSync(pattern, { cwd: options.cwd, nodir: true, follow: true, nocase: false });
+}
+// Regex to extract the module name.
+const nameExpr = /(.*)\..*/i;
+/**
+ * Internal method for globbing a single pattern.
+ *
+ * @param  {String} globPattern
+ * The glob pattern.
+ *
+ * @param opts
+ * @param  {String} opts.cwd
+ * Current working directory, used for resolving filepaths.
+ * Defaults to `process.cwd()`.
+ *
+ * @return {[{name, path, opts}]}
+ * The module names and paths.
+ *
+ * @api private
+ */
+function _listModules(globPattern, opts) {
+    opts = { cwd: process.cwd(), glob: defaultGlob, ...opts };
+    let patternOpts = null;
+    if (Array.isArray(globPattern)) {
+        patternOpts = globPattern[1];
+        globPattern = globPattern[0];
+    }
+    // Replace Windows path separators with Posix path
+    globPattern = globPattern.replace(/\\/g, '/');
+    const result = opts.glob(globPattern, { cwd: opts.cwd });
+    const mapped = result.map((p) => ({
+        name: nameExpr.exec(path.basename(p))[1],
+        path: path.resolve(opts.cwd, p),
+        opts: patternOpts
+    }));
+    return mapped;
+}
+/**
+ * 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 function listModules(globPatterns, opts) {
+    if (Array.isArray(globPatterns)) {
+        return flatten(globPatterns.map((p) => _listModules(p, opts)));
+    }
+    return _listModules(globPatterns, opts);
+}

package/dist/esm/lib/ioc/LoadModuleNative.js

@@ -0,0 +1,5 @@
+// This is kept in a separate .js file to prevent TypeScript re-writing the import() statement to a require() statement
+export function importModule(path) {
+    return import(path);
+}
+// module.exports = {importModule}