@stitchem/core 0.0.3

package/dist/container/container.d.ts

@@ -0,0 +1,79 @@
+import type { Token } from '../token/token.types.js';
+import type { constructor } from '../core/core.types.js';
+import type { Scope } from '../context/scope.js';
+import type { InstanceWrapper } from '../instance-wrapper/instance-wrapper.js';
+import type { Module } from '../module/module.js';
+import { ModuleMap } from './module.map.js';
+/**
+ * Result of looking up a provider.
+ */
+export interface ProviderLookupResult<T = unknown> {
+    wrapper: InstanceWrapper<T>;
+    module: Module;
+}
+/**
+ * Main container that holds all modules.
+ * Manages module registration and provider lookup across the module tree.
+ */
+export declare class Container {
+    /** All registered modules. */
+    private readonly _modules;
+    /** Global modules (accessible from all modules). */
+    private readonly _globalModules;
+    /** Cached global exports for visibility checks. */
+    private _globalExports;
+    /** All modules. */
+    get modules(): ModuleMap;
+    /** All global modules. */
+    get globalModules(): ReadonlySet<Module>;
+    /** All global exports. */
+    get globalExports(): ReadonlySet<Token>;
+    /** Adds a module to the container. */
+    addModule(mod: Module): void;
+    /** Gets a module by ID. */
+    getModule(id: string): Module | undefined;
+    /**
+     * Gets a module by its class constructor.
+     * @throws CoreError (MODULE_NOT_FOUND) if not found
+     */
+    getModuleByClass(classRef: constructor): Module;
+    /**
+     * Gets a module by its class constructor, or undefined if not found.
+     */
+    findModuleByClass(classRef: constructor): Module | undefined;
+    /**
+     * Rebuilds the global exports cache.
+     * Call this after all modules are registered.
+     */
+    buildGlobalExports(): void;
+    /**
+     * Looks up a provider by token from a module's perspective.
+     * Searches own providers, imports, and globals — then checks visibility.
+     *
+     * @throws CoreError (PROVIDER_NOT_FOUND) if provider doesn't exist anywhere
+     * @throws CoreError (PROVIDER_NOT_VISIBLE) if provider exists but is not accessible
+     */
+    getProviderByToken<T>(token: Token<T>, fromModule: Module): ProviderLookupResult<T>;
+    /**
+     * Looks up a provider by token across ALL modules, bypassing visibility rules.
+     *
+     * @throws CoreError (PROVIDER_NOT_FOUND) if provider not found in any module
+     */
+    getProviderByTokenGlobal<T>(token: Token<T>): ProviderLookupResult<T>;
+    /**
+     * Checks if any module in the container has a provider for this token.
+     */
+    private hasProviderAnywhere;
+    /**
+     * Searches a module for an exported provider.
+     * Recursively searches imports if the token is exported but not provided directly.
+     */
+    private findExportedProvider;
+    /**
+     * Disposes all modules in reverse registration order.
+     */
+    dispose(scope?: Scope): Promise<void>;
+    /** Clears all modules from the container. */
+    clear(): void;
+}
+//# sourceMappingURL=container.d.ts.map

package/dist/container/container.js

