@stitchem/core 0.0.3

package/dist/context/context.js

@@ -0,0 +1,395 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { isDynamicModule } from '../module/module.types.js';
+import { isModule } from '../module/module.decorator.js';
+import { Container } from '../container/container.js';
+import { ModuleGraph } from '../module/module.graph.js';
+import { ModuleRef } from '../module/module.ref.js';
+import { Injector } from '../injector/injector.js';
+import { CoreError } from '../errors/core.error.js';
+import { hasOnReady } from '../core/core.lifecycle.js';
+import { ConsoleLogger, NoopLogger } from '../logger/console.logger.js';
+import { LOGGER } from '../logger/logger.token.js';
+import { Scope } from './scope.js';
+/**
+ * The Context orchestrates the DI system.
+ * It compiles modules, manages their lifecycle, and provides dependency resolution.
+ *
+ * @example
+ * ```ts
+ * await using ctx = await Context.create(AppModule);
+ *
+ * const userService = await ctx.resolve(UserService);
+ *
+ * await ctx.withScope(async () => {
+ *   const requestService = await ctx.resolve(RequestService);
+ * });
+ * ```
+ */
+export class Context {
+    container;
+    injector;
+    moduleGraph;
+    rootModule;
+    initialized = false;
+    // noinspection JSMismatchedCollectionQueryUpdate
+    componentKeys = [];
+    constructor() {
+        this.container = new Container();
+        this.injector = new Injector(this.container);
+    }
+    /**
+     * Creates and initializes a context from a root module.
+     *
+     * @throws CoreError (INVALID_MODULE) if the root is not decorated with @module()
+     */
+    static async create(rootModule, options) {
+        const rootClass = isDynamicModule(rootModule)
+            ? rootModule.module
+            : rootModule;
+        if (!isModule(rootClass)) {
+            throw CoreError.invalidModule(rootClass);
+        }
+        const context = new Context();
+        context.componentKeys = options?.componentKeys ?? [];
+        await context.init(rootModule, options);
+        return context;
+    }
+    /**
+     * Resolves a provider by token.
+     *
+     * By default, searches across ALL modules.
+     * Pass `strict: true` to scope resolution to root module visibility.
+     *
+     * Scope auto-detection: if called inside a {@link withScope} or
+     * `scope.run()` callback, the current scope is used automatically.
+     */
+    async resolve(token, options) {
+        this.ensureInitialized();
+        const scope = Scope.current() ?? Scope.STATIC;
+        const { wrapper, module } = options?.strict
+            ? this.container.getProviderByToken(token, this.rootModule)
+            : this.container.getProviderByTokenGlobal(token);
+        return this.injector.loadInstance(wrapper, module, scope);
+    }
+    /**
+     * Synchronously resolves a provider by token.
+     */
+    resolveSync(token, options) {
+        this.ensureInitialized();
+        const scope = Scope.current() ?? Scope.STATIC;
+        const { wrapper, module } = options?.strict
+            ? this.container.getProviderByToken(token, this.rootModule)
+            : this.container.getProviderByTokenGlobal(token);
+        return this.injector.loadInstanceSync(wrapper, module, scope);
+    }
+    /**
+     * Instantiates any class by resolving its dependencies.
+     * The class does not need to be registered as a provider.
+     */
+    async constructClass(ctor, options) {
+        this.ensureInitialized();
+        const scope = Scope.current() ?? Scope.STATIC;
+        return options?.strict
+            ? this.injector.instantiateClass(ctor, this.rootModule, scope)
+            : this.injector.instantiateClassGlobal(ctor, scope);
+    }
+    /**
+     * Resolves an injectable class with global dependency resolution.
+     *
+     * Use this for injectables that are not tied to a specific module
+     * (e.g. global guards, filters, middleware registered via `useGlobal`).
+     * Dependencies are always resolved globally; the instance is cached
+     * on the root module. The `strict` option is accepted for signature
+     * compatibility with {@link ModuleRef.resolveInjectable} but is ignored
+     * (Context always resolves globally).
+     *
+     * For module-scoped resolution, use {@link ModuleRef.resolveInjectable}.
+     */
+    async resolveInjectable(ctor, _options) {
+        this.ensureInitialized();
+        const cached = this.rootModule.getInjectable(ctor);
+        if (cached)
+            return cached;
+        const scope = Scope.current() ?? Scope.STATIC;
+        const instance = await this.injector.instantiateClassGlobal(ctor, scope);
+        if (hasOnReady(instance)) {
+            await instance.onReady();
+        }
+        this.rootModule.setInjectable(ctor, instance);
+        return instance;
+    }
+    /**
+     * Runs a callback within a new disposable scope.
+     * The scope is automatically disposed when the callback completes.
+     *
+     * @example
+     * ```ts
+     * await ctx.withScope(async () => {
+     *   const svc = await ctx.resolve(RequestService);
+     * });
+     * ```
+     */
+    async withScope(fn) {
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            this.ensureInitialized();
+            const scope = __addDisposableResource(env_1, Scope.create((s) => this.dispose(s)), true);
+            // noinspection ES6RedundantAwait
+            return await scope.run(fn);
+        }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
+    }
+    /**
+     * Creates a new disposable scope for request-scoped dependencies.
+     *
+     * @example
+     * ```ts
+     * await using scope = ctx.createScope();
+     * const svc = await scope.run(() => ctx.resolve(RequestService));
+     * ```
+     */
+    createScope() {
+        this.ensureInitialized();
+        return Scope.create((scope) => this.dispose(scope));
+    }
+    /**
+     * Navigates to a specific module for resolution.
+     * Returns a ModuleRef bound to the target module.
+     */
+    select(moduleClass) {
+        this.ensureInitialized();
+        const module = this.container.getModuleByClass(moduleClass);
+        return new ModuleRef(this.container, this.injector, module);
+    }
+    /**
+     * Returns all component instances for a given metadata key.
+     * Components are returned in module dependency order.
+     */
+    getComponents(key) {
+        this.ensureInitialized();
+        const refs = [];
+        for (const id of this.moduleGraph.sortedIds) {
+            const module = this.container.getModule(id);
+            const moduleRef = module
+                .getProvider(ModuleRef)
+                ?.getInstance(Scope.STATIC);
+            for (const entry of module.getComponents(key)) {
+                refs.push({
+                    instance: entry.instance,
+                    classRef: entry.classRef,
+                    moduleRef,
+                });
+            }
+        }
+        return refs;
+    }
+    /** Disposes the context and all managed instances. */
+    async [Symbol.asyncDispose]() {
+        await this.dispose();
+    }
+    // ---------------------------------------------------------------------------
+    // Private
+    // ---------------------------------------------------------------------------
+    /**
+     * Disposes the context.
+     * With scope: only disposes scoped instances for that scope.
+     * Without scope: disposes injectables, components, then providers — shuts down.
+     */
+    async dispose(scope) {
+        if (!this.initialized)
+            return;
+        if (!scope) {
+            await this.disposeInjectables();
+            await this.disposeComponents();
+        }
+        await this.container.dispose(scope);
+        if (!scope) {
+            this.initialized = false;
+        }
+    }
+    async init(rootModule, options) {
+        this.moduleGraph = new ModuleGraph(rootModule, this.container);
+        this.rootModule = this.container.getModule(this.moduleGraph.rootModuleId);
+        this.registerModuleRefs();
+        this.registerLogger(options?.logging);
+        this.container.buildGlobalExports();
+        await this.resolveSingletons();
+        await this.resolveComponents();
+        await this.fireOnReady();
+        this.initialized = true;
+    }
+    /** Registers a ModuleRef factory provider for each module. */
+    registerModuleRefs() {
+        for (const id of this.moduleGraph.sortedIds) {
+            const module = this.container.getModule(id);
+            module.addProvider({
+                provide: ModuleRef,
+                useFactory: () => new ModuleRef(this.container, this.injector, module),
+            });
+        }
+    }
+    /** Registers the LOGGER provider in every module that doesn't already have one. */
+    registerLogger(logging) {
+        let instance;
+        if (logging === false) {
+            instance = new NoopLogger();
+        }
+        else if (logging?.logger) {
+            instance = logging.logger;
+        }
+        else {
+            if (logging?.level !== undefined) {
+                ConsoleLogger.setLevel(logging.level);
+            }
+            instance = new ConsoleLogger();
+        }
+        for (const id of this.moduleGraph.sortedIds) {
+            const module = this.container.getModule(id);
+            if (!module.hasProvider(LOGGER)) {
+                module.addProvider({ provide: LOGGER, useValue: instance });
+            }
+        }
+    }
+    /** Eagerly resolves all singleton providers in dependency order. */
+    async resolveSingletons() {
+        const instantiatedModules = new Map();
+        for (const id of this.moduleGraph.sortedIds) {
+            const module = this.container.getModule(id);
+            for (const [, wrapper] of module.providers) {
+                if (!wrapper.isSingleton || wrapper.isResolved())
+                    continue;
+                await this.injector.loadInstance(wrapper, module, Scope.STATIC);
+            }
+            // Instantiate the module class (skip if classRef already instantiated).
+            const existing = instantiatedModules.get(module.classRef);
+            if (existing !== undefined) {
+                module.instance = existing;
+                continue;
+            }
+            const instance = await this.injector.instantiateClass(module.classRef, module);
+            module.instance = instance;
+            instantiatedModules.set(module.classRef, instance);
+        }
+    }
+    /** Instantiates component classes from registered component keys. */
+    async resolveComponents() {
+        for (const id of this.moduleGraph.sortedIds) {
+            const module = this.container.getModule(id);
+            const meta = module.metadata;
+            for (const key of this.componentKeys) {
+                const classes = meta[key];
+                if (!Array.isArray(classes))
+                    continue;
+                for (const cls of classes) {
+                    const instance = await this.injector.instantiateClass(cls, module);
+                    module.addComponent(key, instance, cls);
+                }
+            }
+        }
+    }
+    /** Calls onReady() on all singleton providers, module classes, and components. */
+    async fireOnReady() {
+        for (const id of this.moduleGraph.sortedIds) {
+            const module = this.container.getModule(id);
+            for (const [, wrapper] of module.providers) {
+                if (!wrapper.isSingleton)
+                    continue;
+                const instance = wrapper.getInstance(Scope.STATIC);
+                if (instance !== undefined && hasOnReady(instance)) {
+                    await instance.onReady();
+                }
+            }
+            if (module.instance !== undefined && hasOnReady(module.instance)) {
+                await module.instance.onReady();
+            }
+            for (const key of this.componentKeys) {
+                for (const entry of module.getComponents(key)) {
+                    if (hasOnReady(entry.instance)) {
+                        await entry.instance.onReady();
+                    }
+                }
+            }
+        }
+    }
+    /** Disposes injectables in reverse module order, before component disposal. */
+    async disposeInjectables() {
+        const moduleIds = [...this.moduleGraph.sortedIds].reverse();
+        for (const id of moduleIds) {
+            const module = this.container.getModule(id);
+            await module.disposeInjectables();
+        }
+    }
+    /** Disposes components in reverse module order, before provider disposal. */
+    async disposeComponents() {
+        const moduleIds = [...this.moduleGraph.sortedIds].reverse();
+        for (const id of moduleIds) {
+            const module = this.container.getModule(id);
+            await module.disposeComponents();
+        }
+    }
+    ensureInitialized() {
+        if (!this.initialized) {
+            throw new Error('Context is not initialized. Call Context.create() first.');
+        }
+    }
+}
+//# sourceMappingURL=context.js.map

