@stitchem/core 0.0.3

package/dist/decorator/inject.decorator.js

@@ -0,0 +1,78 @@
+// WeakMap-based metadata storage for accessor-injected properties.
+// 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();
+// Pending tokens accumulated by @inject() accessor decorators during class definition.
+// Flushed into `registry` by the class decorator (@injectable / @module).
+// This is needed because TC39 accessor decorators execute before the class decorator,
+// so the class constructor isn't available yet when @inject() runs.
+let pendingTokens = [];
+/**
+ * TC39 accessor decorator for property injection.
+ *
+ * Use this when you need to inject a dependency as a class property
+ * rather than through the constructor.
+ *
+ * Must be used on a class also decorated with @injectable() or @module().
+ *
+ * @example
+ * ```ts
+ * @injectable()
+ * class OrderService {
+ *   @inject(LOGGER) accessor logger!: ILogger;
+ * }
+ * ```
+ */
+export function inject(token) {
+    return function (_target, context) {
+        pendingTokens.push({ name: context.name, token });
+    };
+}
+/**
+ * Flushes pending @inject() tokens accumulated during class definition
+ * into the registry, keyed by the given class constructor.
+ *
+ * Called by class decorators (@injectable, @module) which run after accessor decorators.
+ *
+ * @internal
+ */
+export function flushPendingInjectTokens(target) {
+    if (pendingTokens.length === 0)
+        return;
+    let tokens = registry.get(target);
+    if (!tokens) {
+        tokens = new Map();
+        registry.set(target, tokens);
+    }
+    for (const { name, token } of pendingTokens) {
+        tokens.set(name, token);
+    }
+    pendingTokens = [];
+}
+/**
+ * Gets constructor injection tokens from a class's `static inject` array.
+ * These tokens are resolved in order and passed to the constructor.
+ *
+ * Returns an empty array if the class has no `static inject`.
+ *
+ * @example
+ * ```ts
+ * class UserService {
+ *   static inject = [UserRepository, LOGGER] as const;
+ *   constructor(readonly repo: UserRepository, readonly logger: ILogger) {}
+ * }
+ *
+ * getConstructorTokens(UserService); // [UserRepository, LOGGER]
+ * ```
+ */
+export function getConstructorTokens(target) {
+    return target.inject ?? [];
+}
+/**
+ * Gets all accessor-injected property tokens for a class.
+ * Returns a Map of property name → injection token, or undefined if none.
+ */
+export function getInjectTokens(target) {
+    return registry.get(target);
+}
+//# sourceMappingURL=inject.decorator.js.map

package/dist/decorator/injectable.decorator.d.ts

@@ -0,0 +1,45 @@
+import type { constructor } from '../core/core.types.js';
+import { Lifetime } from '../core/core.lifetime.js';
+/**
+ * Options for the @injectable decorator.
+ */
+export interface InjectableOptions {
+    /**
+     * The lifetime of the injectable.
+     * @default Lifetime.SINGLETON
+     */
+    lifetime?: Lifetime;
+}
+/**
+ * Metadata stored by @injectable decorator.
+ */
+export interface InjectableMetadata {
+    lifetime: Lifetime;
+}
+/**
+ * Marks a class as injectable, allowing it to be managed by the DI container.
+ *
+ * Uses TC39 class decorators. No reflect-metadata required.
+ *
+ * @example
+ * ```ts
+ * @injectable()
+ * class UserService {
+ *   static inject = [UserRepository, LOGGER];
+ *   constructor(readonly userRepo: UserRepository, readonly logger: ILogger) {}
+ * }
+ *
+ * @injectable({ lifetime: Lifetime.TRANSIENT })
+ * class RequestHandler {}
+ * ```
+ */
+export declare function injectable(options?: InjectableOptions): (target: constructor, _context: ClassDecoratorContext) => void;
+/**
+ * Checks if a class is decorated with @injectable().
+ */
+export declare function isInjectable(target: constructor): boolean;
+/**
+ * Gets the injectable metadata from a class, or undefined if not decorated.
+ */
+export declare function getInjectableMetadata(target: constructor): InjectableMetadata | undefined;
+//# sourceMappingURL=injectable.decorator.d.ts.map

package/dist/decorator/injectable.decorator.js

