@stitchem/core 0.0.3

package/dist/logger/logger.token.js

@@ -0,0 +1,23 @@
+/**
+ * Injection token for the logger.
+ *
+ * Use this token to inject or replace the logger via DI.
+ *
+ * @example Inject
+ * ```ts
+ * @injectable()
+ * class UserService {
+ *   static inject = [LOGGER] as const;
+ *   constructor(readonly logger: Logger) {}
+ * }
+ * ```
+ *
+ * @example Replace globally
+ * ```ts
+ * await using ctx = await Context.create(AppModule, {
+ *   logging: { logger: pino() },
+ * });
+ * ```
+ */
+export const LOGGER = Symbol.for('stitchem:logger');
+//# sourceMappingURL=logger.token.js.map

package/dist/logger/logger.types.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Log levels in order of verbosity (lowest to highest).
+ */
+export declare enum LogLevel {
+    DEBUG = 0,
+    INFO = 1,
+    WARN = 2,
+    ERROR = 3,
+    SILENT = 4
+}
+/**
+ * Minimal logger interface.
+ *
+ * Compatible with `console`, `pino()`, and `winston.createLogger()` out of the box.
+ *
+ * @example DI injection
+ * ```ts
+ * @injectable()
+ * class UserService {
+ *   static inject = [LOGGER] as const;
+ *   constructor(readonly logger: Logger) {}
+ * }
+ * ```
+ *
+ * @example Replace with pino
+ * ```ts
+ * await using ctx = await Context.create(AppModule, {
+ *   logging: { logger: pino() },
+ * });
+ * ```
+ */
+export interface Logger {
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+    debug(message: string, ...args: unknown[]): void;
+}
+//# sourceMappingURL=logger.types.d.ts.map

package/dist/logger/logger.types.js

@@ -0,0 +1,12 @@
+/**
+ * Log levels in order of verbosity (lowest to highest).
+ */
+export var LogLevel;
+(function (LogLevel) {
+    LogLevel[LogLevel["DEBUG"] = 0] = "DEBUG";
+    LogLevel[LogLevel["INFO"] = 1] = "INFO";
+    LogLevel[LogLevel["WARN"] = 2] = "WARN";
+    LogLevel[LogLevel["ERROR"] = 3] = "ERROR";
+    LogLevel[LogLevel["SILENT"] = 4] = "SILENT";
+})(LogLevel || (LogLevel = {}));
+//# sourceMappingURL=logger.types.js.map

package/dist/module/module.d.ts