package/dist/context/scope.d.ts

@@ -0,0 +1,30 @@
+type ScopeDisposer = (scope: Scope) => void | Promise<void>;
+/**
+ * Represents a scoped resolution context.
+ * Manages scope propagation via AsyncLocalStorage and implements
+ * AsyncDisposable for automatic cleanup with `await using`.
+ *
+ * @example
+ * ```ts
+ * await ctx.withScope(async () => {
+ *   const svc = await ctx.resolve(RequestService);
+ * });
+ * ```
+ */
+export declare class Scope implements AsyncDisposable {
+    /** Static scope for singleton instances. */
+    static readonly STATIC: Scope;
+    /** The unique identifier for this scope. */
+    readonly id: string;
+    private readonly _dispose?;
+    private constructor();
+    /** @internal Creates a new scope with a unique UUIDv7 identifier. */
+    static create(dispose?: ScopeDisposer): Scope;
+    /** Returns the currently active scope, or undefined if outside any scope. */
+    static current(): Scope | undefined;
+    /** Runs a callback within this scope context. */
+    run<T>(fn: () => T): T;
+    [Symbol.asyncDispose](): Promise<void>;
+}
+export {};
+//# sourceMappingURL=scope.d.ts.map

package/dist/context/scope.js

@@ -0,0 +1,42 @@
+import { v7 as uuidv7 } from 'uuid';
+import { AsyncLocalStorage } from 'node:async_hooks';
+const storage = new AsyncLocalStorage();
+/**
+ * Represents a scoped resolution context.
+ * Manages scope propagation via AsyncLocalStorage and implements
+ * AsyncDisposable for automatic cleanup with `await using`.
+ *
+ * @example
+ * ```ts
+ * await ctx.withScope(async () => {
+ *   const svc = await ctx.resolve(RequestService);
+ * });
+ * ```
+ */
+export class Scope {
+    /** Static scope for singleton instances. */
+    static STATIC = Object.freeze(new Scope('static'));
+    /** The unique identifier for this scope. */
+    id;
+    _dispose;
+    constructor(id, dispose) {
+        this.id = id;
+        this._dispose = dispose;
+    }
+    /** @internal Creates a new scope with a unique UUIDv7 identifier. */
+    static create(dispose) {
+        return new Scope(uuidv7(), dispose);
+    }
+    /** Returns the currently active scope, or undefined if outside any scope. */
+    static current() {
+        return storage.getStore();
+    }
+    /** Runs a callback within this scope context. */
+    run(fn) {
+        return storage.run(this, fn);
+    }
+    async [Symbol.asyncDispose]() {
+        await this._dispose?.(this);
+    }
+}
+//# sourceMappingURL=scope.js.map

