@illuma/core 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,378 @@
+import { N as NodeBase, P as Provider, T as Token, M as MultiNodeToken, a as NodeToken, C as Ctor } from './providers-D9YA8L_g.js';
+export { e as extractToken, g as iNodeAliasProvider, f as iNodeClassProvider, d as iNodeFactoryProvider, h as iNodeProvider, b as iNodeTokenBaseOptions, c as iNodeValueProvider, i as isNodeBase } from './providers-D9YA8L_g.js';
+export { E as ExtractInjectedType, N as NodeInjectFn, i as iNodeInjectorOptions, n as nodeInject } from './injection-Y_bVmBSk.js';
+import { i as iInjectionNode, T as TreeNode, I as Illuma } from './plugin-container-CwkVlVS4.js';
+
+/** @internal */
+type InjectorFn = (token: NodeBase<any>, optional?: boolean) => any;
+/**
+ * Internal context manager for tracking dependency injections during factory execution.
+ * This class manages the injection context lifecycle and tracks all injection calls.
+ *
+ * @internal
+ */
+declare abstract class InjectionContext {
+    static contextOpen: boolean;
+    static readonly _calls: Set<iInjectionNode<any>>;
+    static injector: InjectorFn | null;
+    private static readonly _scanners;
+    /**
+     * Adds a dependency to the current injection context.
+     * Called by `nodeInject` when a dependency is requested.
+     *
+     * @param node - The injection node representing the dependency
+     * @throws {InjectionError} If called outside of an active injection context
+     */
+    static addDep(node: iInjectionNode<any>): void;
+    /**
+     * Opens a new injection context.
+     * Resets the calls set and sets the injector if provided.
+     *
+     * @param injector - Optional injector function to use for resolving dependencies
+     */
+    /**
+     * Scans a factory function for dependencies.
+     * Executes the factory in a dry-run mode to capture `nodeInject` calls.
+     * Also runs registered context scanners.
+     *
+     * @param factory - The factory function to scan
+     * @returns A set of detected injection nodes
+     */
+    static open(injector?: InjectorFn): void;
+    static scan(factory: any): Set<iInjectionNode<any>>;
+    static instantiate<T>(factory: () => T, injector: InjectorFn): T;
+    static closeAndReport(): Set<iInjectionNode<any>>;
+}
+
+/**
+ * Interface for dependency injection containers.
+ * Defines the core methods that all DI containers must implement.
+ */
+interface iDIContainer {
+    /**
+     * Registers a provider in the container.
+     * @template T - The type of value being provided
+     * @param provider - The provider configuration
+     */
+    provide<T>(provider: Provider<T>): void;
+    /**
+     * @internal Finds the tree node associated with the given token.
+     * @template T - The type of value being searched
+     * @param token - The token or constructor to find
+     * @returns The associated tree node, or null if not found
+     */
+    findNode<T>(token: Token<T>): TreeNode<T> | null;
+    /**
+     * Retrieves an instance for the given token.
+     * @template T - The type of value being retrieved
+     * @param token - The token or constructor to retrieve
+     * @returns The resolved instance
+     */
+    get<T>(token: MultiNodeToken<T>): T[];
+    get<T>(token: NodeToken<T>): T;
+    get<T>(token: Ctor<T>): T;
+    produce<T>(fn: Ctor<T> | (() => T)): T;
+}
+
+/**
+ * Symbol used to mark classes as injectable and store their associated token.
+ * @internal
+ */
+declare const INJECTION_SYMBOL: unique symbol;
+/**
+ * Decorator that marks a class as injectable in the dependency injection system.
+ * Automatically creates and associates a NodeToken with the class.
+ *
+ * @template T - The type of the class being decorated
+ * @returns A class decorator function
+ *
+ * @example
+ * ```typescript
+ * @NodeInjectable()
+ * class UserService {
+ *   public getUser() {
+ *     return { id: 1, name: 'John' };
+ *   }
+ * }
+ *
+ * container.provide(UserService);
+ * container.bootstrap();
+ * const service = container.get(UserService);
+ * ```
+ */
+declare function NodeInjectable<T>(): (ctor: Ctor<T>) => Ctor<T>;
+/**
+ * Alternative function to mark a class as injectable in the dependency injection system for environments
+ * that do not support decorators.
+ * @param ctor
+ * @returns
+ *
+ * @example
+ * ```typescript
+ * import { makeInjectable } from '@illuma/core';
+ *
+ * class _UserService {
+ *   public getUser() {
+ *     return { id: 1, name: "John Doe" };
+ *    }
+ * }
+ *
+ * export type UserService = _UserService;
+ * export const UserService = makeInjectable(_UserService);
+ * ```
+ */
+declare function makeInjectable<T>(ctor: Ctor<T>): Ctor<T>;
+/** @internal */
+declare function isInjectable<T>(ctor: unknown): ctor is Ctor<T> & {
+    [INJECTION_SYMBOL]: NodeToken<T>;
+};
+/** @internal */
+declare function getInjectableToken<T>(ctor: Ctor<T> & {
+    [INJECTION_SYMBOL]: NodeToken<T>;
+}): NodeToken<T>;
+declare function isConstructor(fn: unknown): fn is Ctor<any>;
+
+/**
+ * Configuration options for the NodeContainer.
+ */
+interface iContainerOptions {
+    /**
+     * When true, logs the bootstrap time to the console based on performance.now()
+     * difference before and after bootstrap.
+     * @default false
+     */
+    measurePerformance?: boolean;
+    diagnostics?: boolean;
+    parent?: iDIContainer;
+}
+declare class NodeContainer extends Illuma implements iDIContainer {
+    private readonly _opts?;
+    private _bootstrapped;
+    private _rootNode?;
+    private readonly _parent?;
+    private readonly _protoNodes;
+    private readonly _multiProtoNodes;
+    constructor(_opts?: iContainerOptions | undefined);
+    /**
+     * Registers a provider in the container.
+     * Must be called before {@link bootstrap}.
+     *
+     * @template T - The type of value being provided
+     * @param provider - The provider configuration (token, class, or provider object)
+     * @throws {InjectionError} If called after bootstrap or if a duplicate provider is detected
+     *
+     * @example
+     * ```typescript
+     * // Provide a value
+     * container.provide({ provide: CONFIG_TOKEN, value: { apiKey: '123' } });
+     *
+     * // Provide a factory
+     * container.provide({ provide: LOGGER_TOKEN, factory: () => new ConsoleLogger() });
+     *
+     * // Provide an injectable class directly
+     * container.provide(UserService);
+     *
+     * // Provide a class override
+     * container.provide({ provide: ServiceClass, useClass: ServiceOverride });
+     * ```
+     */
+    provide<T>(provider: Provider<T>): void;
+    findNode<T>(token: Token<T>): TreeNode<T> | null;
+    private _getFromParent;
+    private _buildInjectionTree;
+    /**
+     * Bootstraps the container by resolving the dependency trees and instantiating all providers.
+     * This must be called after all providers are registered and before calling {@link get}.
+     *
+     * The bootstrap process:
+     * 1. Validates all provider registrations
+     * 2. Builds dependency injection trees
+     * 3. Detects circular dependencies in each tree
+     * 4. Instantiates all dependencies in the correct order
+     *
+     * @throws {InjectionError} If the container is already bootstrapped or if circular dependencies are detected
+     *
+     * @example
+     * ```typescript
+     * const container = new NodeContainer();
+     * container.provide(UserService);
+     * container.provide(LoggerService);
+     * container.bootstrap(); // Resolves and instantiates all dependencies
+     * ```
+     */
+    bootstrap(): void;
+    /**
+     * Retrieves an instance from the container.
+     * Must be called after {@link bootstrap}.
+     *
+     * @template T - The type of value being retrieved (typically inferred)
+     * @param token - The token or class to retrieve
+     * @returns For NodeToken: a single instance. For MultiNodeToken: an array of instances.
+     * @throws {InjectionError} If called before bootstrap or if the token is not found
+     *
+     * @example
+     * ```typescript
+     * // Get a single provider
+     * const logger = container.get(LoggerToken);
+     *
+     * // Get a decorated class
+     * const service = container.get(UserService);
+     *
+     * // Get multiple providers
+     * const plugins = container.get(PluginToken); // Returns array
+     * ```
+     */
+    get<T>(token: MultiNodeToken<T>): T[];
+    get<T>(token: NodeToken<T>): T;
+    get<T>(token: Ctor<T>): T;
+    /**
+     * Instantiates a class outside injection context. Primarily used to create instances via Injector.
+     * Class does not get registered in the container and cannot be retrieved via {@link get} or {@link nodeInject}.
+     * Must be called after {@link bootstrap}.
+     *
+     * @template T - The type of the class being instantiated
+     * @param factory - Factory or class constructor to instantiate
+     * @returns A new instance of the class with dependencies injected
+     * @throws {InjectionError} If called before bootstrap or if the constructor is invalid
+     */
+    produce<T>(fn: Ctor<T> | (() => T)): T;
+}
+
+declare class InjectionError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+    static duplicate(token: NodeBase<unknown>): InjectionError;
+    static duplicateFactory(token: NodeBase<unknown>): InjectionError;
+    static invalidCtor(ctor: Ctor<unknown>): InjectionError;
+    static invalidProvider(provider: string): InjectionError;
+    static invalidAlias(alias: unknown): InjectionError;
+    static loopAlias(alias: NodeBase<unknown>): InjectionError;
+    static notBootstrapped(): InjectionError;
+    static bootstrapped(): InjectionError;
+    static doubleBootstrap(): InjectionError;
+    static notFound(token: NodeBase<unknown>): InjectionError;
+    static circularDependency(provider: NodeBase<unknown> | Ctor<unknown>, path: (NodeBase<unknown> | Ctor<unknown>)[]): InjectionError;
+    static untracked(token: NodeBase<unknown> | Ctor<unknown>, parent: NodeBase<unknown> | Ctor<unknown>): InjectionError;
+    static outsideContext(token: NodeBase<unknown> | Ctor<unknown>): InjectionError;
+    static calledUtilsOutsideContext(): InjectionError;
+    static instanceAccessFailed(token: NodeBase<unknown>): InjectionError;
+    static accessFailed(): InjectionError;
+}
+
+interface iInjector {
+    /** The DI container associated with this injector */
+    readonly container: iDIContainer;
+    /**
+     * Retrieves an instance for the given token.
+     * @template T - The type of value being retrieved
+     * @param token - The token or constructor to retrieve
+     * @returns The resolved instance
+     */
+    get<T>(token: MultiNodeToken<T>): T[];
+    get<T>(token: NodeToken<T>): T;
+    get<T>(token: Ctor<T>): T;
+    /**
+     * Instantiates a class with injections in runtime using current context.
+     * Useful when creating an object that requires injections in runtime.
+     * Class does not get registered in the container and cannot be retrieved via {@link get} or {@link nodeInject}.
+     *
+     * @template T - The type of the class being instantiated
+     * @param ctor - The constructor of the class to instantiate
+     * @returns A new instance of the class with dependencies injected
+     * @throws {InjectionError} If called before bootstrap or if the constructor is invalid
+     * Must be called after {@link bootstrap}.
+     */
+    produce<T>(fn: Ctor<T> | (() => T)): T;
+}
+/**
+ * Injector implementation that allows retrieving instances from the parent DI container.
+ */
+declare class InjectorImpl implements iInjector {
+    readonly container: iDIContainer;
+    constructor(container: iDIContainer);
+    get<T>(token: MultiNodeToken<T>): T[];
+    get<T>(token: NodeToken<T>): T;
+    get<T>(token: Ctor<T>): T;
+    produce<T>(fn: Ctor<T> | (() => T)): T;
+}
+/**
+ * Injector node that is used to access provider outside of injection context.
+ * @example
+ * ```typescript
+ * import { Injector, nodeInject, NodeInjectable, NodeContainer } from "@illuma/core";
+ *
+ * @NodeInjectable()
+ * class MyService {
+ *   private readonly _injector = nodeInject(Injector);
+ *   public doSomething() {
+ *     const otherService = this._injector.get(OtherService);
+ *     // Use otherService...
+ *   }
+ * }
+ * ```
+ */
+declare const Injector: NodeToken<iInjector>;
+
+type MaybeAsyncFactory<T> = () => T | Promise<T>;
+interface iInjectionOptions {
+    /**
+     * Whether to cache the result of the injection function
+     * Prevents multiple invocations from creating multiple sub-containers or injections
+     * @default true
+     */
+    withCache?: boolean;
+    /**
+     * Overrides to provide to the sub-container
+     * These will be provided in addition to the main injection
+     * @default []
+     */
+    overrides?: Provider[];
+}
+/**
+ * Creates an async function that injects a group of dependencies as a sub-container.
+ * The returned function, when called, will create a new sub-container, provide the given dependencies,
+ * bootstrap it, and return its injector.
+ *
+ * @note
+ * `injectGroupAsync` should be called within an injection context where the parent container is accessible.
+ *
+ * @param fn - A function that returns an array of providers or a promise resolving to one
+ * @returns A function that returns a promise resolving to the injector of the sub-container
+ */
+declare function injectGroupAsync(fn: MaybeAsyncFactory<Provider[]>, opts?: iInjectionOptions): () => Promise<iInjector>;
+/**
+ * Creates an async function that injects a dependency for the given token or constructor.
+ * The returned function, when called, will create a new sub-container,
+ * provide the token or constructor, bootstrap it, and return the resolved instance(s).
+ *
+ * @note
+ * `injectAsync` should be called within an injection context where the parent container is accessible.
+ *
+ * @template T - The type of value being injected
+ * @param fn - A function that returns a token, constructor, or a promise resolving to one
+ * @returns A function that returns a promise resolving to the injected instance(s)
+ */
+declare function injectAsync<T>(fn: MaybeAsyncFactory<MultiNodeToken<T>>, opts?: iInjectionOptions): () => Promise<T[]>;
+declare function injectAsync<T>(fn: MaybeAsyncFactory<NodeToken<T>>, opts?: iInjectionOptions): () => Promise<T>;
+declare function injectAsync<T>(fn: MaybeAsyncFactory<Ctor<T>>, opts?: iInjectionOptions): () => Promise<T>;
+interface iEntrypointConfig<T extends Token<any>> {
+    readonly entrypoint: T;
+    readonly providers: Provider[];
+}
+/**
+ * Creates an async function that injects a sub-container with a specific entrypoint.
+ * The returned function, when called, will create a new sub-container,
+ * provide the given providers, bootstrap it, and return the resolved instance(s) of the entrypoint.
+ *
+ * @note
+ * `injectEntryAsync` should be called within an injection context where the parent container is accessible.
+ *
+ * @template T - The type of the entrypoint token
+ * @param fn - A function that returns an entrypoint configuration or a promise resolving to one
+ * @returns A function that returns a promise resolving to the injected instance(s) of the entrypoint
+ */
+declare function injectEntryAsync<T>(fn: MaybeAsyncFactory<iEntrypointConfig<NodeToken<T>>>, opts?: iInjectionOptions): () => Promise<T[]>;
+declare function injectEntryAsync<T>(fn: MaybeAsyncFactory<iEntrypointConfig<Ctor<T>>>, opts?: iInjectionOptions): () => Promise<T>;
+declare function injectEntryAsync<T>(fn: MaybeAsyncFactory<iEntrypointConfig<MultiNodeToken<T>>>, opts?: iInjectionOptions): () => Promise<T>;
+
+export { Ctor, INJECTION_SYMBOL, InjectionContext, InjectionError, Injector, type InjectorFn, InjectorImpl, MultiNodeToken, NodeBase, NodeContainer, NodeInjectable, NodeToken, Provider, Token, getInjectableToken, type iDIContainer, type iEntrypointConfig, iInjectionNode, type iInjector, injectAsync, injectEntryAsync, injectGroupAsync, isConstructor, isInjectable, makeInjectable };