@@ -0,0 +1,104 @@
+import type { Token } from '../token/token.types.js';
+import type { constructor } from '../core/core.types.js';
+import type { Provider } from '../provider/provider.interface.js';
+import type { ModuleMetadata } from './module.types.js';
+import { Scope } from '../context/scope.js';
+import { InstanceWrapper } from '../instance-wrapper/instance-wrapper.js';
+/**
+ * Options for creating a Module.
+ */
+export interface ModuleOptions {
+    /** Unique identifier for this module instance. */
+    id: string;
+    /** The module class (decorated with @module). */
+    classRef: constructor;
+    /** Module metadata (providers, exports, imports). */
+    metadata: ModuleMetadata;
+    /** Whether this is a global module. */
+    isGlobal?: boolean;
+}
+/**
+ * Represents a module instance with its own providers.
+ * Each module maintains its own provider registry and visibility rules.
+ */
+export declare class Module {
+    /** Unique identifier for this module instance. */
+    readonly id: string;
+    /** The module class. */
+    readonly classRef: constructor;
+    /** Whether this is a global module. */
+    readonly isGlobal: boolean;
+    /** Original metadata from @module decorator + dynamic config. */
+    readonly metadata: ModuleMetadata;
+    /** Provider storage (token -> InstanceWrapper). */
+    private readonly _providers;
+    /** Exported tokens. */
+    private readonly _exports;
+    /** Imported modules. */
+    private readonly _imports;
+    /** Registration order for disposal. */
+    private readonly _registrationOrder;
+    /** Component instances keyed by metadata key (e.g. 'routers'). */
+    private readonly _components;
+    /** Injectable instances (guards, filters, middleware, etc.) keyed by class ref. */
+    private readonly _injectables;
+    /** Insertion order for injectable disposal. */
+    private readonly _injectableOrder;
+    /** Module instance (the instantiated module class). */
+    private _instance?;
+    constructor(options: ModuleOptions);
+    /** All providers in this module. */
+    get providers(): ReadonlyMap<Token, InstanceWrapper>;
+    /** All exported tokens. */
+    get exports(): ReadonlySet<Token>;
+    /** All imported modules. */
+    get imports(): ReadonlySet<Module>;
+    /** The module class instance. */
+    get instance(): unknown;
+    set instance(value: unknown);
+    /**
+     * Adds a provider to this module.
+     * Validates that class-based providers have @injectable().
+     *
+     * @throws CoreError (NOT_INJECTABLE) if a class provider lacks @injectable()
+     */
+    addProvider<T>(provider: Provider<T>): InstanceWrapper<T>;
+    /** Gets a provider by token. */
+    getProvider<T>(token: Token<T>): InstanceWrapper<T> | undefined;
+    /** Checks if a provider exists in this module. */
+    hasProvider(token: Token): boolean;
+    /** Adds an export token. */
+    addExport(token: Token): void;
+    /** Adds an imported module. */
+    addImport(mod: Module): void;
+    /** Registers a component instance under a metadata key. */
+    addComponent(key: string, instance: unknown, classRef: constructor): void;
+    /** Returns component instances for a metadata key. */
+    getComponents(key: string): readonly {
+        instance: unknown;
+        classRef: constructor;
+    }[];
+    /** Returns a cached injectable instance, or undefined if not resolved yet. */
+    getInjectable<T>(ctor: constructor<T>): T | undefined;
+    /** Caches an injectable instance and tracks insertion order. */
+    setInjectable<T>(ctor: constructor<T>, instance: T): void;
+    /** All cached injectables as [classRef, instance] pairs. */
+    get injectables(): ReadonlyMap<constructor, unknown>;
+    /** Disposes all injectable instances in reverse insertion order. */
+    disposeInjectables(): Promise<void>;
+    /** Disposes all component instances in reverse order. */
+    disposeComponents(): Promise<void>;
+    /**
+     * Disposes provider instances in reverse registration order.
+     *
+     * - With scope: only dispose SCOPED instances for that scope
+     * - Without scope: dispose all SINGLETON instances (full shutdown)
+     */
+    dispose(scope?: Scope): Promise<void>;
+    /**
+     * Validates a provider configuration.
+     * @throws CoreError (NOT_INJECTABLE) if a class provider lacks @injectable()
+     */
+    private validateProvider;
+}
+//# sourceMappingURL=module.d.ts.map

package/dist/module/module.decorator.d.ts

@@ -0,0 +1,28 @@
+import type { constructor } from '../core/core.types.js';
+import type { ModuleMetadata } from './module.types.js';
+/**
+ * Marks a class as a module.
+ *
+ * Modules are the building blocks of a stitchem application.
+ * They group related providers and define dependencies on other modules.
+ *
+ * @example
+ * ```ts
+ * @module({
+ *   imports: [DatabaseModule],
+ *   providers: [UserService, UserRepository],
+ *   exports: [UserService],
+ * })
+ * class UserModule {}
+ * ```
+ */
+export declare function module(metadata?: ModuleMetadata): (target: constructor, _context: ClassDecoratorContext) => void;
+/**
+ * Checks if a class is decorated with @module().
+ */
+export declare function isModule(target: constructor): boolean;
+/**
+ * Gets the module metadata from a class, or undefined if not decorated.
+ */
+export declare function getModuleMetadata(target: constructor): ModuleMetadata | undefined;
+//# sourceMappingURL=module.decorator.d.ts.map

package/dist/module/module.decorator.js