package/dist/core/core.lifecycle.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Interface for providers that need initialization after instantiation.
+ */
+export interface OnInit {
+    onInit(): void | Promise<void>;
+}
+/**
+ * Interface for providers that need cleanup before disposal.
+ */
+export interface OnDispose {
+    onDispose(): void | Promise<void>;
+}
+/**
+ * Interface for providers that need to run logic after all modules are initialized.
+ * Fires after every singleton provider has been created and onInit() has completed.
+ */
+export interface OnReady {
+    onReady(): void | Promise<void>;
+}
+/**
+ * Type guard for OnInit.
+ *
+ * @param instance - The value to check for OnInit conformance.
+ * @returns True if the instance implements the OnInit interface.
+ */
+export declare function hasOnInit(instance: unknown): instance is OnInit;
+/**
+ * Type guard for OnDispose.
+ *
+ * @param instance - The value to check for OnDispose conformance.
+ * @returns True if the instance implements the OnDispose interface.
+ */
+export declare function hasOnDispose(instance: unknown): instance is OnDispose;
+/**
+ * Type guard for OnReady.
+ *
+ * @param instance - The value to check for OnReady conformance.
+ * @returns True if the instance implements the OnReady interface.
+ */
+export declare function hasOnReady(instance: unknown): instance is OnReady;
+//# sourceMappingURL=core.lifecycle.d.ts.map

