@illuma/core 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1,78 +1,8 @@
-import { N as NodeBase, P as Provider, T as Token, M as MultiNodeToken, a as NodeToken, C as Ctor } from './providers-D9YA8L_g.cjs';
-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.cjs';
-export { E as ExtractInjectedType, N as NodeInjectFn, i as iNodeInjectorOptions, n as nodeInject } from './injection-CSxu56ds.cjs';
-import { i as iInjectionNode, T as TreeNode, I as Illuma } from './plugin-container-D8Zwpigq.cjs';
-
-/** @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;
-}
+import { C as Ctor, N as NodeToken, a as NodeBase, P as Provider, T as Token, M as MultiNodeToken } from './token-BvQrvm-Q.cjs';
+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 './token-BvQrvm-Q.cjs';
+import { i as iNodeInjectorOptions, E as ExtractInjectedType } from './injection-CJGqGWJ6.cjs';
+export { N as NodeInjectFn, n as nodeInject } from './injection-CJGqGWJ6.cjs';
+import { i as iInjectionNode, T as TreeNode, I as Illuma } from './plugin-container-n0FIqLbh.cjs';
 
 /**
  * Symbol used to mark classes as injectable and store their associated token.
@@ -132,6 +62,47 @@ declare function getInjectableToken<T>(ctor: Ctor<T> & {
 }): NodeToken<T>;
 declare function isConstructor(fn: unknown): fn is Ctor<any>;
 
+/** @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>>;
+}
+
 /**
  * Configuration options for the NodeContainer.
  */
@@ -142,9 +113,57 @@ interface iContainerOptions {
      * @default false
      */
     measurePerformance?: boolean;
+    /**
+     * When true, enables diagnostics reporting after bootstrap.
+     * @default false
+     */
     diagnostics?: boolean;
+    /**
+     * @internal
+     * The parent container for hierarchical dependency resolution.
+     */
     parent?: iDIContainer;
+    /**
+     * @experimental
+     * Whether to instantiate dependencies immediately.
+     * If disabled, providers instantiation will happen when first requested.
+     * This helps improve startup performance for large containers.
+     * Enabled by default until stable.
+     *
+     * @default true
+     */
+    instant?: boolean;
+}
+/**
+ * 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;
 }
+
 declare class NodeContainer extends Illuma implements iDIContainer {
     private readonly _opts?;
     private _bootstrapped;
@@ -238,6 +257,24 @@ declare class NodeContainer extends Illuma implements iDIContainer {
     produce<T>(fn: Ctor<T> | (() => T)): T;
 }
 
+declare const ERR_CODES: {
+    readonly DUPLICATE_PROVIDER: 100;
+    readonly DUPLICATE_FACTORY: 101;
+    readonly INVALID_CTOR: 102;
+    readonly INVALID_PROVIDER: 103;
+    readonly INVALID_ALIAS: 200;
+    readonly LOOP_ALIAS: 201;
+    readonly NOT_BOOTSTRAPPED: 300;
+    readonly BOOTSTRAPPED: 301;
+    readonly DOUBLE_BOOTSTRAP: 302;
+    readonly NOT_FOUND: 400;
+    readonly CIRCULAR_DEPENDENCY: 401;
+    readonly UNTRACKED: 500;
+    readonly OUTSIDE_CONTEXT: 501;
+    readonly CALLED_UTILS_OUTSIDE_CONTEXT: 502;
+    readonly INSTANCE_ACCESS_FAILED: 503;
+    readonly ACCESS_FAILED: 504;
+};
 declare class InjectionError extends Error {
     readonly code: number;
     constructor(code: number, message: string);
@@ -259,6 +296,12 @@ declare class InjectionError extends Error {
     static accessFailed(): InjectionError;
 }
 
+declare function injectDefer<N>(token: N, options: iNodeInjectorOptions & {
+    optional: true;
+}): () => N extends MultiNodeToken<infer V> ? V[] : N extends NodeToken<infer U> ? U | null : N extends new (...args: any[]) => infer T ? T | null : never;
+declare function injectDefer<N>(token: N, options?: iNodeInjectorOptions): () => N extends MultiNodeToken<infer V> ? V[] : N extends NodeToken<infer U> ? U : N extends new (...args: any) => infer T ? T : never;
+declare function injectDefer<N extends NodeToken<unknown> | MultiNodeToken<unknown>>(token: N, options?: iNodeInjectorOptions): () => ExtractInjectedType<N>;
+
 interface iInjector {
     /** The DI container associated with this injector */
     readonly container: iDIContainer;
