@stitchem/core 0.0.3

package/dist/module/module.js

@@ -0,0 +1,181 @@
+import { InstanceWrapper } from '../instance-wrapper/instance-wrapper.js';
+import { hasOnDispose } from '../core/core.lifecycle.js';
+import { isConstructorProvider, isClassProvider, getProviderToken, } from '../provider/provider.guards.js';
+import { isInjectable } from '../decorator/injectable.decorator.js';
+import { CoreError } from '../errors/core.error.js';
+/**
+ * Represents a module instance with its own providers.
+ * Each module maintains its own provider registry and visibility rules.
+ */
+export class Module {
+    /** Unique identifier for this module instance. */
+    id;
+    /** The module class. */
+    classRef;
+    /** Whether this is a global module. */
+    isGlobal;
+    /** Original metadata from @module decorator + dynamic config. */
+    metadata;
+    /** Provider storage (token -> InstanceWrapper). */
+    _providers = new Map();
+    /** Exported tokens. */
+    _exports = new Set();
+    /** Imported modules. */
+    _imports = new Set();
+    /** Registration order for disposal. */
+    _registrationOrder = [];
+    /** Component instances keyed by metadata key (e.g. 'routers'). */
+    _components = new Map();
+    /** Injectable instances (guards, filters, middleware, etc.) keyed by class ref. */
+    _injectables = new Map();
+    /** Insertion order for injectable disposal. */
+    _injectableOrder = [];
+    /** Module instance (the instantiated module class). */
+    _instance;
+    constructor(options) {
+        this.id = options.id;
+        this.classRef = options.classRef;
+        this.metadata = options.metadata;
+        this.isGlobal = options.isGlobal ?? false;
+    }
+    /** All providers in this module. */
+    get providers() {
+        return this._providers;
+    }
+    /** All exported tokens. */
+    get exports() {
+        return this._exports;
+    }
+    /** All imported modules. */
+    get imports() {
+        return this._imports;
+    }
+    /** The module class instance. */
+    get instance() {
+        return this._instance;
+    }
+    set instance(value) {
+        this._instance = value;
+    }
+    /**
+     * Adds a provider to this module.
+     * Validates that class-based providers have @injectable().
+     *
+     * @throws CoreError (NOT_INJECTABLE) if a class provider lacks @injectable()
+     */
+    addProvider(provider) {
+        this.validateProvider(provider);
+        const wrapper = InstanceWrapper.fromProvider(provider);
+        const token = getProviderToken(provider);
+        this._providers.set(token, wrapper);
+        this._registrationOrder.push(token);
+        return wrapper;
+    }
+    /** Gets a provider by token. */
+    getProvider(token) {
+        return this._providers.get(token);
+    }
+    /** Checks if a provider exists in this module. */
+    hasProvider(token) {
+        return this._providers.has(token);
+    }
+    /** Adds an export token. */
+    addExport(token) {
+        this._exports.add(token);
+    }
+    /** Adds an imported module. */
+    addImport(mod) {
+        this._imports.add(mod);
+    }
+    /** Registers a component instance under a metadata key. */
+    addComponent(key, instance, classRef) {
+        let entries = this._components.get(key);
+        if (!entries) {
+            entries = [];
+            this._components.set(key, entries);
+        }
+        entries.push({ instance, classRef });
+    }
+    /** Returns component instances for a metadata key. */
+    getComponents(key) {
+        return this._components.get(key) ?? [];
+    }
+    /** Returns a cached injectable instance, or undefined if not resolved yet. */
+    getInjectable(ctor) {
+        return this._injectables.get(ctor);
+    }
+    /** Caches an injectable instance and tracks insertion order. */
+    setInjectable(ctor, instance) {
+        if (!this._injectables.has(ctor)) {
+            this._injectableOrder.push(ctor);
+        }
+        this._injectables.set(ctor, instance);
+    }
+    /** All cached injectables as [classRef, instance] pairs. */
+    get injectables() {
+        return this._injectables;
+    }
+    /** Disposes all injectable instances in reverse insertion order. */
+    async disposeInjectables() {
+        for (const ctor of [...this._injectableOrder].reverse()) {
+            const instance = this._injectables.get(ctor);
+            if (hasOnDispose(instance))
+                await instance.onDispose();
+        }
+        this._injectables.clear();
+        this._injectableOrder.length = 0;
+    }
+    /** Disposes all component instances in reverse order. */
+    async disposeComponents() {
+        for (const [, entries] of this._components) {
+            for (const { instance } of [...entries].reverse()) {
+                if (hasOnDispose(instance))
+                    await instance.onDispose();
+            }
+        }
+        this._components.clear();
+    }
+    /**
+     * Disposes provider instances in reverse registration order.
+     *
+     * - With scope: only dispose SCOPED instances for that scope
+     * - Without scope: dispose all SINGLETON instances (full shutdown)
+     */
+    async dispose(scope) {
+        const reversed = [...this._registrationOrder].reverse();
+        for (const token of reversed) {
+            const wrapper = this._providers.get(token);
+            if (!wrapper)
+                continue;
+            if (scope) {
+                if (wrapper.isScoped && wrapper.isResolved(scope)) {
+                    const instance = wrapper.getInstance(scope);
+                    if (hasOnDispose(instance))
+                        await instance.onDispose();
+                    wrapper.clear(scope);
+                }
+            }
+            else {
+                if (wrapper.isSingleton && wrapper.isResolved()) {
+                    const instance = wrapper.getInstance();
+                    if (hasOnDispose(instance))
+                        await instance.onDispose();
+                    wrapper.clear();
+                }
+            }
+        }
+    }
+    /**
+     * Validates a provider configuration.
+     * @throws CoreError (NOT_INJECTABLE) if a class provider lacks @injectable()
+     */
+    validateProvider(provider) {
+        if (isConstructorProvider(provider) && !isInjectable(provider)) {
+            throw CoreError.notInjectable(provider);
+        }
+        if (isClassProvider(provider) && !isInjectable(provider.useClass)) {
+            throw CoreError.notInjectable(provider.useClass);
+        }
+    }
+}
+//# sourceMappingURL=module.js.map

