@stitchem/core 0.0.3

package/dist/test/test.module-builder.d.ts

@@ -0,0 +1,136 @@
+import type { Token } from '../token/token.types.js';
+import type { constructor } from '../core/core.types.js';
+import type { ModuleMetadata } from '../module/module.types.js';
+import type { ContextOptions } from '../context/context.js';
+import type { Provider } from '../provider/provider.interface.js';
+import type { Lifetime } from '../core/core.lifetime.js';
+import { TestModule } from './test.module.js';
+interface InjectableValueOverride {
+    kind: 'value';
+    ctor: constructor;
+    value: unknown;
+}
+interface InjectableClassOverride {
+    kind: 'class';
+    ctor: constructor;
+    useClass: constructor;
+}
+interface InjectableFactoryOverride {
+    kind: 'factory';
+    ctor: constructor;
+    factory: (...args: unknown[]) => unknown;
+    inject?: Token[];
+}
+type InjectableOverride = InjectableValueOverride | InjectableClassOverride | InjectableFactoryOverride;
+interface ComponentValueOverride {
+    kind: 'value';
+    classRef: constructor;
+    value: unknown;
+}
+interface ComponentClassOverride {
+    kind: 'class';
+    classRef: constructor;
+    useClass: constructor;
+}
+type ComponentOverride = ComponentValueOverride | ComponentClassOverride;
+/**
+ * Builder for creating a test module with provider overrides.
+ *
+ * @example
+ * ```ts
+ * const module = await Test.createModule({
+ *   imports: [UserModule, DbModule],
+ *   providers: [UserService],
+ * })
+ * .overrideProvider(DbService).useValue({ query: vi.fn() })
+ * .compile();
+ * ```
+ */
+export declare class TestModuleBuilder {
+    private readonly metadata;
+    private readonly overrides;
+    private readonly injectableOverrides;
+    private readonly componentOverrides;
+    constructor(metadata: ModuleMetadata);
+    /**
+     * Starts overriding a provider identified by its token.
+     * Returns an {@link OverrideBy} helper with `.useValue()`, `.useClass()`, etc.
+     */
+    overrideProvider(token: Token): OverrideBy;
+    /**
+     * Starts overriding an injectable (guard, filter, middleware, etc.) by class.
+     * Returns an {@link InjectableOverrideBy} helper with `.useValue()`,
+     * `.useClass()`, or `.useFactory()`.
+     */
+    overrideInjectable(ctor: constructor): InjectableOverrideBy;
+    /**
+     * Starts overriding a component (router, etc.) by class reference.
+     * Returns a {@link ComponentOverrideBy} helper with `.useValue()` or `.useClass()`.
+     */
+    overrideComponent(classRef: constructor): ComponentOverrideBy;
+    /**
+     * Compiles the test module.
+     * Builds the module graph, applies overrides, and resolves singletons.
+     */
+    compile(options?: ContextOptions): Promise<TestModule>;
+    /** @internal */
+    addOverride(provider: Provider): this;
+    /** @internal */
+    addInjectableOverride(override: InjectableOverride): this;
+    /** @internal */
+    addComponentOverride(override: ComponentOverride): this;
+}
+/**
+ * Fluent helper for specifying how to override a provider.
+ * Returned by {@link TestModuleBuilder.overrideProvider}.
+ */
+export declare class OverrideBy {
+    private readonly builder;
+    private readonly token;
+    constructor(builder: TestModuleBuilder, token: Token);
+    /** Override with a static value. */
+    useValue(value: unknown): TestModuleBuilder;
+    /** Override with a class. */
+    useClass(cls: constructor, lifetime?: Lifetime): TestModuleBuilder;
+    /** Override with a factory function. */
+    useFactory(options: {
+        factory: (...args: unknown[]) => unknown;
+        inject?: Token[];
+        lifetime?: Lifetime;
+    }): TestModuleBuilder;
+    /** Override with an alias to another token. */
+    useExisting(existingToken: Token): TestModuleBuilder;
+}
+/**
+ * Fluent helper for specifying how to override an injectable.
+ * Returned by {@link TestModuleBuilder.overrideInjectable}.
+ */
+export declare class InjectableOverrideBy {
+    private readonly builder;
+    private readonly ctor;
+    constructor(builder: TestModuleBuilder, ctor: constructor);
+    /** Override with a static value (mock instance). */
+    useValue(value: unknown): TestModuleBuilder;
+    /** Override with a replacement class (resolved via DI). */
+    useClass(cls: constructor): TestModuleBuilder;
+    /** Override with a factory function. */
+    useFactory(options: {
+        factory: (...args: unknown[]) => unknown;
+        inject?: Token[];
+    }): TestModuleBuilder;
+}
+/**
+ * Fluent helper for specifying how to override a component.
+ * Returned by {@link TestModuleBuilder.overrideComponent}.
+ */
+export declare class ComponentOverrideBy {
+    private readonly builder;
+    private readonly classRef;
+    constructor(builder: TestModuleBuilder, classRef: constructor);
+    /** Override with a static value (skip DI instantiation entirely). */
+    useValue(value: unknown): TestModuleBuilder;
+    /** Override with a different class (instantiated via DI). */
+    useClass(cls: constructor): TestModuleBuilder;
+}
+export {};
+//# sourceMappingURL=test.module-builder.d.ts.map