@@ -300,6 +343,7 @@ declare class InjectorImpl implements iInjector {
  * @example
  * ```typescript
  * import { Injector, nodeInject, NodeInjectable, NodeContainer } from "@illuma/core";
+import { iDIContainer } from '../container/types';
  *
  * @NodeInjectable()
  * class MyService {
@@ -375,4 +419,4 @@ declare function injectEntryAsync<T>(fn: MaybeAsyncFactory<iEntrypointConfig<Nod
 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 };
+export { Ctor, ExtractInjectedType, ERR_CODES as ILLUMA_ERR_CODES, INJECTION_SYMBOL, InjectionContext, InjectionError, Injector, type InjectorFn, InjectorImpl, MultiNodeToken, NodeBase, NodeContainer, NodeInjectable, NodeToken, Provider, Token, getInjectableToken, type iEntrypointConfig, iInjectionNode, type iInjector, iNodeInjectorOptions, injectAsync, injectDefer, injectEntryAsync, injectGroupAsync, isConstructor, isInjectable, makeInjectable };

package/dist/index.d.ts

@@ -1,78 +1,8 @@
-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;
-}
+import { C as Ctor, N as NodeToken, a as NodeBase, P as Provider, T as Token, M as MultiNodeToken } from './token-BvQrvm-Q.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 './token-BvQrvm-Q.js';
+import { i as iNodeInjectorOptions, E as ExtractInjectedType } from './injection-D22uAh1O.js';
+export { N as NodeInjectFn, n as nodeInject } from './injection-D22uAh1O.js';
+import { i as iInjectionNode, T as TreeNode, I as Illuma } from './plugin-container-CUw26ZhP.js';
 
 /**
  * Symbol used to mark classes as injectable and store their associated token.
@@ -132,6 +62,47 @@ declare function getInjectableToken<T>(ctor: Ctor<T> & {
 }): NodeToken<T>;
 declare function isConstructor(fn: unknown): fn is Ctor<any>;
 
+/** @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>>;
+}
+
 /**
  * Configuration options for the NodeContainer.
  */
@@ -142,9 +113,57 @@ interface iContainerOptions {
      * @default false
      */
     measurePerformance?: boolean;
+    /**
+     * When true, enables diagnostics reporting after bootstrap.
+     * @default false
+     */
     diagnostics?: boolean;
+    /**
+     * @internal
+     * The parent container for hierarchical dependency resolution.
+     */
     parent?: iDIContainer;
+    /**
+     * @experimental
+     * Whether to instantiate dependencies immediately.
+     * If disabled, providers instantiation will happen when first requested.
+     * This helps improve startup performance for large containers.
+     * Enabled by default until stable.
+     *
+     * @default true
+     */
+    instant?: boolean;
+}
+/**
+ * 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;
 }
+
 declare class NodeContainer extends Illuma implements iDIContainer {
     private readonly _opts?;
     private _bootstrapped;
@@ -238,6 +257,24 @@ declare class NodeContainer extends Illuma implements iDIContainer {
     produce<T>(fn: Ctor<T> | (() => T)): T;
 }
 
+declare const ERR_CODES: {
+    readonly DUPLICATE_PROVIDER: 100;
+    readonly DUPLICATE_FACTORY: 101;
+    readonly INVALID_CTOR: 102;
+    readonly INVALID_PROVIDER: 103;
+    readonly INVALID_ALIAS: 200;
+    readonly LOOP_ALIAS: 201;
+    readonly NOT_BOOTSTRAPPED: 300;
+    readonly BOOTSTRAPPED: 301;
+    readonly DOUBLE_BOOTSTRAP: 302;
+    readonly NOT_FOUND: 400;
+    readonly CIRCULAR_DEPENDENCY: 401;
+    readonly UNTRACKED: 500;
+    readonly OUTSIDE_CONTEXT: 501;
+    readonly CALLED_UTILS_OUTSIDE_CONTEXT: 502;
+    readonly INSTANCE_ACCESS_FAILED: 503;
+    readonly ACCESS_FAILED: 504;
+};
 declare class InjectionError extends Error {
     readonly code: number;
     constructor(code: number, message: string);
@@ -259,6 +296,12 @@ declare class InjectionError extends Error {
     static accessFailed(): InjectionError;
 }
 
+declare function injectDefer<N>(token: N, options: iNodeInjectorOptions & {
+    optional: true;
+}): () => N extends MultiNodeToken<infer V> ? V[] : N extends NodeToken<infer U> ? U | null : N extends new (...args: any[]) => infer T ? T | null : never;
+declare function injectDefer<N>(token: N, options?: iNodeInjectorOptions): () => N extends MultiNodeToken<infer V> ? V[] : N extends NodeToken<infer U> ? U : N extends new (...args: any) => infer T ? T : never;
+declare function injectDefer<N extends NodeToken<unknown> | MultiNodeToken<unknown>>(token: N, options?: iNodeInjectorOptions): () => ExtractInjectedType<N>;
+
 interface iInjector {
     /** The DI container associated with this injector */
     readonly container: iDIContainer;
@@ -300,6 +343,7 @@ declare class InjectorImpl implements iInjector {
  * @example
  * ```typescript
  * import { Injector, nodeInject, NodeInjectable, NodeContainer } from "@illuma/core";
+import { iDIContainer } from '../container/types';
  *
  * @NodeInjectable()
  * class MyService {
@@ -375,4 +419,4 @@ declare function injectEntryAsync<T>(fn: MaybeAsyncFactory<iEntrypointConfig<Nod
 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 };
+export { Ctor, ExtractInjectedType, ERR_CODES as ILLUMA_ERR_CODES, INJECTION_SYMBOL, InjectionContext, InjectionError, Injector, type InjectorFn, InjectorImpl, MultiNodeToken, NodeBase, NodeContainer, NodeInjectable, NodeToken, Provider, Token, getInjectableToken, type iEntrypointConfig, iInjectionNode, type iInjector, iNodeInjectorOptions, injectAsync, injectDefer, injectEntryAsync, injectGroupAsync, isConstructor, isInjectable, makeInjectable };