package/dist/module/module.ref.d.ts

@@ -0,0 +1,81 @@
+import type { Token } from '../token/token.types.js';
+import type { constructor } from '../core/core.types.js';
+import type { ComponentRef } from '../context/context.js';
+import type { Container } from '../container/container.js';
+import type { Injector } from '../injector/injector.js';
+import type { Module } from './module.js';
+import { Scope } from '../context/scope.js';
+/**
+ * Reference to a module, injectable into providers.
+ * Provides dynamic resolution, module navigation, and instance creation.
+ *
+ * @example
+ * ```ts
+ * @injectable()
+ * class DynamicService {
+ *   static inject = [ModuleRef] as const;
+ *   constructor(private moduleRef: ModuleRef) {}
+ *
+ *   async getService<T>(token: Token<T>): Promise<T> {
+ *     return this.moduleRef.resolve(token);
+ *   }
+ * }
+ * ```
+ */
+export declare class ModuleRef {
+    private readonly container;
+    private readonly injector;
+    private readonly module;
+    constructor(container: Container, injector: Injector, module: Module);
+    /** The module class. */
+    get moduleClass(): constructor;
+    /** The module's unique identifier. */
+    get id(): string;
+    /** Whether this is a global module. */
+    get isGlobal(): boolean;
+    /** Gets the module instance. */
+    get<T = unknown>(): T;
+    /**
+     * Resolves a dependency from this module's context.
+     * Respects module visibility (can only resolve visible tokens).
+     */
+    resolve<T>(token: Token<T>, scope?: Scope): Promise<T>;
+    /** Synchronously resolves a dependency from this module's context. */
+    resolveSync<T>(token: Token<T>, scope?: Scope): T;
+    /**
+     * Creates a new instance of a registered provider, bypassing cache.
+     * The class must be registered as a provider in this module.
+     *
+     * @throws CoreError (PROVIDER_NOT_FOUND) if the class is not registered
+     */
+    create<T>(ctor: constructor<T>, scope?: Scope): Promise<T>;
+    /**
+     * Instantiates any class by resolving its dependencies.
+     * The class does not need to be registered as a provider.
+     */
+    constructClass<T>(ctor: constructor<T>, scope?: Scope): Promise<T>;
+    /**
+     * Resolves an injectable class instance with caching and lifecycle hooks.
+     *
+     * Injectables are auxiliary classes (guards, filters, middleware, etc.)
+     * that participate in DI but are not registered as providers. They are
+     * cached on the module and receive full lifecycle support.
+     *
+     * @param ctor - The injectable class to resolve.
+     * @param options - Resolution options.
+     * @param options.strict - When `true` (default), resolves dependencies from
+     *   this module's visibility. When `false`, resolves globally.
+     * @returns The resolved instance (cached on subsequent calls).
+     */
+    resolveInjectable<T>(ctor: constructor<T>, options?: {
+        strict?: boolean;
+    }): Promise<T>;
+    /** Returns component instances for a given metadata key from this module. */
+    getComponents<T = unknown>(key: string): ComponentRef<T>[];
+    /**
+     * Navigates to a different module for resolution.
+     * Returns a new ModuleRef bound to the target module.
+     */
+    select<T extends constructor>(moduleClass: T): ModuleRef;
+}
+//# sourceMappingURL=module.ref.d.ts.map