package/dist/test/test.module-builder.js

@@ -0,0 +1,377 @@
+var __esDecorate = (this && this.__esDecorate) || function (ctor, descriptorIn, decorators, contextIn, initializers, extraInitializers) {
+    function accept(f) { if (f !== void 0 && typeof f !== "function") throw new TypeError("Function expected"); return f; }
+    var kind = contextIn.kind, key = kind === "getter" ? "get" : kind === "setter" ? "set" : "value";
+    var target = !descriptorIn && ctor ? contextIn["static"] ? ctor : ctor.prototype : null;
+    var descriptor = descriptorIn || (target ? Object.getOwnPropertyDescriptor(target, contextIn.name) : {});
+    var _, done = false;
+    for (var i = decorators.length - 1; i >= 0; i--) {
+        var context = {};
+        for (var p in contextIn) context[p] = p === "access" ? {} : contextIn[p];
+        for (var p in contextIn.access) context.access[p] = contextIn.access[p];
+        context.addInitializer = function (f) { if (done) throw new TypeError("Cannot add initializers after decoration has completed"); extraInitializers.push(accept(f || null)); };
+        var result = (0, decorators[i])(kind === "accessor" ? { get: descriptor.get, set: descriptor.set } : descriptor[key], context);
+        if (kind === "accessor") {
+            if (result === void 0) continue;
+            if (result === null || typeof result !== "object") throw new TypeError("Object expected");
+            if (_ = accept(result.get)) descriptor.get = _;
+            if (_ = accept(result.set)) descriptor.set = _;
+            if (_ = accept(result.init)) initializers.unshift(_);
+        }
+        else if (_ = accept(result)) {
+            if (kind === "field") initializers.unshift(_);
+            else descriptor[key] = _;
+        }
+    }
+    if (target) Object.defineProperty(target, contextIn.name, descriptor);
+    done = true;
+};
+var __runInitializers = (this && this.__runInitializers) || function (thisArg, initializers, value) {
+    var useValue = arguments.length > 2;
+    for (var i = 0; i < initializers.length; i++) {
+        value = useValue ? initializers[i].call(thisArg, value) : initializers[i].call(thisArg);
+    }
+    return useValue ? value : void 0;
+};
+import { module as moduleDecorator } 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 { Scope } from '../context/scope.js';
+import { hasOnReady } from '../core/core.lifecycle.js';
+import { getProviderToken } from '../provider/provider.guards.js';
+import { TestModule } from './test.module.js';
+// ---------------------------------------------------------------------------
+// TestModuleBuilder
+// ---------------------------------------------------------------------------
+/**
+ * Builder for creating a test module with provider overrides.
+ *
+ * @example
+ * ```ts
+ * const module = await Test.createModule({
+ *   imports: [UserModule, DbModule],
+ *   providers: [UserService],
+ * })
+ * .overrideProvider(DbService).useValue({ query: vi.fn() })
+ * .compile();
+ * ```
+ */
+export class TestModuleBuilder {
+    metadata;
+    overrides = [];
+    injectableOverrides = [];
+    componentOverrides = [];
+    constructor(metadata) {
+        this.metadata = metadata;
+    }
+    /**
+     * Starts overriding a provider identified by its token.
+     * Returns an {@link OverrideBy} helper with `.useValue()`, `.useClass()`, etc.
+     */
+    overrideProvider(token) {
+        return new OverrideBy(this, token);
+    }
+    /**
+     * Starts overriding an injectable (guard, filter, middleware, etc.) by class.
+     * Returns an {@link InjectableOverrideBy} helper with `.useValue()`,
+     * `.useClass()`, or `.useFactory()`.
+     */
+    overrideInjectable(ctor) {
+        return new InjectableOverrideBy(this, ctor);
+    }
+    /**
+     * Starts overriding a component (router, etc.) by class reference.
+     * Returns a {@link ComponentOverrideBy} helper with `.useValue()` or `.useClass()`.
+     */
+    overrideComponent(classRef) {
+        return new ComponentOverrideBy(this, classRef);
+    }
+    /**
+     * Compiles the test module.
+     * Builds the module graph, applies overrides, and resolves singletons.
+     */
+    async compile(options) {
+        let TestRootModule = (() => {
+            let _classDecorators = [moduleDecorator(this.metadata)];
+            let _classDescriptor;
+            let _classExtraInitializers = [];
+            let _classThis;
+            var TestRootModule = class {
+                static { _classThis = this; }
+                static {
+                    const _metadata = typeof Symbol === "function" && Symbol.metadata ? Object.create(null) : void 0;
+                    __esDecorate(null, _classDescriptor = { value: _classThis }, _classDecorators, { kind: "class", name: _classThis.name, metadata: _metadata }, null, _classExtraInitializers);
+                    TestRootModule = _classThis = _classDescriptor.value;
+                    if (_metadata) Object.defineProperty(_classThis, Symbol.metadata, { enumerable: true, configurable: true, writable: true, value: _metadata });
+                    __runInitializers(_classThis, _classExtraInitializers);
+                }
+            };
+            return TestRootModule = _classThis;
+        })();
+        const container = new Container();
+        const moduleGraph = new ModuleGraph(TestRootModule, container);
+        const injector = new Injector(container);
+        const componentKeys = options?.componentKeys ?? [];
+        // Register ModuleRef factory per module.
+        for (const id of moduleGraph.sortedIds) {
+            const mod = container.getModule(id);
+            mod.addProvider({
+                provide: ModuleRef,
+                useFactory: () => new ModuleRef(container, injector, mod),
+            });
+        }
+        // Apply provider overrides across all modules.
+        for (const override of this.overrides) {
+            const token = getProviderToken(override);
+            for (const id of moduleGraph.sortedIds) {
+                const mod = container.getModule(id);
+                if (mod.hasProvider(token)) {
+                    mod.addProvider(override);
+                }
+            }
+        }
+        // Apply value-based injectable overrides immediately (pre-populate cache).
+        for (const override of this.injectableOverrides) {
+            if (override.kind !== 'value')
+                continue;
+            for (const id of moduleGraph.sortedIds) {
+                const mod = container.getModule(id);
+                mod.setInjectable(override.ctor, override.value);
+            }
+        }
+        // Rebuild global exports after overrides.
+        container.buildGlobalExports();
+        const rootModule = container.getModule(moduleGraph.rootModuleId);
+        // Eagerly resolve singletons and instantiate module classes.
+        const instantiatedModules = new Map();
+        for (const id of moduleGraph.sortedIds) {
+            const mod = container.getModule(id);
+            for (const [, wrapper] of mod.providers) {
+                if (!wrapper.isSingleton || wrapper.isResolved())
+                    continue;
+                await injector.loadInstance(wrapper, mod, Scope.STATIC);
+            }
+            const existing = instantiatedModules.get(mod.classRef);
+            if (existing !== undefined) {
+                mod.instance = existing;
+                continue;
+            }
+            const instance = await injector.instantiateClass(mod.classRef, mod);
+            mod.instance = instance;
+            instantiatedModules.set(mod.classRef, instance);
+        }
+        // Apply class/factory injectable overrides (may depend on resolved providers).
+        for (const override of this.injectableOverrides) {
+            if (override.kind === 'value')
+                continue;
+            let instance;
+            if (override.kind === 'class') {
+                instance = await injector.instantiateClassGlobal(override.useClass, Scope.STATIC);
+            }
+            else {
+                const deps = [];
+                for (const token of override.inject ?? []) {
+                    const { wrapper, module: depMod } = container.getProviderByTokenGlobal(token);
+                    deps.push(await injector.loadInstance(wrapper, depMod, Scope.STATIC));
+                }
+                const result = override.factory(...deps);
+                instance = result instanceof Promise ? await result : result;
+            }
+            if (hasOnReady(instance)) {
+                await instance.onReady();
+            }
+            for (const id of moduleGraph.sortedIds) {
+                const mod = container.getModule(id);
+                mod.setInjectable(override.ctor, instance);
+            }
+        }
+        // Build component override lookup (last override wins).
+        const componentOverrideMap = new Map();
+        for (const override of this.componentOverrides) {
+            componentOverrideMap.set(override.classRef, override);
+        }
+        // Resolve components.
+        for (const id of moduleGraph.sortedIds) {
+            const mod = container.getModule(id);
+            const meta = mod.metadata;
+            for (const key of componentKeys) {
+                const classes = meta[key];
+                if (!Array.isArray(classes))
+                    continue;
+                for (const cls of classes) {
+                    const override = componentOverrideMap.get(cls);
+                    if (override?.kind === 'value') {
+                        mod.addComponent(key, override.value, cls);
+                    }
+                    else if (override?.kind === 'class') {
+                        const instance = await injector.instantiateClass(override.useClass, mod);
+                        mod.addComponent(key, instance, cls);
+                    }
+                    else {
+                        const instance = await injector.instantiateClass(cls, mod);
+                        mod.addComponent(key, instance, cls);
+                    }
+                }
+            }
+        }
+        // Fire onReady lifecycle.
+        for (const id of moduleGraph.sortedIds) {
+            const mod = container.getModule(id);
+            for (const [, wrapper] of mod.providers) {
+                if (!wrapper.isSingleton)
+                    continue;
+                const instance = wrapper.getInstance(Scope.STATIC);
+                if (instance !== undefined && hasOnReady(instance)) {
+                    await instance.onReady();
+                }
+            }
+            if (mod.instance !== undefined && hasOnReady(mod.instance)) {
+                await mod.instance.onReady();
+            }
+            for (const key of componentKeys) {
+                for (const entry of mod.getComponents(key)) {
+                    if (hasOnReady(entry.instance)) {
+                        await entry.instance.onReady();
+                    }
+                }
+            }
+        }
+        return new TestModule(container, injector, rootModule, moduleGraph.sortedIds);
+    }
+    /** @internal */
+    addOverride(provider) {
+        this.overrides.push(provider);
+        return this;
+    }
+    /** @internal */
+    addInjectableOverride(override) {
+        this.injectableOverrides.push(override);
+        return this;
+    }
+    /** @internal */
+    addComponentOverride(override) {
+        this.componentOverrides.push(override);
+        return this;
+    }
+}
+// ---------------------------------------------------------------------------
+// OverrideBy (providers)
+// ---------------------------------------------------------------------------
+/**
+ * Fluent helper for specifying how to override a provider.
+ * Returned by {@link TestModuleBuilder.overrideProvider}.
+ */
+export class OverrideBy {
+    builder;
+    token;
+    constructor(builder, token) {
+        this.builder = builder;
+        this.token = token;
+    }
+    /** Override with a static value. */
+    useValue(value) {
+        return this.builder.addOverride({
+            provide: this.token,
+            useValue: value,
+        });
+    }
+    /** Override with a class. */
+    useClass(cls, lifetime) {
+        const provider = {
+            provide: this.token,
+            useClass: cls,
+            lifetime,
+        };
+        return this.builder.addOverride(provider);
+    }
+    /** Override with a factory function. */
+    useFactory(options) {
+        const provider = {
+            provide: this.token,
+            useFactory: options.factory,
+            inject: options.inject,
+            lifetime: options.lifetime,
+        };
+        return this.builder.addOverride(provider);
+    }
+    /** Override with an alias to another token. */
+    useExisting(existingToken) {
+        return this.builder.addOverride({
+            provide: this.token,
+            useExisting: existingToken,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// InjectableOverrideBy
+// ---------------------------------------------------------------------------
+/**
+ * Fluent helper for specifying how to override an injectable.
+ * Returned by {@link TestModuleBuilder.overrideInjectable}.
+ */
+export class InjectableOverrideBy {
+    builder;
+    ctor;
+    constructor(builder, ctor) {
+        this.builder = builder;
+        this.ctor = ctor;
+    }
+    /** Override with a static value (mock instance). */
+    useValue(value) {
+        return this.builder.addInjectableOverride({
+            kind: 'value',
+            ctor: this.ctor,
+            value,
+        });
+    }
+    /** Override with a replacement class (resolved via DI). */
+    useClass(cls) {
+        return this.builder.addInjectableOverride({
+            kind: 'class',
+            ctor: this.ctor,
+            useClass: cls,
+        });
+    }
+    /** Override with a factory function. */
+    useFactory(options) {
+        return this.builder.addInjectableOverride({
+            kind: 'factory',
+            ctor: this.ctor,
+            factory: options.factory,
+            inject: options.inject,
+        });
+    }
+}
+// ---------------------------------------------------------------------------
+// ComponentOverrideBy
+// ---------------------------------------------------------------------------
+/**
+ * Fluent helper for specifying how to override a component.
+ * Returned by {@link TestModuleBuilder.overrideComponent}.
+ */
+export class ComponentOverrideBy {
+    builder;
+    classRef;
+    constructor(builder, classRef) {
+        this.builder = builder;
+        this.classRef = classRef;
+    }
+    /** Override with a static value (skip DI instantiation entirely). */
+    useValue(value) {
+        return this.builder.addComponentOverride({
+            kind: 'value',
+            classRef: this.classRef,
+            value,
+        });
+    }
+    /** Override with a different class (instantiated via DI). */
+    useClass(cls) {
+        return this.builder.addComponentOverride({
+            kind: 'class',
+            classRef: this.classRef,
+            useClass: cls,
+        });
+    }
+}
+//# sourceMappingURL=test.module-builder.js.map

package/dist/test/test.module.d.ts

@@ -0,0 +1,71 @@
+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/module.js';
+import { Scope } from '../context/scope.js';
+import { ModuleRef } from '../module/module.ref.js';
+/**
+ * A compiled test module.
+ * Provides resolution and lifecycle management for test scenarios.
+ *
+ * @example
+ * ```ts
+ * await using module = await Test.createModule({
+ *   imports: [UserModule],
+ *   providers: [UserService],
+ * }).compile();
+ *
+ * const userService = await module.resolve(UserService);
+ * ```
+ */
+export declare class TestModule implements AsyncDisposable {
+    private readonly container;
+    private readonly injector;
+    private readonly rootModule;
+    private readonly sortedIds;
+    private disposed;
+    /** @internal */
+    constructor(container: Container, injector: Injector, rootModule: Module, sortedIds: readonly string[]);
+    /** Resolves a provider by token from the root module. */
+    resolve<T>(token: Token<T>, scope?: Scope): Promise<T>;
+    /** Synchronously resolves a provider by token. */
+    resolveSync<T>(token: Token<T>, scope?: Scope): T;
+    /** Navigates to a specific module for resolution. */
+    select<T extends constructor>(moduleClass: T): ModuleRef;
+    /** Returns all component instances for a given metadata key. */
+    getComponents<T = unknown>(key: string): ComponentRef<T>[];
+    /**
+     * Resolves an injectable class with global dependency resolution.
+     *
+     * Dependencies are always resolved globally and the instance is cached
+     * on the root module. This makes TestModule satisfy the InjectableHost
+     * structural interface used by extension resolvers.
+     *
+     * @param ctor - The injectable class to resolve.
+     * @param _options - Accepted for InjectableHost compatibility; ignored
+     *   (TestModule always resolves globally, like Context).
+     */
+    resolveInjectable<T>(ctor: constructor<T>, _options?: {
+        strict?: boolean;
+    }): Promise<T>;
+    /** The DI container. For extension authors only. */
+    get $container(): Container;
+    /** The dependency injector. For extension authors only. */
+    get $injector(): Injector;
+    /** The root module of the test module graph. For extension authors only. */
+    get $rootModule(): Module;
+    /** Module IDs in topological order. For extension authors only. */
+    get $sortedIds(): readonly string[];
+    /** Creates a new disposable scope for scoped resolution. */
+    createScope(): Scope;
+    [Symbol.asyncDispose](): Promise<void>;
+    /**
+     * Disposes the test module.
+     * Call in afterEach/afterAll to clean up.
+     */
+    close(scope?: Scope): Promise<void>;
+    private ensureNotDisposed;
+}
+//# sourceMappingURL=test.module.d.ts.map