@stitchem/core 0.0.3

package/dist/test/test.module.js

@@ -0,0 +1,151 @@
+import { Scope } from '../context/scope.js';
+import { ModuleRef } from '../module/module.ref.js';
+import { hasOnReady } from '../core/core.lifecycle.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 class TestModule {
+    container;
+    injector;
+    rootModule;
+    sortedIds;
+    disposed = false;
+    /** @internal */
+    constructor(container, injector, rootModule, sortedIds) {
+        this.container = container;
+        this.injector = injector;
+        this.rootModule = rootModule;
+        this.sortedIds = sortedIds;
+    }
+    /** Resolves a provider by token from the root module. */
+    async resolve(token, scope = Scope.STATIC) {
+        this.ensureNotDisposed();
+        const { wrapper, module } = this.container.getProviderByToken(token, this.rootModule);
+        return this.injector.loadInstance(wrapper, module, scope);
+    }
+    /** Synchronously resolves a provider by token. */
+    resolveSync(token, scope = Scope.STATIC) {
+        this.ensureNotDisposed();
+        const { wrapper, module } = this.container.getProviderByToken(token, this.rootModule);
+        return this.injector.loadInstanceSync(wrapper, module, scope);
+    }
+    /** Navigates to a specific module for resolution. */
+    select(moduleClass) {
+        this.ensureNotDisposed();
+        const module = this.container.getModuleByClass(moduleClass);
+        return new ModuleRef(this.container, this.injector, module);
+    }
+    /** Returns all component instances for a given metadata key. */
+    getComponents(key) {
+        this.ensureNotDisposed();
+        const refs = [];
+        for (const id of this.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;
+    }
+    /**
+     * 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).
+     */
+    async resolveInjectable(ctor, _options) {
+        this.ensureNotDisposed();
+        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;
+    }
+    // ---------------------------------------------------------------------------
+    // Extension internals (for extension authors building test wrappers)
+    // ---------------------------------------------------------------------------
+    /** The DI container. For extension authors only. */
+    get $container() {
+        return this.container;
+    }
+    /** The dependency injector. For extension authors only. */
+    get $injector() {
+        return this.injector;
+    }
+    /** The root module of the test module graph. For extension authors only. */
+    get $rootModule() {
+        return this.rootModule;
+    }
+    /** Module IDs in topological order. For extension authors only. */
+    get $sortedIds() {
+        return this.sortedIds;
+    }
+    /** Creates a new disposable scope for scoped resolution. */
+    createScope() {
+        this.ensureNotDisposed();
+        return Scope.create((scope) => this.close(scope));
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    /**
+     * Disposes the test module.
+     * Call in afterEach/afterAll to clean up.
+     */
+    async close(scope) {
+        if (this.disposed && !scope)
+            return;
+        if (!scope) {
+            // Dispose injectables → components → providers.
+            const moduleIds = [...this.sortedIds].reverse();
+            for (const id of moduleIds) {
+                const module = this.container.getModule(id);
+                if (module)
+                    await module.disposeInjectables();
+            }
+            for (const id of moduleIds) {
+                const module = this.container.getModule(id);
+                if (module)
+                    await module.disposeComponents();
+            }
+        }
+        await this.container.dispose(scope);
+        if (!scope) {
+            this.disposed = true;
+        }
+    }
+    ensureNotDisposed() {
+        if (this.disposed) {
+            throw new Error('TestModule has been closed.');
+        }
+    }
+}
+//# sourceMappingURL=test.module.js.map

package/dist/token/lazy.token.d.ts

@@ -0,0 +1,44 @@
+import type { Token } from './token.types.js';
+/**
+ * Metadata key for lazy tokens.
+ */
+export declare const LAZY_BRAND: unique symbol;
+/**
+ * A lazy token that defers resolution until first property access.
+ * Used to break circular dependencies between providers.
+ */
+export interface LazyToken<T = unknown> {
+    readonly [LAZY_BRAND]: true;
+    readonly factory: () => Token<T>;
+}
+/**
+ * Wraps a token factory to enable lazy resolution, breaking circular dependencies.
+ *
+ * When a provider depends on another provider that creates a circular dependency,
+ * wrap the token with `lazy()` to defer its resolution until first access.
+ * Only one side of the cycle needs to use `lazy()`.
+ *
+ * @example
+ * ```ts
+ * @injectable()
+ * class ServiceA {
+ *   static inject = [lazy(() => ServiceB)];
+ *   constructor(private b: ServiceB) {}
+ * }
+ *
+ * @injectable()
+ * class ServiceB {
+ *   static inject = [ServiceA];
+ *   constructor(private a: ServiceA) {}
+ * }
+ * ```
+ *
+ * @param factory - A function that returns the injection token (deferred to handle forward references)
+ * @returns A lazy token that the injector resolves on first property access
+ */
+export declare function lazy<T>(factory: () => Token<T>): LazyToken<T>;
+/**
+ * Type guard that checks if a value is a lazy token.
+ */
+export declare function isLazyToken(value: unknown): value is LazyToken;
+//# sourceMappingURL=lazy.token.d.ts.map

package/dist/token/lazy.token.js

@@ -0,0 +1,42 @@
+/**
+ * Metadata key for lazy tokens.
+ */
+export const LAZY_BRAND = Symbol.for('stitchem:lazy');
+/**
+ * Wraps a token factory to enable lazy resolution, breaking circular dependencies.
+ *
+ * When a provider depends on another provider that creates a circular dependency,
+ * wrap the token with `lazy()` to defer its resolution until first access.
+ * Only one side of the cycle needs to use `lazy()`.
+ *
+ * @example
+ * ```ts
+ * @injectable()
+ * class ServiceA {
+ *   static inject = [lazy(() => ServiceB)];
+ *   constructor(private b: ServiceB) {}
+ * }
+ *
+ * @injectable()
+ * class ServiceB {
+ *   static inject = [ServiceA];
+ *   constructor(private a: ServiceA) {}
+ * }
+ * ```
+ *
+ * @param factory - A function that returns the injection token (deferred to handle forward references)
+ * @returns A lazy token that the injector resolves on first property access
+ */
+export function lazy(factory) {
+    return { [LAZY_BRAND]: true, factory };
+}
+/**
+ * Type guard that checks if a value is a lazy token.
+ */
+export function isLazyToken(value) {
+    return (value !== null &&
+        typeof value === 'object' &&
+        LAZY_BRAND in value &&
+        value[LAZY_BRAND]);
+}
+//# sourceMappingURL=lazy.token.js.map

package/dist/token/token.types.d.ts

@@ -0,0 +1,8 @@
+import type { constructor } from '../core/core.types.js';
+import type { LazyToken } from './lazy.token.js';
+/**
+ * A token that can be used to identify a dependency.
+ * Can be a class constructor, abstract class, string, symbol, or lazy token.
+ */
+export type Token<T = unknown> = constructor<T> | LazyToken<T> | string | symbol;
+//# sourceMappingURL=token.types.d.ts.map

package/dist/token/token.types.js

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

package/dist/token/token.utils.d.ts

@@ -0,0 +1,9 @@
+import type { Token } from './token.types.js';
+/**
+ * Formats a token for display in error messages and debugging.
+ *
+ * @param token - The injection token to format
+ * @returns A human-readable string representation of the token
+ */
+export declare function formatToken(token: Token): string;
+//# sourceMappingURL=token.utils.d.ts.map

package/dist/token/token.utils.js

@@ -0,0 +1,19 @@
+import { isLazyToken } from './lazy.token.js';
+/**
+ * Formats a token for display in error messages and debugging.
+ *
+ * @param token - The injection token to format
+ * @returns A human-readable string representation of the token
+ */
+export function formatToken(token) {
+    if (typeof token === 'function')
+        return token.name;
+    if (typeof token === 'symbol')
+        return token.description ?? token.toString();
+    if (isLazyToken(token)) {
+        const inner = token.factory();
+        return `lazy(${formatToken(inner)})`;
+    }
+    return String(token);
+}
+//# sourceMappingURL=token.utils.js.map

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@stitchem/core",
+  "version": "0.0.3",
+  "description": "Extensible modular dependency injection for TypeScript",
+  "author": {
+    "name": "hexac",
+    "url": "https://existin.space",
+    "email": "hexac@existin.space"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/eishexac/stitchem.git",
+    "directory": "core"
+  },
+  "homepage": "https://github.com/eishexac/stitchem/tree/release/#readme",
+  "bugs": "https://github.com/eishexac/stitchem/issues",
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "@source": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "dependencies": {
+    "log-symbols": "^7.0.1",
+    "picocolors": "^1.1.1",
+    "toposort": "^2.0.2",
+    "uuid": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/toposort": "^2.0.7"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.2"
+  },
+  "scripts": {
+    "build": "rimraf dist && tsc -p tsconfig.build.json",
+    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
+    "type:check": "tsc --noEmit",
+    "lint": "eslint \"src/**/*.ts\" \"test/**/*.ts\"",
+    "lint:fix": "eslint \"src/**/*.ts\" \"test/**/*.ts\" --fix",
+    "test": "vitest run",
+    "test:unit": "vitest run --project unit",
+    "test:int": "vitest run --project int",
+    "test:e2e": "vitest run --project e2e",
+    "test:coverage": "vitest run --coverage"
+  }
+}