package/dist/module/module.ref.js

@@ -0,0 +1,123 @@
+import { Scope } from '../context/scope.js';
+import { hasOnReady } from '../core/core.lifecycle.js';
+import { CoreError } from '../errors/core.error.js';
+/**
+ * Reference to a module, injectable into providers.
+ * Provides dynamic resolution, module navigation, and instance creation.
+ *
+ * @example
+ * ```ts
+ * @injectable()
+ * class DynamicService {
+ *   static inject = [ModuleRef] as const;
+ *   constructor(private moduleRef: ModuleRef) {}
+ *
+ *   async getService<T>(token: Token<T>): Promise<T> {
+ *     return this.moduleRef.resolve(token);
+ *   }
+ * }
+ * ```
+ */
+export class ModuleRef {
+    container;
+    injector;
+    module;
+    constructor(container, injector, module) {
+        this.container = container;
+        this.injector = injector;
+        this.module = module;
+    }
+    /** The module class. */
+    get moduleClass() {
+        return this.module.classRef;
+    }
+    /** The module's unique identifier. */
+    get id() {
+        return this.module.id;
+    }
+    /** Whether this is a global module. */
+    get isGlobal() {
+        return this.module.isGlobal;
+    }
+    /** Gets the module instance. */
+    get() {
+        return this.module.instance;
+    }
+    /**
+     * Resolves a dependency from this module's context.
+     * Respects module visibility (can only resolve visible tokens).
+     */
+    async resolve(token, scope = Scope.STATIC) {
+        const { wrapper, module } = this.container.getProviderByToken(token, this.module);
+        return this.injector.loadInstance(wrapper, module, scope);
+    }
+    /** Synchronously resolves a dependency from this module's context. */
+    resolveSync(token, scope = Scope.STATIC) {
+        const { wrapper, module } = this.container.getProviderByToken(token, this.module);
+        return this.injector.loadInstanceSync(wrapper, module, scope);
+    }
+    /**
+     * Creates a new instance of a registered provider, bypassing cache.
+     * The class must be registered as a provider in this module.
+     *
+     * @throws CoreError (PROVIDER_NOT_FOUND) if the class is not registered
+     */
+    async create(ctor, scope = Scope.STATIC) {
+        const wrapper = this.module.getProvider(ctor);
+        if (wrapper) {
+            return this.injector.createUncached(wrapper, this.module, scope);
+        }
+        throw CoreError.providerNotFound(ctor, this.module.id);
+    }
+    /**
+     * Instantiates any class by resolving its dependencies.
+     * The class does not need to be registered as a provider.
+     */
+    async constructClass(ctor, scope = Scope.STATIC) {
+        return this.injector.instantiateClass(ctor, this.module, scope);
+    }
+    /**
+     * Resolves an injectable class instance with caching and lifecycle hooks.
+     *
+     * Injectables are auxiliary classes (guards, filters, middleware, etc.)
+     * that participate in DI but are not registered as providers. They are
+     * cached on the module and receive full lifecycle support.
+     *
+     * @param ctor - The injectable class to resolve.
+     * @param options - Resolution options.
+     * @param options.strict - When `true` (default), resolves dependencies from
+     *   this module's visibility. When `false`, resolves globally.
+     * @returns The resolved instance (cached on subsequent calls).
+     */
+    async resolveInjectable(ctor, options) {
+        const cached = this.module.getInjectable(ctor);
+        if (cached)
+            return cached;
+        const scope = Scope.current() ?? Scope.STATIC;
+        const instance = await (options?.strict === false
+            ? this.injector.instantiateClassGlobal(ctor, scope)
+            : this.injector.instantiateClass(ctor, this.module, scope));
+        if (hasOnReady(instance)) {
+            await instance.onReady();
+        }
+        this.module.setInjectable(ctor, instance);
+        return instance;
+    }
+    /** Returns component instances for a given metadata key from this module. */
+    getComponents(key) {
+        return this.module.getComponents(key).map((entry) => ({
+            instance: entry.instance,
+            classRef: entry.classRef,
+            moduleRef: this,
+        }));
+    }
+    /**
+     * Navigates to a different module for resolution.
+     * Returns a new ModuleRef bound to the target module.
+     */
+    select(moduleClass) {
+        const module = this.container.getModuleByClass(moduleClass);
+        return new ModuleRef(this.container, this.injector, module);
+    }
+}
+//# sourceMappingURL=module.ref.js.map