@@ -0,0 +1,42 @@
+import { flushPendingInjectTokens } from '../decorator/inject.decorator.js';
+// WeakMap-based metadata storage.
+// TODO: Replace with `context.metadata[key]` once transpilers ship decorator metadata support.
+// That change is internal-only — the public API stays identical.
+const registry = new WeakMap();
+/**
+ * Marks a class as a module.
+ *
+ * Modules are the building blocks of a stitchem application.
+ * They group related providers and define dependencies on other modules.
+ *
+ * @example
+ * ```ts
+ * @module({
+ *   imports: [DatabaseModule],
+ *   providers: [UserService, UserRepository],
+ *   exports: [UserService],
+ * })
+ * class UserModule {}
+ * ```
+ */
+export function module(metadata = {}) {
+    return function (target, _context) {
+        registry.set(target, metadata);
+        // Flush any @inject() accessor tokens accumulated during class definition.
+        // TC39 order: accessor decorators run first, class decorator runs last.
+        flushPendingInjectTokens(target);
+    };
+}
+/**
+ * Checks if a class is decorated with @module().
+ */
+export function isModule(target) {
+    return registry.has(target);
+}
+/**
+ * Gets the module metadata from a class, or undefined if not decorated.
+ */
+export function getModuleMetadata(target) {
+    return registry.get(target);
+}
+//# sourceMappingURL=module.decorator.js.map

package/dist/module/module.graph.d.ts

@@ -0,0 +1,52 @@
+import type { constructor } from '../core/core.types.js';
+import type { DynamicModule } from './module.types.js';
+import { Container } from '../container/container.js';
+/**
+ * Analyzes and builds the module dependency graph.
+ * Creates Module instances and sets up their relationships.
+ */
+export declare class ModuleGraph {
+    private readonly container;
+    /** Module IDs in topological order (dependencies first). */
+    readonly sortedIds: readonly string[];
+    /** Counter for generating unique DynamicModule instance IDs. */
+    private dynamicModuleCounter;
+    /** Tracks DynamicModule objects to their assigned IDs. */
+    private readonly dynamicModuleIds;
+    /** Internal nodes during graph building. */
+    private readonly nodes;
+    /** Tracks IDs currently being collected (prevents infinite recursion on cycles). */
+    private readonly visiting;
+    /**
+     * Builds the module graph and populates the container.
+     */
+    constructor(rootModule: constructor | DynamicModule, container: Container);
+    /** The root module ID (last in topological order). */
+    get rootModuleId(): string;
+    /** Generates a unique ID for a module import. */
+    private getModuleId;
+    /** Collects all modules recursively. */
+    private collectModules;
+    /** Unwraps a ModuleImport to get the class and optional dynamic config. */
+    private unwrapModule;
+    /**
+     * Gets and validates module metadata.
+     * @throws CoreError (INVALID_MODULE) if the class is not decorated with @module()
+     */
+    private getValidatedMetadata;
+    /**
+     * Merges base metadata with dynamic module config.
+     * Well-known keys are merged type-safely; augmented component keys
+     * (e.g. `routers: constructor[]`) are concatenated.
+     */
+    private mergeMetadata;
+    /** Topological sort with global modules first. */
+    private toposort;
+    /** Collects all transitive import IDs reachable from the given root IDs. */
+    private collectTransitiveImports;
+    /** Creates Module instances and sets up relationships. */
+    private buildModules;
+    /** Checks if a constructor is the classRef of any imported module. */
+    private isImportedModule;
+}
+//# sourceMappingURL=module.graph.d.ts.map

package/dist/module/module.graph.js