package/dist/core/core.lifecycle.js

@@ -0,0 +1,37 @@
+/**
+ * Type guard for OnInit.
+ *
+ * @param instance - The value to check for OnInit conformance.
+ * @returns True if the instance implements the OnInit interface.
+ */
+export function hasOnInit(instance) {
+    return (typeof instance === 'object' &&
+        instance !== null &&
+        'onInit' in instance &&
+        typeof instance.onInit === 'function');
+}
+/**
+ * Type guard for OnDispose.
+ *
+ * @param instance - The value to check for OnDispose conformance.
+ * @returns True if the instance implements the OnDispose interface.
+ */
+export function hasOnDispose(instance) {
+    return (typeof instance === 'object' &&
+        instance !== null &&
+        'onDispose' in instance &&
+        typeof instance.onDispose === 'function');
+}
+/**
+ * Type guard for OnReady.
+ *
+ * @param instance - The value to check for OnReady conformance.
+ * @returns True if the instance implements the OnReady interface.
+ */
+export function hasOnReady(instance) {
+    return (typeof instance === 'object' &&
+        instance !== null &&
+        'onReady' in instance &&
+        typeof instance.onReady === 'function');
+}
+//# sourceMappingURL=core.lifecycle.js.map

package/dist/core/core.lifetime.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Defines the lifetime/scope of a dependency instance.
+ */
+export declare enum Lifetime {
+    /**
+     * A single instance is created and shared across the entire container.
+     * This is the default lifetime.
+     */
+    SINGLETON = "singleton",
+    /**
+     * A new instance is created every time the dependency is resolved.
+     */
+    TRANSIENT = "transient",
+    /**
+     * A single instance is created per scope (identified by UUID).
+     * Scoped containers are created via `container.createScope()`.
+     * Useful for request-scoped dependencies in web frameworks.
+     */
+    SCOPED = "scoped"
+}
+//# sourceMappingURL=core.lifetime.d.ts.map