package/dist/module/module.types.d.ts

@@ -0,0 +1,80 @@
+import type { constructor } from '../core/core.types.js';
+import type { Token } from '../token/token.types.js';
+import type { Provider } from '../provider/provider.interface.js';
+/**
+ * Metadata for a module declaration.
+ *
+ * Plugins can extend this interface via TypeScript declaration merging:
+ * @example
+ * ```ts
+ * declare module '@stitchem/core' {
+ *   interface ModuleMetadata {
+ *     controllers?: constructor[];
+ *   }
+ * }
+ * ```
+ */
+export interface ModuleMetadata {
+    /**
+     * Whether this module should be global.
+     * Global modules export their providers to all modules without explicit import.
+     */
+    global?: boolean;
+    /**
+     * Modules to import. Importing a module gives access to its exports.
+     * Can be module classes or DynamicModule objects from forRoot/forFeature.
+     */
+    imports?: ModuleImport[];
+    /**
+     * Providers registered in this module.
+     * Private by default — only accessible within this module.
+     */
+    providers?: Provider[];
+    /**
+     * Tokens or modules to export from this module.
+     * Exported providers become accessible to importing modules.
+     * Exporting a module class re-exports all of that module's exports.
+     */
+    exports?: (Token | constructor)[];
+}
+/**
+ * A dynamic module configuration returned by forRoot/forFeature static methods.
+ * Allows modules to be configured dynamically with additional providers.
+ *
+ * Extends ModuleMetadata so that augmented keys (e.g. `routers`) are
+ * automatically available on DynamicModule as well.
+ *
+ * @example
+ * ```ts
+ * class ConfigModule {
+ *   static forRoot(options: ConfigModuleOptions): DynamicModule {
+ *     return {
+ *       module: ConfigModule,
+ *       providers: [
+ *         { provide: CONFIG_OPTIONS, useValue: options },
+ *         ConfigService,
+ *       ],
+ *       exports: [ConfigService],
+ *       global: options.isGlobal,
+ *     };
+ *   }
+ * }
+ * ```
+ */
+export interface DynamicModule extends ModuleMetadata {
+    /** The module class. */
+    module: constructor;
+}
+/**
+ * A module import: either a class or a DynamicModule configuration.
+ */
+export type ModuleImport = constructor | DynamicModule;
+/**
+ * A module class decorated with @module().
+ */
+export type ModuleClass = constructor;
+/**
+ * Checks if a value is a DynamicModule.
+ */
+export declare function isDynamicModule(value: ModuleImport): value is DynamicModule;
+//# sourceMappingURL=module.types.d.ts.map