@@ -0,0 +1,156 @@
+import { ModuleMap } from './module.map.js';
+import { CoreError } from '../errors/core.error.js';
+/**
+ * Main container that holds all modules.
+ * Manages module registration and provider lookup across the module tree.
+ */
+export class Container {
+    /** All registered modules. */
+    _modules = new ModuleMap();
+    /** Global modules (accessible from all modules). */
+    _globalModules = new Set();
+    /** Cached global exports for visibility checks. */
+    _globalExports = new Set();
+    /** All modules. */
+    get modules() {
+        return this._modules;
+    }
+    /** All global modules. */
+    get globalModules() {
+        return this._globalModules;
+    }
+    /** All global exports. */
+    get globalExports() {
+        return this._globalExports;
+    }
+    /** Adds a module to the container. */
+    addModule(mod) {
+        this._modules.set(mod.id, mod);
+        if (mod.isGlobal)
+            this._globalModules.add(mod);
+    }
+    /** Gets a module by ID. */
+    getModule(id) {
+        return this._modules.get(id);
+    }
+    /**
+     * Gets a module by its class constructor.
+     * @throws CoreError (MODULE_NOT_FOUND) if not found
+     */
+    getModuleByClass(classRef) {
+        const mod = this._modules.getByClass(classRef);
+        if (!mod)
+            throw CoreError.moduleNotFound(classRef);
+        return mod;
+    }
+    /**
+     * Gets a module by its class constructor, or undefined if not found.
+     */
+    findModuleByClass(classRef) {
+        return this._modules.getByClass(classRef);
+    }
+    /**
+     * Rebuilds the global exports cache.
+     * Call this after all modules are registered.
+     */
+    buildGlobalExports() {
+        this._globalExports = new Set();
+        for (const mod of this._globalModules) {
+            for (const token of mod.exports) {
+                this._globalExports.add(token);
+            }
+        }
+    }
+    /**
+     * Looks up a provider by token from a module's perspective.
+     * Searches own providers, imports, and globals — then checks visibility.
+     *
+     * @throws CoreError (PROVIDER_NOT_FOUND) if provider doesn't exist anywhere
+     * @throws CoreError (PROVIDER_NOT_VISIBLE) if provider exists but is not accessible
+     */
+    getProviderByToken(token, fromModule) {
+        // Own providers first.
+        const ownProvider = fromModule.getProvider(token);
+        if (ownProvider)
+            return { wrapper: ownProvider, module: fromModule };
+        // Imported modules' exports.
+        for (const imported of fromModule.imports) {
+            const result = this.findExportedProvider(imported, token);
+            if (result)
+                return result;
+        }
+        // Global modules.
+        for (const globalMod of this._globalModules) {
+            const result = this.findExportedProvider(globalMod, token);
+            if (result)
+                return result;
+        }
+        // Not found — determine if it exists elsewhere (visibility issue) or doesn't exist at all.
+        if (this.hasProviderAnywhere(token)) {
+            throw CoreError.providerNotVisible(token, fromModule.id);
+        }
+        throw CoreError.providerNotFound(token, fromModule.id);
+    }
+    /**
+     * Looks up a provider by token across ALL modules, bypassing visibility rules.
+     *
+     * @throws CoreError (PROVIDER_NOT_FOUND) if provider not found in any module
+     */
+    getProviderByTokenGlobal(token) {
+        for (const mod of this._modules.values()) {
+            const provider = mod.getProvider(token);
+            if (provider)
+                return { wrapper: provider, module: mod };
+        }
+        throw CoreError.providerNotFound(token, 'global');
+    }
+    /**
+     * Checks if any module in the container has a provider for this token.
+     */
+    hasProviderAnywhere(token) {
+        for (const mod of this._modules.values()) {
+            if (mod.hasProvider(token))
+                return true;
+        }
+        return false;
+    }
+    /**
+     * Searches a module for an exported provider.
+     * Recursively searches imports if the token is exported but not provided directly.
+     */
+    findExportedProvider(mod, token, visited = new Set()) {
+        if (visited.has(mod))
+            return undefined;
+        visited.add(mod);
+        if (!mod.exports.has(token))
+            return undefined;
+        const provider = mod.getProvider(token);
+        if (provider)
+            return { wrapper: provider, module: mod };
+        // Token is exported but not owned — search imports for actual provider.
+        for (const imported of mod.imports) {
+            const result = this.findExportedProvider(imported, token, visited);
+            if (result)
+                return result;
+        }
+        return undefined;
+    }
+    /**
+     * Disposes all modules in reverse registration order.
+     */
+    async dispose(scope) {
+        const moduleIds = [...this._modules.keys()].reverse();
+        for (const id of moduleIds) {
+            const mod = this._modules.get(id);
+            if (mod)
+                await mod.dispose(scope);
+        }
+    }
+    /** Clears all modules from the container. */
+    clear() {
+        this._modules.clear();
+        this._globalModules.clear();
+        this._globalExports.clear();
+    }
+}
+//# sourceMappingURL=container.js.map

package/dist/container/module.map.d.ts

@@ -0,0 +1,22 @@
+import type { constructor } from '../core/core.types.js';
+import type { Module } from '../module/module.js';
+/**
+ * Map of module ID → Module with utility lookup methods.
+ */
+export declare class ModuleMap extends Map<string, Module> {
+    /**
+     * Gets a module by its class constructor.
+     * Returns the first match (multiple instances possible via DynamicModule).
+     */
+    getByClass(classRef: constructor): Module | undefined;
+    /**
+     * Gets all modules with the given class constructor.
+     * Useful for DynamicModules where the same class can have multiple instances.
+     */
+    getAllByClass(classRef: constructor): Module[];
+    /**
+     * Gets all global modules.
+     */
+    getGlobalModules(): Module[];
+}
+//# sourceMappingURL=module.map.d.ts.map

package/dist/container/module.map.js

@@ -0,0 +1,40 @@
+/**
+ * Map of module ID → Module with utility lookup methods.
+ */
+export class ModuleMap extends Map {
+    /**
+     * Gets a module by its class constructor.
+     * Returns the first match (multiple instances possible via DynamicModule).
+     */
+    getByClass(classRef) {
+        for (const mod of this.values()) {
+            if (mod.classRef === classRef)
+                return mod;
+        }
+        return undefined;
+    }
+    /**
+     * Gets all modules with the given class constructor.
+     * Useful for DynamicModules where the same class can have multiple instances.
+     */
+    getAllByClass(classRef) {
+        const modules = [];
+        for (const mod of this.values()) {
+            if (mod.classRef === classRef)
+                modules.push(mod);
+        }
+        return modules;
+    }
+    /**
+     * Gets all global modules.
+     */
+    getGlobalModules() {
+        const globals = [];
+        for (const mod of this.values()) {
+            if (mod.isGlobal)
+                globals.push(mod);
+        }
+        return globals;
+    }
+}
+//# sourceMappingURL=module.map.js.map