@@ -0,0 +1,46 @@
+import { Lifetime } from '../core/core.lifetime.js';
+import { flushPendingInjectTokens } from './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 injectable, allowing it to be managed by the DI container.
+ *
+ * Uses TC39 class decorators. No reflect-metadata required.
+ *
+ * @example
+ * ```ts
+ * @injectable()
+ * class UserService {
+ *   static inject = [UserRepository, LOGGER];
+ *   constructor(readonly userRepo: UserRepository, readonly logger: ILogger) {}
+ * }
+ *
+ * @injectable({ lifetime: Lifetime.TRANSIENT })
+ * class RequestHandler {}
+ * ```
+ */
+export function injectable(options) {
+    return function (target, _context) {
+        registry.set(target, {
+            lifetime: options?.lifetime ?? Lifetime.SINGLETON,
+        });
+        // 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 @injectable().
+ */
+export function isInjectable(target) {
+    return registry.has(target);
+}
+/**
+ * Gets the injectable metadata from a class, or undefined if not decorated.
+ */
+export function getInjectableMetadata(target) {
+    return registry.get(target);
+}
+//# sourceMappingURL=injectable.decorator.js.map

package/dist/errors/core.error.d.ts

@@ -0,0 +1,24 @@
+import type { Token } from '../token/token.types.js';
+import type { constructor } from '../core/core.types.js';
+import { ErrorCode } from './error.codes.js';
+/**
+ * Single error class for all core DI errors.
+ * Use `code` to distinguish error types and `context` for structured data.
+ */
+export declare class CoreError extends Error {
+    readonly code: ErrorCode;
+    readonly context: Record<string, unknown>;
+    constructor(code: ErrorCode, message: string, context?: Record<string, unknown>);
+    static circularDependency(path: Token[]): CoreError;
+    static scopedResolution(token: Token): CoreError;
+    static unknownDependency(token: Token, detail?: string): CoreError;
+    static invalidModule(moduleClass: constructor): CoreError;
+    static circularModuleDependency(detail: string): CoreError;
+    static moduleNotFound(moduleClass: constructor): CoreError;
+    static moduleNotExported(moduleClass: constructor, moduleId: string): CoreError;
+    static notInjectable(target: constructor): CoreError;
+    static invalidProvider(detail: string): CoreError;
+    static providerNotFound(token: Token, moduleId: string): CoreError;
+    static providerNotVisible(token: Token, moduleId: string): CoreError;
+}
+//# sourceMappingURL=core.error.d.ts.map

package/dist/errors/core.error.js

@@ -0,0 +1,59 @@
+import { formatToken } from '../token/token.utils.js';
+import { ErrorCode } from './error.codes.js';
+/**
+ * Single error class for all core DI errors.
+ * Use `code` to distinguish error types and `context` for structured data.
+ */
+export class CoreError extends Error {
+    code;
+    context;
+    constructor(code, message, context = {}) {
+        super(message);
+        this.name = 'CoreError';
+        this.code = code;
+        this.context = context;
+        Error.captureStackTrace(this, this.constructor);
+    }
+    // --- Injection errors ---
+    static circularDependency(path) {
+        const pathString = path.map(formatToken).join(' -> ');
+        return new CoreError(ErrorCode.CIRCULAR_DEPENDENCY, `Circular dependency detected: ${pathString}`, { path });
+    }
+    static scopedResolution(token) {
+        return new CoreError(ErrorCode.SCOPED_RESOLUTION, `Cannot resolve scoped dependency ${formatToken(token)} outside of a scope. Use context.createScope() to create a scoped context.`, { token });
+    }
+    static unknownDependency(token, detail) {
+        const tokenName = formatToken(token);
+        const message = detail
+            ? `Cannot resolve dependency "${tokenName}": ${detail}`
+            : `Cannot resolve dependency "${tokenName}"`;
+        return new CoreError(ErrorCode.UNKNOWN_DEPENDENCY, message, { token });
+    }
+    // --- Module errors ---
+    static invalidModule(moduleClass) {
+        return new CoreError(ErrorCode.INVALID_MODULE, `Class "${moduleClass.name}" is not a valid module. Did you forget @module()?`, { moduleClass });
+    }
+    static circularModuleDependency(detail) {
+        return new CoreError(ErrorCode.CIRCULAR_MODULE_DEPENDENCY, `Circular module dependency detected: ${detail}`);
+    }
+    static moduleNotFound(moduleClass) {
+        return new CoreError(ErrorCode.MODULE_NOT_FOUND, `Module "${moduleClass.name}" not found in container. Ensure it is imported in the module tree.`, { moduleClass });
+    }
+    static moduleNotExported(moduleClass, moduleId) {
+        return new CoreError(ErrorCode.MODULE_NOT_EXPORTED, `Module "${moduleClass.name}" is listed in exports of module "${moduleId}" but is not imported. A module must be imported before it can be re-exported.`, { moduleClass, moduleId });
+    }
+    // --- Provider errors ---
+    static notInjectable(target) {
+        return new CoreError(ErrorCode.NOT_INJECTABLE, `Class "${target.name}" is not injectable. Did you forget to add @injectable()?`, { target });
+    }
+    static invalidProvider(detail) {
+        return new CoreError(ErrorCode.INVALID_PROVIDER, `Invalid provider: ${detail}`);
+    }
+    static providerNotFound(token, moduleId) {
+        return new CoreError(ErrorCode.PROVIDER_NOT_FOUND, `Provider "${formatToken(token)}" not found when resolving from module "${moduleId}".`, { token, moduleId });
+    }
+    static providerNotVisible(token, moduleId) {
+        return new CoreError(ErrorCode.PROVIDER_NOT_VISIBLE, `Cannot resolve "${formatToken(token)}" from module "${moduleId}". The provider exists but is not visible. Ensure it is exported by an imported module or is a global export.`, { token, moduleId });
+    }
+}
+//# sourceMappingURL=core.error.js.map

package/dist/errors/error.codes.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Error codes for all stitchem DI errors.
+ */
+export declare enum ErrorCode {
+    CIRCULAR_DEPENDENCY = "CIRCULAR_DEPENDENCY",
+    SCOPED_RESOLUTION = "SCOPED_RESOLUTION",
+    UNKNOWN_DEPENDENCY = "UNKNOWN_DEPENDENCY",
+    INVALID_MODULE = "INVALID_MODULE",
+    CIRCULAR_MODULE_DEPENDENCY = "CIRCULAR_MODULE_DEPENDENCY",
+    MODULE_NOT_FOUND = "MODULE_NOT_FOUND",
+    MODULE_NOT_EXPORTED = "MODULE_NOT_EXPORTED",
+    NOT_INJECTABLE = "NOT_INJECTABLE",
+    INVALID_PROVIDER = "INVALID_PROVIDER",
+    PROVIDER_NOT_FOUND = "PROVIDER_NOT_FOUND",
+    PROVIDER_NOT_VISIBLE = "PROVIDER_NOT_VISIBLE"
+}
+//# sourceMappingURL=error.codes.d.ts.map

package/dist/errors/error.codes.js

@@ -0,0 +1,21 @@
+/**
+ * Error codes for all stitchem DI errors.
+ */
+export var ErrorCode;
+(function (ErrorCode) {
+    // Injection errors
+    ErrorCode["CIRCULAR_DEPENDENCY"] = "CIRCULAR_DEPENDENCY";
+    ErrorCode["SCOPED_RESOLUTION"] = "SCOPED_RESOLUTION";
+    ErrorCode["UNKNOWN_DEPENDENCY"] = "UNKNOWN_DEPENDENCY";
+    // Module errors
+    ErrorCode["INVALID_MODULE"] = "INVALID_MODULE";
+    ErrorCode["CIRCULAR_MODULE_DEPENDENCY"] = "CIRCULAR_MODULE_DEPENDENCY";
+    ErrorCode["MODULE_NOT_FOUND"] = "MODULE_NOT_FOUND";
+    ErrorCode["MODULE_NOT_EXPORTED"] = "MODULE_NOT_EXPORTED";
+    // Provider errors
+    ErrorCode["NOT_INJECTABLE"] = "NOT_INJECTABLE";
+    ErrorCode["INVALID_PROVIDER"] = "INVALID_PROVIDER";
+    ErrorCode["PROVIDER_NOT_FOUND"] = "PROVIDER_NOT_FOUND";
+    ErrorCode["PROVIDER_NOT_VISIBLE"] = "PROVIDER_NOT_VISIBLE";
+})(ErrorCode || (ErrorCode = {}));
+//# sourceMappingURL=error.codes.js.map

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+export { injectable } from './decorator/injectable.decorator.js';
+export { inject } from './decorator/inject.decorator.js';
+export { module } from './module/module.decorator.js';
+export type { constructor } from './core/core.types.js';
+export type { Token } from './token/token.types.js';
+export { Lifetime } from './core/core.lifetime.js';
+export { lazy } from './token/lazy.token.js';
+export { isConstructor } from './core/core.utils.js';
+export type { OnInit, OnDispose, OnReady } from './core/core.lifecycle.js';
+export type { Provider, ClassProvider, ValueProvider, FactoryProvider, ExistingProvider, } from './provider/provider.interface.js';
+export type { ModuleMetadata, DynamicModule, ModuleImport, } from './module/module.types.js';
+export { Context } from './context/context.js';
+export type { Scope } from './context/scope.js';
+export type { ResolveOptions, ContextOptions, LoggingOptions, ComponentRef, } from './context/context.js';
+export { ModuleRef } from './module/module.ref.js';
+export { CoreError } from './errors/core.error.js';
+export { ErrorCode } from './errors/error.codes.js';
+export type { Logger } from './logger/logger.types.js';
+export { LogLevel } from './logger/logger.types.js';
+export { LOGGER } from './logger/logger.token.js';
+export { ConsoleLogger } from './logger/console.logger.js';
+export { Test } from './test/test.js';
+export { TestModule } from './test/test.module.js';
+export { TestModuleBuilder } from './test/test.module-builder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,23 @@
+// Decorators
+export { injectable } from './decorator/injectable.decorator.js';
+export { inject } from './decorator/inject.decorator.js';
+export { module } from './module/module.decorator.js';
+export { Lifetime } from './core/core.lifetime.js';
+export { lazy } from './token/lazy.token.js';
+// Utilities
+export { isConstructor } from './core/core.utils.js';
+// Context
+export { Context } from './context/context.js';
+// Module reference
+export { ModuleRef } from './module/module.ref.js';
+// Errors
+export { CoreError } from './errors/core.error.js';
+export { ErrorCode } from './errors/error.codes.js';
+export { LogLevel } from './logger/logger.types.js';
+export { LOGGER } from './logger/logger.token.js';
+export { ConsoleLogger } from './logger/console.logger.js';
+// Testing
+export { Test } from './test/test.js';
+export { TestModule } from './test/test.module.js';
+export { TestModuleBuilder } from './test/test.module-builder.js';
+//# sourceMappingURL=index.js.map

package/dist/injector/injector.d.ts

@@ -0,0 +1,78 @@
+import type { constructor } from '../core/core.types.js';
+import type { InstanceWrapper } from '../instance-wrapper/instance-wrapper.js';
+import type { Module } from '../module/module.js';
+import { Scope } from '../context/scope.js';
+import { Container } from '../container/container.js';
+/**
+ * Handles dependency resolution and instance creation.
+ * Supports constructor injection (via `static inject`), accessor injection
+ * (via `@inject()` accessor decorator), and lazy proxies for circular deps.
+ */
+export declare class Injector {
+    private readonly container;
+    /** Tracks tokens currently being resolved (circular dependency detection). */
+    private readonly resolutionStack;
+    constructor(container: Container);
+    /**
+     * Resolves an instance from a wrapper (async).
+     * Handles caching, circular dependency detection, and lifecycle hooks.
+     *
+     * @throws CoreError (SCOPED_RESOLUTION) if resolving scoped without a scope
+     * @throws CoreError (CIRCULAR_DEPENDENCY) if a circular dependency is detected
+     */
+    loadInstance<T>(wrapper: InstanceWrapper<T>, module: Module, scope?: Scope): Promise<T>;
+    /**
+     * Resolves an instance from a wrapper (sync).
+     *
+     * @throws CoreError (SCOPED_RESOLUTION) if resolving scoped without a scope
+     * @throws CoreError (CIRCULAR_DEPENDENCY) if a circular dependency is detected
+     * @throws Error if async factory or async onInit is encountered
+     */
+    loadInstanceSync<T>(wrapper: InstanceWrapper<T>, module: Module, scope?: Scope): T;
+    /**
+     * Creates a new instance without caching.
+     * Useful for transient-like creation on demand.
+     *
+     * @throws CoreError (CIRCULAR_DEPENDENCY) if a circular dependency is detected
+     */
+    createUncached<T>(wrapper: InstanceWrapper<T>, module: Module, scope?: Scope): Promise<T>;
+    /**
+     * Instantiates any class by resolving its constructor and accessor dependencies.
+     * The class does not need to be registered as a provider or marked with @injectable().
+     */
+    instantiateClass<T>(ctor: constructor<T>, module: Module, scope?: Scope): Promise<T>;
+    /**
+     * Instantiates any class using global resolution (bypasses module visibility).
+     */
+    instantiateClassGlobal<T>(ctor: constructor<T>, scope?: Scope): Promise<T>;
+    /**
+     * Validates resolution preconditions and returns the cached instance if available.
+     * Returns null if the instance needs to be created.
+     *
+     * @throws CoreError (SCOPED_RESOLUTION) if resolving scoped without a scope
+     * @throws CoreError (CIRCULAR_DEPENDENCY) if a circular dependency is detected
+     */
+    private guardResolution;
+    /** Creates a resolver scoped to a specific module. */
+    private moduleResolver;
+    /** Creates a resolver that searches all modules (bypasses visibility). */
+    private globalResolver;
+    /** Creates an instance from a wrapper's provider (async). */
+    private createInstance;
+    /** Creates an instance from a wrapper's provider (sync). */
+    private createInstanceSync;
+    /** Resolves an array of dependency tokens (async). */
+    private resolveDependencies;
+    /** Resolves an array of dependency tokens (sync). */
+    private resolveDependenciesSync;
+    /** Injects accessor-decorated properties on an instance (async). */
+    private injectAccessorProperties;
+    /** Injects accessor-decorated properties on an instance (sync). */
+    private injectAccessorPropertiesSync;
+    /**
+     * Creates a lazy proxy that defers resolution until first property access.
+     * Used to break circular dependencies.
+     */
+    private createLazyProxy;
+}
+//# sourceMappingURL=injector.d.ts.map