package/dist/module/module.types.js

@@ -0,0 +1,10 @@
+/**
+ * Checks if a value is a DynamicModule.
+ */
+export function isDynamicModule(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        'module' in value &&
+        typeof value.module === 'function');
+}
+//# sourceMappingURL=module.types.js.map

package/dist/provider/provider.guards.d.ts

@@ -0,0 +1,46 @@
+import type { constructor } from '../core/core.types.js';
+import type { Token } from '../token/token.types.js';
+import type { ClassProvider, ExistingProvider, FactoryProvider, Provider, ValueProvider } from './provider.interface.js';
+/**
+ * Type guard for ClassProvider.
+ *
+ * @param provider - The provider to check
+ * @returns True if the provider is a ClassProvider
+ */
+export declare function isClassProvider<T>(provider: Provider<T>): provider is ClassProvider<T>;
+/**
+ * Type guard for ValueProvider.
+ *
+ * @param provider - The provider to check
+ * @returns True if the provider is a ValueProvider
+ */
+export declare function isValueProvider<T>(provider: Provider<T>): provider is ValueProvider<T>;
+/**
+ * Type guard for FactoryProvider.
+ *
+ * @param provider - The provider to check
+ * @returns True if the provider is a FactoryProvider
+ */
+export declare function isFactoryProvider<T>(provider: Provider<T>): provider is FactoryProvider<T>;
+/**
+ * Type guard for ExistingProvider.
+ *
+ * @param provider - The provider to check
+ * @returns True if the provider is an ExistingProvider
+ */
+export declare function isExistingProvider<T>(provider: Provider<T>): provider is ExistingProvider<T>;
+/**
+ * Type guard to check if a provider is a class constructor (shorthand form).
+ *
+ * @param provider - The provider to check
+ * @returns True if the provider is a class constructor
+ */
+export declare function isConstructorProvider<T>(provider: Provider<T>): provider is constructor<T>;
+/**
+ * Extracts the token from a provider.
+ *
+ * @param provider - The provider to extract the token from
+ * @returns The injection token for the provider
+ */
+export declare function getProviderToken<T>(provider: Provider<T>): Token<T>;
+//# sourceMappingURL=provider.guards.d.ts.map

package/dist/provider/provider.guards.js