package/dist/context/context.d.ts

@@ -0,0 +1,181 @@
+import type { constructor } from '../core/core.types.js';
+import type { Token } from '../token/token.types.js';
+import type { ModuleImport } from '../module/module.types.js';
+import type { Logger } from '../logger/logger.types.js';
+import { LogLevel } from '../logger/logger.types.js';
+import { Container } from '../container/container.js';
+import { ModuleRef } from '../module/module.ref.js';
+import { Injector } from '../injector/injector.js';
+import { Scope } from './scope.js';
+/**
+ * Options for resolving a provider.
+ */
+export interface ResolveOptions {
+    /** When true, scopes resolution to root module visibility. */
+    strict?: boolean;
+}
+/**
+ * Options for creating a Context.
+ */
+export interface ContextOptions {
+    /**
+     * Metadata keys whose values are arrays of constructors that the core
+     * should instantiate with DI and lifecycle-manage as "components".
+     *
+     * @example
+     * ```ts
+     * // HTTP extension registers 'routers'
+     * await using ctx = await Context.create(AppModule, {
+     *   componentKeys: ['routers'],
+     * });
+     * ```
+     */
+    componentKeys?: string[];
+    /**
+     * Logging configuration.
+     *
+     * - Omitted / `undefined`: default {@link ConsoleLogger} at {@link LogLevel.DEBUG}.
+     * - `false`: logging is disabled (a {@link NoopLogger} is registered).
+     * - `{ level }`: default ConsoleLogger at the given level.
+     * - `{ logger }`: custom {@link Logger} implementation used as-is.
+     */
+    logging?: false | LoggingOptions;
+}
+/**
+ * Logging configuration for the DI context.
+ */
+export interface LoggingOptions {
+    /** Custom logger implementation. Defaults to {@link ConsoleLogger}. */
+    logger?: Logger;
+    /** Log level for the default ConsoleLogger. Ignored when a custom `logger` is provided. */
+    level?: LogLevel;
+}
+/**
+ * A resolved component instance with its origin information.
+ */
+export interface ComponentRef<T = unknown> {
+    instance: T;
+    classRef: constructor<T>;
+    moduleRef: ModuleRef;
+}
+/**
+ * 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 declare class Context implements AsyncDisposable {
+    readonly container: Container;
+    readonly injector: Injector;
+    private moduleGraph;
+    private rootModule;
+    private initialized;
+    private componentKeys;
+    private constructor();
+    /**
+     * Creates and initializes a context from a root module.
+     *
+     * @throws CoreError (INVALID_MODULE) if the root is not decorated with @module()
+     */
+    static create(rootModule: ModuleImport, options?: ContextOptions): Promise<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.
+     */
+    resolve<T>(token: Token<T>, options?: ResolveOptions): Promise<T>;
+    /**
+     * Synchronously resolves a provider by token.
+     */
+    resolveSync<T>(token: Token<T>, options?: ResolveOptions): T;
+    /**
+     * Instantiates any class by resolving its dependencies.
+     * The class does not need to be registered as a provider.
+     */
+    constructClass<T>(ctor: constructor<T>, options?: ResolveOptions): Promise<T>;
+    /**
+     * 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}.
+     */
+    resolveInjectable<T>(ctor: constructor<T>, _options?: {
+        strict?: boolean;
+    }): Promise<T>;
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    withScope<T>(fn: () => T | Promise<T>): Promise<T>;
+    /**
+     * 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(): Scope;
+    /**
+     * Navigates to a specific module for resolution.
+     * Returns a ModuleRef bound to the target module.
+     */
+    select<T extends constructor>(moduleClass: T): ModuleRef;
+    /**
+     * Returns all component instances for a given metadata key.
+     * Components are returned in module dependency order.
+     */
+    getComponents<T = unknown>(key: string): ComponentRef<T>[];
+    /** Disposes the context and all managed instances. */
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Disposes the context.
+     * With scope: only disposes scoped instances for that scope.
+     * Without scope: disposes injectables, components, then providers — shuts down.
+     */
+    private dispose;
+    private init;
+    /** Registers a ModuleRef factory provider for each module. */
+    private registerModuleRefs;
+    /** Registers the LOGGER provider in every module that doesn't already have one. */
+    private registerLogger;
+    /** Eagerly resolves all singleton providers in dependency order. */
+    private resolveSingletons;
+    /** Instantiates component classes from registered component keys. */
+    private resolveComponents;
+    /** Calls onReady() on all singleton providers, module classes, and components. */
+    private fireOnReady;
+    /** Disposes injectables in reverse module order, before component disposal. */
+    private disposeInjectables;
+    /** Disposes components in reverse module order, before provider disposal. */
+    private disposeComponents;
+    private ensureInitialized;
+}
+//# sourceMappingURL=context.d.ts.map