@@ -0,0 +1,263 @@
+import toposort from 'toposort';
+import { isDynamicModule } from './module.types.js';
+import { isModule, getModuleMetadata } from './module.decorator.js';
+import { Module } from './module.js';
+import { CoreError } from '../errors/core.error.js';
+/**
+ * Analyzes and builds the module dependency graph.
+ * Creates Module instances and sets up their relationships.
+ */
+export class ModuleGraph {
+    container;
+    /** Module IDs in topological order (dependencies first). */
+    sortedIds;
+    /** Counter for generating unique DynamicModule instance IDs. */
+    dynamicModuleCounter = 0;
+    /** Tracks DynamicModule objects to their assigned IDs. */
+    dynamicModuleIds = new WeakMap();
+    /** Internal nodes during graph building. */
+    nodes = new Map();
+    /** Tracks IDs currently being collected (prevents infinite recursion on cycles). */
+    visiting = new Set();
+    /**
+     * Builds the module graph and populates the container.
+     */
+    constructor(rootModule, container) {
+        this.container = container;
+        const edges = [];
+        const globalIds = new Set();
+        this.collectModules(rootModule, globalIds, edges);
+        this.sortedIds = this.toposort(edges, globalIds);
+        this.buildModules();
+        this.container.buildGlobalExports();
+    }
+    /** The root module ID (last in topological order). */
+    get rootModuleId() {
+        return this.sortedIds[this.sortedIds.length - 1];
+    }
+    /** Generates a unique ID for a module import. */
+    getModuleId(moduleImport) {
+        if (isDynamicModule(moduleImport)) {
+            const existingId = this.dynamicModuleIds.get(moduleImport);
+            if (existingId)
+                return existingId;
+            const id = `${moduleImport.module.name}$${++this.dynamicModuleCounter}`;
+            this.dynamicModuleIds.set(moduleImport, id);
+            return id;
+        }
+        return moduleImport.name;
+    }
+    /** Collects all modules recursively. */
+    collectModules(moduleImport, globalIds, edges) {
+        const id = this.getModuleId(moduleImport);
+        if (this.nodes.has(id))
+            return id;
+        // Cycle guard: if we're already collecting this module's imports,
+        // return the ID without recursing (the node will be built when the
+        // original call unwinds). This allows circular module imports when
+        // lazy() is used to break the provider-level cycle.
+        if (this.visiting.has(id))
+            return id;
+        this.visiting.add(id);
+        const { moduleClass, dynamicConfig } = this.unwrapModule(moduleImport);
+        const baseMeta = this.getValidatedMetadata(moduleClass);
+        const mergedMeta = dynamicConfig
+            ? this.mergeMetadata(baseMeta, dynamicConfig)
+            : { ...baseMeta };
+        const importIds = [];
+        for (const imported of mergedMeta.imports ?? []) {
+            const importedId = this.collectModules(imported, globalIds, edges);
+            importIds.push(importedId);
+            edges.push([id, importedId]);
+        }
+        const isGlobalModule = dynamicConfig?.global ?? baseMeta.global ?? false;
+        const node = {
+            id,
+            moduleClass,
+            metadata: mergedMeta,
+            isGlobal: isGlobalModule,
+            importIds,
+        };
+        this.nodes.set(id, node);
+        if (isGlobalModule)
+            globalIds.add(id);
+        return id;
+    }
+    /** Unwraps a ModuleImport to get the class and optional dynamic config. */
+    unwrapModule(moduleImport) {
+        if (isDynamicModule(moduleImport)) {
+            return { moduleClass: moduleImport.module, dynamicConfig: moduleImport };
+        }
+        return { moduleClass: moduleImport, dynamicConfig: null };
+    }
+    /**
+     * Gets and validates module metadata.
+     * @throws CoreError (INVALID_MODULE) if the class is not decorated with @module()
+     */
+    getValidatedMetadata(moduleClass) {
+        const meta = getModuleMetadata(moduleClass);
+        if (!meta)
+            throw CoreError.invalidModule(moduleClass);
+        return meta;
+    }
+    /**
+     * Merges base metadata with dynamic module config.
+     * Well-known keys are merged type-safely; augmented component keys
+     * (e.g. `routers: constructor[]`) are concatenated.
+     */
+    mergeMetadata(base, dynamic) {
+        const WELL_KNOWN = new Set([
+            'module',
+            'global',
+            'imports',
+            'providers',
+            'exports',
+        ]);
+        const result = {
+            global: dynamic.global ?? base.global,
+            imports: [...(base.imports ?? []), ...(dynamic.imports ?? [])],
+            providers: [...(base.providers ?? []), ...(dynamic.providers ?? [])],
+            exports: [...(base.exports ?? []), ...(dynamic.exports ?? [])],
+        };
+        const baseExtras = base;
+        const dynExtras = dynamic;
+        const resultExtras = result;
+        for (const key of Object.keys(base)) {
+            if (!WELL_KNOWN.has(key)) {
+                resultExtras[key] = baseExtras[key];
+            }
+        }
+        for (const key of Object.keys(dynamic)) {
+            if (WELL_KNOWN.has(key))
+                continue;
+            const dynArr = dynExtras[key];
+            if (!dynArr)
+                continue;
+            const baseArr = resultExtras[key];
+            resultExtras[key] = baseArr ? [...baseArr, ...dynArr] : [...dynArr];
+        }
+        return result;
+    }
+    /** Topological sort with global modules first. */
+    toposort(edges, globalIds) {
+        // Add edges: non-global modules depend on global modules.
+        // Skip transitive imports of global modules to avoid creating cycles.
+        const globalImports = this.collectTransitiveImports(globalIds);
+        for (const [id, node] of this.nodes) {
+            if (!node.isGlobal && !globalImports.has(id)) {
+                for (const globalId of globalIds) {
+                    edges.push([id, globalId]);
+                }
+            }
+        }
+        let sortedIds;
+        try {
+            sortedIds = toposort(edges).reverse();
+        }
+        catch (error) {
+            if (error instanceof Error &&
+                error.message.toLowerCase().includes('cycl')) {
+                // Circular module imports are allowed when lazy() breaks the
+                // provider-level cycle. Fall back to globals-first insertion order.
+                const globals = [];
+                const rest = [];
+                for (const id of this.nodes.keys()) {
+                    if (globalIds.has(id))
+                        globals.push(id);
+                    else
+                        rest.push(id);
+                }
+                sortedIds = [...globals, ...rest];
+            }
+            else {
+                throw error;
+            }
+        }
+        // Handle modules with no dependencies (not in any edge).
+        const allIds = new Set(this.nodes.keys());
+        const idsInEdges = new Set(sortedIds);
+        for (const id of allIds) {
+            if (!idsInEdges.has(id))
+                sortedIds.unshift(id);
+        }
+        return sortedIds.filter((id) => this.nodes.has(id));
+    }
+    /** Collects all transitive import IDs reachable from the given root IDs. */
+    collectTransitiveImports(rootIds) {
+        const visited = new Set();
+        const stack = [...rootIds];
+        while (stack.length > 0) {
+            const id = stack.pop();
+            const node = this.nodes.get(id);
+            if (!node)
+                continue;
+            for (const importId of node.importIds) {
+                if (!visited.has(importId)) {
+                    visited.add(importId);
+                    stack.push(importId);
+                }
+            }
+        }
+        return visited;
+    }
+    /** Creates Module instances and sets up relationships. */
+    buildModules() {
+        // First pass: create all Module instances.
+        for (const id of this.sortedIds) {
+            const node = this.nodes.get(id);
+            const mod = new Module({
+                id: node.id,
+                classRef: node.moduleClass,
+                metadata: node.metadata,
+                isGlobal: node.isGlobal,
+            });
+            for (const provider of node.metadata.providers ?? []) {
+                mod.addProvider(provider);
+            }
+            this.container.addModule(mod);
+        }
+        // Second pass: set up imports (now all modules exist).
+        for (const id of this.sortedIds) {
+            const node = this.nodes.get(id);
+            const mod = this.container.getModule(id);
+            for (const importedId of node.importIds) {
+                const importedModule = this.container.getModule(importedId);
+                if (importedModule)
+                    mod.addImport(importedModule);
+            }
+        }
+        // Third pass: register exports (imports must be wired first for module re-exports).
+        for (const id of this.sortedIds) {
+            const node = this.nodes.get(id);
+            const mod = this.container.getModule(id);
+            for (const token of node.metadata.exports ?? []) {
+                if (typeof token === 'function' && this.isImportedModule(mod, token)) {
+                    // Module re-export: copy all exported tokens from matching imported modules.
+                    for (const importedModule of mod.imports) {
+                        if (importedModule.classRef === token) {
+                            for (const exportedToken of importedModule.exports) {
+                                mod.addExport(exportedToken);
+                            }
+                        }
+                    }
+                }
+                else if (typeof token === 'function' && isModule(token)) {
+                    // Module class in exports but not imported — error.
+                    throw CoreError.moduleNotExported(token, mod.id);
+                }
+                else {
+                    mod.addExport(token);
+                }
+            }
+        }
+    }
+    /** Checks if a constructor is the classRef of any imported module. */
+    isImportedModule(mod, token) {
+        for (const importedModule of mod.imports) {
+            if (importedModule.classRef === token)
+                return true;
+        }
+        return false;
+    }
+}
+//# sourceMappingURL=module.graph.js.map