@@ -0,0 +1,62 @@
+/**
+ * Type guard for ClassProvider.
+ *
+ * @param provider - The provider to check
+ * @returns True if the provider is a ClassProvider
+ */
+export function isClassProvider(provider) {
+    return (typeof provider === 'object' && provider !== null && 'useClass' in provider);
+}
+/**
+ * Type guard for ValueProvider.
+ *
+ * @param provider - The provider to check
+ * @returns True if the provider is a ValueProvider
+ */
+export function isValueProvider(provider) {
+    return (typeof provider === 'object' && provider !== null && 'useValue' in provider);
+}
+/**
+ * Type guard for FactoryProvider.
+ *
+ * @param provider - The provider to check
+ * @returns True if the provider is a FactoryProvider
+ */
+export function isFactoryProvider(provider) {
+    return (typeof provider === 'object' &&
+        provider !== null &&
+        'useFactory' in provider);
+}
+/**
+ * Type guard for ExistingProvider.
+ *
+ * @param provider - The provider to check
+ * @returns True if the provider is an ExistingProvider
+ */
+export function isExistingProvider(provider) {
+    return (typeof provider === 'object' &&
+        provider !== null &&
+        'useExisting' in provider);
+}
+/**
+ * Type guard to check if a provider is a class constructor (shorthand form).
+ *
+ * @param provider - The provider to check
+ * @returns True if the provider is a class constructor
+ */
+export function isConstructorProvider(provider) {
+    return typeof provider === 'function';
+}
+/**
+ * Extracts the token from a provider.
+ *
+ * @param provider - The provider to extract the token from
+ * @returns The injection token for the provider
+ */
+export function getProviderToken(provider) {
+    if (isConstructorProvider(provider)) {
+        return provider;
+    }
+    return provider.provide;
+}
+//# sourceMappingURL=provider.guards.js.map

package/dist/provider/provider.interface.d.ts

@@ -0,0 +1,39 @@
+import type { constructor } from '../core/core.types.js';
+import type { Lifetime } from '../core/core.lifetime.js';
+import type { Token } from '../token/token.types.js';
+/**
+ * Provider that uses a class constructor.
+ */
+export interface ClassProvider<T = unknown> {
+    provide: Token<T>;
+    useClass: constructor<T>;
+    lifetime?: Lifetime;
+}
+/**
+ * Provider that uses a static value.
+ */
+export interface ValueProvider<T = unknown> {
+    provide: Token<T>;
+    useValue: T;
+}
+/**
+ * Provider that uses a factory function.
+ */
+export interface FactoryProvider<T = unknown> {
+    provide: Token<T>;
+    useFactory: (...args: any[]) => T | Promise<T>;
+    inject?: Token[];
+    lifetime?: Lifetime;
+}
+/**
+ * Provider that aliases another token.
+ */
+export interface ExistingProvider<T = unknown> {
+    provide: Token<T>;
+    useExisting: Token<T>;
+}
+/**
+ * Union of all provider types.
+ */
+export type Provider<T = unknown> = constructor<T> | ClassProvider<T> | ValueProvider<T> | FactoryProvider<T> | ExistingProvider<T>;
+//# sourceMappingURL=provider.interface.d.ts.map

package/dist/provider/provider.interface.js

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

package/dist/test/test.d.ts

@@ -0,0 +1,22 @@
+import type { ModuleMetadata } from '../module/module.types.js';
+import { TestModuleBuilder } from './test.module-builder.js';
+/**
+ * Entry point for the testing API.
+ *
+ * @example
+ * ```ts
+ * const module = await Test.createModule({
+ *   imports: [UserModule],
+ *   providers: [UserService],
+ * })
+ * .overrideProvider(DbService).useValue({ query: vi.fn() })
+ * .compile();
+ *
+ * const userService = await module.resolve(UserService);
+ * await module.close();
+ * ```
+ */
+export declare class Test {
+    static createModule(metadata: ModuleMetadata): TestModuleBuilder;
+}
+//# sourceMappingURL=test.d.ts.map

package/dist/test/test.js

@@ -0,0 +1,23 @@
+import { TestModuleBuilder } from './test.module-builder.js';
+/**
+ * Entry point for the testing API.
+ *
+ * @example
+ * ```ts
+ * const module = await Test.createModule({
+ *   imports: [UserModule],
+ *   providers: [UserService],
+ * })
+ * .overrideProvider(DbService).useValue({ query: vi.fn() })
+ * .compile();
+ *
+ * const userService = await module.resolve(UserService);
+ * await module.close();
+ * ```
+ */
+export class Test {
+    static createModule(metadata) {
+        return new TestModuleBuilder(metadata);
+    }
+}
+//# sourceMappingURL=test.js.map