package/dist/core/core.lifetime.js

@@ -0,0 +1,22 @@
+/**
+ * Defines the lifetime/scope of a dependency instance.
+ */
+export var Lifetime;
+(function (Lifetime) {
+    /**
+     * A single instance is created and shared across the entire container.
+     * This is the default lifetime.
+     */
+    Lifetime["SINGLETON"] = "singleton";
+    /**
+     * A new instance is created every time the dependency is resolved.
+     */
+    Lifetime["TRANSIENT"] = "transient";
+    /**
+     * A single instance is created per scope (identified by UUID).
+     * Scoped containers are created via `container.createScope()`.
+     * Useful for request-scoped dependencies in web frameworks.
+     */
+    Lifetime["SCOPED"] = "scoped";
+})(Lifetime || (Lifetime = {}));
+//# sourceMappingURL=core.lifetime.js.map

package/dist/core/core.types.d.ts

@@ -0,0 +1,2 @@
+export type constructor<T = unknown> = new (...args: any[]) => T;
+//# sourceMappingURL=core.types.d.ts.map

package/dist/core/core.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=core.types.js.map

package/dist/core/core.utils.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Distinguishes class constructors from plain functions.
+ *
+ * A class has a prototype whose `constructor` property points back to
+ * itself and contains at least one additional own property (a method).
+ */
+export declare function isConstructor(fn: unknown): boolean;
+//# sourceMappingURL=core.utils.d.ts.map

package/dist/core/core.utils.js

@@ -0,0 +1,13 @@
+/**
+ * Distinguishes class constructors from plain functions.
+ *
+ * A class has a prototype whose `constructor` property points back to
+ * itself and contains at least one additional own property (a method).
+ */
+export function isConstructor(fn) {
+    const proto = fn.prototype;
+    return (proto !== undefined &&
+        proto.constructor === fn &&
+        Object.getOwnPropertyNames(proto).length > 1);
+}
+//# sourceMappingURL=core.utils.js.map

package/dist/decorator/inject.decorator.d.ts

@@ -0,0 +1,50 @@
+import type { Token } from '../token/token.types.js';
+/**
+ * TC39 accessor decorator for property injection.
+ *
+ * Use this when you need to inject a dependency as a class property
+ * rather than through the constructor.
+ *
+ * Must be used on a class also decorated with @injectable() or @module().
+ *
+ * @example
+ * ```ts
+ * @injectable()
+ * class OrderService {
+ *   @inject(LOGGER) accessor logger!: ILogger;
+ * }
+ * ```
+ */
+export declare function inject(token: Token): <This, Value>(_target: ClassAccessorDecoratorTarget<This, Value>, context: ClassAccessorDecoratorContext<This, Value>) => void;
+/**
+ * Flushes pending @inject() tokens accumulated during class definition
+ * into the registry, keyed by the given class constructor.
+ *
+ * Called by class decorators (@injectable, @module) which run after accessor decorators.
+ *
+ * @internal
+ */
+export declare function flushPendingInjectTokens(target: object): void;
+/**
+ * Gets constructor injection tokens from a class's `static inject` array.
+ * These tokens are resolved in order and passed to the constructor.
+ *
+ * Returns an empty array if the class has no `static inject`.
+ *
+ * @example
+ * ```ts
+ * class UserService {
+ *   static inject = [UserRepository, LOGGER] as const;
+ *   constructor(readonly repo: UserRepository, readonly logger: ILogger) {}
+ * }
+ *
+ * getConstructorTokens(UserService); // [UserRepository, LOGGER]
+ * ```
+ */
+export declare function getConstructorTokens(target: object): readonly Token[];
+/**
+ * Gets all accessor-injected property tokens for a class.
+ * Returns a Map of property name → injection token, or undefined if none.
+ */
+export declare function getInjectTokens(target: object): ReadonlyMap<string | symbol, Token> | undefined;
+//# sourceMappingURL=inject.decorator.d.ts.map