@nexus-ioc/core 0.6.1 → 0.7.0

package/dist/types/core/nexus-applications.d.ts

@@ -1,30 +1,56 @@
-import { type HashUtilInterface, type InjectionToken, type Module, type NexusApplicationInterface, type ScannerPluginInterface } from "../interfaces";
+import { type BootstrapOptions, type CreateChildOptions, type DynamicModule, type GetOptions, type HashUtilInterface, type LazyModule, type NexusApplicationInterface, type ProviderToken, type ScannerPluginInterface, type Type, type UnloadResult } from "../interfaces";
+import { ModuleRef } from "./module-ref";
 /**
- * NexusApplications is the main application class that provides a high-level
+ * NexusApplication is the main application class that provides a high-level
  * API for creating and managing IoC containers.
  *
  * This class wraps the Container and provides additional features:
  * - Automatic singleton initialization
  * - Scanner plugin support for custom metadata processing
- * - Parent-child container hierarchies
- * - Async/sync container modes
+ * - Child containers for modules declared in `@Module({ children })`
+ * - Lazy/eager container modes
  *
  * @example
  * ```typescript
- * const app = NexusApplications.create(AppModule);
+ * const app = NexusApplication.create(AppModule);
  * await app.bootstrap();
- * const service = await app.get(MyService);
+ * const service = app.get(MyService);
  * ```
  */
-export declare class NexusApplications implements NexusApplicationInterface {
+export declare class NexusApplication implements NexusApplicationInterface {
     private readonly rootModule;
-    private hashUtil;
+    private readonly options?;
+    private readonly hashUtil;
     private isAsyncContainer;
+    /** Built in the constructor, once `hashUtil` honours `options.hashFn`. */
     private readonly container;
     private readonly scannerPlugins;
-    private _parentContainer;
+    private closePromise;
+    /** The parent chain; set only for children made by `createChild()`. */
+    private readonly link;
+    /** Removes this child from its parent's `liveChildren` once closed. */
+    private readonly onClosed;
     /**
-     * Creates a new NexusApplications instance.
+     * Token, in the parent graph, of the module that declares this child in
+     * `@Module({ children })`; the parent closes the child when an unload
+     * destroys that module.
+     */
+    private readonly declaredIn;
+    /**
+     * Children created by `createChild()` and not closed yet, in creation
+     * order. The only reference the parent keeps to a child.
+     */
+    private readonly liveChildren;
+    /**
+     * Lazy child code, per lazy ref id, with the token of the declaring
+     * module; a failed load is not cached, and an unload that destroys the
+     * declaring module drops the entry.
+     */
+    private readonly loadedChildren;
+    private readonly pendingLoads;
+    private readonly lazyModuleLoader;
+    /**
+     * Creates a new NexusApplication instance.
      *
      * @param rootModule - The root module of the application
      * @param options - Optional configuration
@@ -32,24 +58,77 @@ export declare class NexusApplications implements NexusApplicationInterface {
      */
     private constructor();
     /**
-     * Creates a new NexusApplications instance.
+     * Creates a new NexusApplication instance.
      *
      * This is the main entry point for creating an application.
      *
      * @param rootModule - The root module of the application
      * @param options - Optional configuration
      * @param options.hashFn - Custom hash function for module identification
-     * @returns A new NexusApplications instance
+     * @returns A new NexusApplication instance
      *
      * @example
      * ```typescript
-     * const app = NexusApplications.create(AppModule);
+     * const app = NexusApplication.create(AppModule);
      * await app.bootstrap();
      * ```
      */
-    static create(rootModule: Module, options?: {
+    static create(rootModule: Type, options?: {
         hashFn: new () => HashUtilInterface;
-    }): NexusApplications;
+    }): NexusApplication;
+    /**
+     * Creates a not-yet-bootstrapped child application. Private: the only
+     * public way to get a child is `createChild()`.
+     */
+    private static createAsChild;
+    /**
+     * Creates a child application for a module declared in
+     * `@Module({ children })` somewhere in this application's graph. The
+     * child is returned bootstrapped, with its singletons created.
+     *
+     * - `Type` matches a declared class; `DynamicModule` matches by its
+     *   `.module`; a `LazyModule` matches a declared ref by identity, and its
+     *   loader runs once per ref (a failed load is retried next time).
+     * - `options.providers` are appended to the child root module's providers.
+     * - The child's `get()`/`resolve()` look in the child first, then at what
+     *   the declaring module sees in this application, then up this
+     *   application's own parent chain.
+     *
+     * @throws {ContainerNotCompiledError} If this application is not bootstrapped
+     * @throws {ContainerClosedError} If this application is closed or closing
+     * @throws {ChildModuleNotDeclaredError} If no module declares `child`, or
+     *   (`reason: "unloaded"`) the lazy module declaring it was unloaded while
+     *   the child was being created; the child is closed then
+     * @throws {LazyModuleLoadError} If a lazy child's loader fails or returns a non-module
+     *
+     * @example
+     * ```typescript
+     * @Module({ children: [ProfileModule] })
+     * class AppModule {}
+     *
+     * const app = await NexusApplication.create(AppModule).bootstrap();
+     * const profile = await app.createChild(ProfileModule, {
+     *   providers: [{ provide: PROFILE_ID, useValue: "p1" }],
+     * });
+     * ```
+     */
+    createChild(child: Type | DynamicModule | LazyModule, options?: CreateChildOptions): Promise<NexusApplication>;
+    /** Runs a lazy child's loader once per ref; a failure is not cached. */
+    private loadChildModule;
+    private runChildLoader;
+    /**
+     * The link a child declared in `declaredIn` uses: what that module sees
+     * in this application, then this application's own parent chain. It
+     * never caches instances, only which tokens the declaring module sees,
+     * so a `canProvide` followed by `get` walks the imports once per token
+     * (until a load or unload changes the graph) instead of twice per call.
+     * Once this application closes, `canProvide` still answers from the
+     * graph, so `get`/`resolve` of a token the child would have taken from
+     * here throw `ContainerClosedError` (even with `optional`) instead of
+     * quietly reporting it missing.
+     */
+    private linkFor;
+    private requireLink;
     /**
      * Bootstraps the application by initializing the container and all providers.
      *
@@ -63,12 +142,63 @@ export declare class NexusApplications implements NexusApplicationInterface {
      *
      * @example
      * ```typescript
-     * const app = NexusApplications.create(AppModule);
+     * const app = NexusApplication.create(AppModule);
      * await app.bootstrap();
      * // Application is now ready to use
      * ```
      */
-    bootstrap(): Promise<this>;
+    bootstrap(options?: BootstrapOptions): Promise<this>;
+    /**
+     * Pre-instantiates the singleton providers named by `tokens`, unless the
+     * application is running in lazy mode.
+     */
+    private warmUpSingletons;
+    /**
+     * Closes the application and cleans up resources.
+     *
+     * - The closed flag is set synchronously: from this call on, `get`,
+     *   `resolve` and `load` throw `ContainerClosedError`.
+     * - Waits for in-flight lazy loads, then runs on the compile queue so it
+     *   never interleaves with `load`/`unload`.
+     * - Calls every `onModuleDestroy` in reverse creation order, even if some
+     *   throw; failures are collected into a single `AggregateError`.
+     * - Idempotent: later calls return the same promise.
+     * - A child application removes itself from its parent's live children
+     *   once closed.
+     *
+     * @returns A promise that resolves when the application is closed
+     * @throws {AggregateError} If one or more `onModuleDestroy` hooks failed
+     *
+     * @example
+     * ```typescript
+     * const app = await NexusApplication.create(AppModule).bootstrap();
+     * await app.close();
+     * ```
+     */
+    close(): Promise<void>;
+    /**
+     * Closes the live children (newest first, one at a time), then this
+     * application. Every failure, a child's or its own, ends up in one
+     * `AggregateError`, flattened so a child's `AggregateError` contributes
+     * its errors rather than nesting.
+     */
+    private closeChildrenThenSelf;
+    /**
+     * Waits for in-flight `load()` calls (including their singleton warm-up,
+     * which bypasses the closed guard) so nothing is instantiated after the
+     * destroy pass, then tears the container down.
+     */
+    private drainAndClose;
+    /**
+     * Unload hook (see `Container.onUnloading`): closes the live children
+     * declared by a module the unload destroys, newest first, and forgets
+     * the lazy child code those modules declared.
+     */
+    private closeChildrenDeclaredIn;
+    /** True once `close()` has been called (the app may still be closing). */
+    get isClosed(): boolean;
+    private assertOpen;
+    private assertUsable;
     /**
      * Adds one or more scanner plugins to the application.
      *
@@ -81,7 +211,7 @@ export declare class NexusApplications implements NexusApplicationInterface {
      *
      * @example
      * ```typescript
-     * const app = NexusApplications.create(AppModule)
+     * const app = NexusApplication.create(AppModule)
      *   .addScannerPlugin(new CustomScanner())
      *   .addScannerPlugin([new Scanner1(), new Scanner2()]);
      * await app.bootstrap();
@@ -89,72 +219,106 @@ export declare class NexusApplications implements NexusApplicationInterface {
      */
     addScannerPlugin(scanner: ScannerPluginInterface | ScannerPluginInterface[]): this;
     /**
-     * Resolves and returns an instance of a provider by its injection token.
+     * Synchronously returns an already-created singleton provider.
      *
-     * If the provider is not found in this container, it will attempt to
-     * resolve it from the parent container (if set).
+     * If the token is not a provider of this application and this is a child
+     * (see `createChild()`), the parent chain is asked. A token found locally
+     * is always answered locally, never by the parent.
      *
-     * @template T - The type of the provider to resolve
-     * @param token - The injection token (class, string, or symbol)
-     * @returns A promise that resolves to the provider instance, or undefined if not found
+     * @template T - The type of the provider
+     * @param token - The provider token: class, InjectionToken, string or symbol
+     * @param options - `optional: true` returns undefined instead of throwing when no provider exists
+     * @throws {ContainerNotCompiledError} If called before bootstrap()
+     * @throws {ProviderNotFoundError} If no provider has this token (unless optional)
+     * @throws {ProviderScopeError} If the provider is Transient; use resolve()
+     * @throws {ProviderNotInstantiatedError} If the singleton is not created yet (lazy mode); use resolve()
      *
      * @example
      * ```typescript
-     * const app = await NexusApplications.create(AppModule).bootstrap();
-     * const userService = await app.get(UserService);
-     * const config = await app.get('CONFIG');
+     * const app = await NexusApplication.create(AppModule).bootstrap();
+     * const userService = app.get(UserService);
+     * const config = app.get('CONFIG', { optional: true });
      * ```
      */
-    get<T>(token: InjectionToken): Promise<T | undefined>;
+    get<T>(token: ProviderToken<T>): T;
+    get<T>(token: ProviderToken<T>, options: {
+        optional: true;
+    }): T | undefined;
+    get<T>(token: ProviderToken<T>, options: {
+        optional?: false;
+    }): T;
+    get<T>(token: ProviderToken<T>, options: GetOptions): T | undefined;
     /**
-     * Gets all errors that occurred during graph compilation.
+     * Resolves a provider asynchronously, creating it according to its scope
+     * (Transient providers are created per call). A child application falls
+     * back to its parent chain when the token is not a provider of its own.
      *
-     * @returns An array of graph errors
+     * @param token - The provider token: class, InjectionToken, string or symbol
+     * @param options - `optional: true` returns undefined instead of rejecting when no provider exists
+     * @throws {ContainerNotCompiledError} If called before bootstrap()
+     * @throws {ProviderNotFoundError} If no provider has this token (unless optional)
      *
      * @example
      * ```typescript
-     * const app = await NexusApplications.create(AppModule).bootstrap();
-     * if (app.errors.length > 0) {
-     *   console.error('Application errors:', app.errors);
-     * }
+     * const handler = await app.resolve(RequestHandler);
      * ```
      */
-    get errors(): import("@nexus-ioc/shared").GraphError[];
+    resolve<T>(token: ProviderToken<T>): Promise<T>;
+    resolve<T>(token: ProviderToken<T>, options: {
+        optional: true;
+    }): Promise<T | undefined>;
+    resolve<T>(token: ProviderToken<T>, options: {
+        optional?: false;
+    }): Promise<T>;
+    resolve<T>(token: ProviderToken<T>, options: GetOptions): Promise<T | undefined>;
     /**
-     * Enables async mode for the container.
+     * Loads a lazy module declared with `lazy()` into this application's
+     * container and returns a handle to it. Repeated calls for the same ref
+     * return the same providers; the loader runs once.
      *
-     * In async mode, singleton providers are NOT pre-instantiated during
-     * bootstrap. They will be created lazily on first access via get().
-     * This can improve startup time for large applications.
+     * @throws {LazyModuleLoadError} if the loader fails or returns a non-module
+     * @throws {LazyModuleGraphError} if the module's dependency graph is invalid
+     */
+    load(lazyModule: LazyModule): Promise<ModuleRef>;
+    private loadAndWarmUp;
+    /**
+     * Unloads a lazy module previously returned by `load()` (directly or via
+     * `LazyModuleLoader`): destroys every singleton and module nothing else
+     * still needs. A no-op if `ref` is already unloaded.
+     */
+    unload(ref: ModuleRef): Promise<UnloadResult>;
+    /**
+     * Gets all errors that occurred during graph compilation.
      *
-     * @returns This instance for method chaining
+     * @returns An array of graph errors
      *
      * @example
      * ```typescript
-     * const app = NexusApplications.create(AppModule)
-     *   .async();
-     * await app.bootstrap(); // Singletons are NOT created yet
-     * const service = await app.get(MyService); // Created on first access
+     * const app = await NexusApplication.create(AppModule).bootstrap();
+     * if (app.errors.length > 0) {
+     *   console.error('Application errors:', app.errors);
+     * }
      * ```
      */
-    async(): this;
+    get errors(): import("@nexus-ioc/shared").GraphError[];
     /**
-     * Sets a parent container for this application.
+     * Enables lazy mode for the container.
+     *
+     * In lazy mode, singleton providers are NOT pre-instantiated during
+     * bootstrap. They will be created lazily on first access via resolve();
+     * get() throws ProviderNotInstantiatedError until then.
      *
-     * When a provider is not found in this container, it will be looked up
-     * in the parent container. This enables hierarchical container structures.
+     * @deprecated Use lazy modules (lazy()/load()) instead; in this mode get() throws ProviderNotInstantiatedError until resolve() is called.
      *
-     * @param parentContainer - The parent container
      * @returns This instance for method chaining
      *
      * @example
      * ```typescript
-     * const parentApp = await NexusApplications.create(ParentModule).bootstrap();
-     * const childApp = await NexusApplications.create(ChildModule)
-     *   .setParent(parentApp)
-     *   .bootstrap();
-     * // childApp can access providers from parentApp
+     * const app = NexusApplication.create(AppModule)
+     *   .lazy();
+     * await app.bootstrap(); // Singletons are NOT created yet
+     * const service = await app.resolve(MyService); // Created on first access
      * ```
      */
-    setParent(parentContainer: NexusApplicationInterface): this;
+    lazy(): this;
 }

package/dist/types/core/nexus-applications.server.d.ts

@@ -1,21 +1,43 @@
-import type { InjectionToken, Module, NexusApplicationInterface, ScannerPluginInterface } from "../interfaces";
+import type { CreateChildOptions, DynamicModule, GetOptions, LazyModule, NexusApplicationInterface, ProviderToken, ScannerPluginInterface, Type, UnloadResult } from "../interfaces";
+import { ModuleRef } from "./module-ref";
 /**
  * @deprecated
  * It will be removed in version 1.0.0.
- * these classes work the same way. For the new behavior, use @NexusApplications
+ * these classes work the same way. For the new behavior, use @NexusApplication
  */
-export declare class NexusApplicationsServer implements NexusApplicationInterface {
+export declare class NexusApplicationServer implements NexusApplicationInterface {
     private readonly rootModule;
     private readonly hashUtil;
     private readonly container;
     private readonly scannerPlugins;
-    private _parentContainer;
+    private closePromise;
     private constructor();
-    static create(rootModule: Module): NexusApplicationsServer;
+    static create(rootModule: Type): NexusApplicationServer;
     bootstrap(): Promise<this>;
     addScannerPlugin(scanner: ScannerPluginInterface | ScannerPluginInterface[]): this;
-    get<T>(token: InjectionToken): Promise<T | undefined>;
+    get<T>(token: ProviderToken<T>): T;
+    get<T>(token: ProviderToken<T>, options: {
+        optional: true;
+    }): T | undefined;
+    get<T>(token: ProviderToken<T>, options: {
+        optional?: false;
+    }): T;
+    get<T>(token: ProviderToken<T>, options: GetOptions): T | undefined;
+    resolve<T>(token: ProviderToken<T>): Promise<T>;
+    resolve<T>(token: ProviderToken<T>, options: {
+        optional: true;
+    }): Promise<T | undefined>;
+    resolve<T>(token: ProviderToken<T>, options: {
+        optional?: false;
+    }): Promise<T>;
+    resolve<T>(token: ProviderToken<T>, options: GetOptions): Promise<T | undefined>;
     get errors(): import("@nexus-ioc/shared").GraphError[];
-    async(): this;
-    setParent(parentContainer: NexusApplicationInterface): this;
+    load(lazyModule: LazyModule): Promise<ModuleRef>;
+    unload(ref: ModuleRef): Promise<UnloadResult>;
+    lazy(): this;
+    close(): Promise<void>;
+    get isClosed(): boolean;
+    private assertOpen;
+    private assertUsable;
+    createChild(_child: Type | DynamicModule | LazyModule, _options?: CreateChildOptions): Promise<NexusApplicationInterface>;
 }

package/dist/types/core/resolver/providers-container.d.ts

@@ -1,3 +1,3 @@
-import type { InjectionToken } from "../../interfaces";
-export declare class ProvidersContainer extends Map<InjectionToken, any> {
+import type { ProviderToken } from "../../interfaces";
+export declare class ProvidersContainer extends Map<ProviderToken, any> {
 }

package/dist/types/core/resolver/resolution-context.d.ts

@@ -0,0 +1,22 @@
+import type { ProviderToken } from "../../interfaces";
+export declare class ResolutionContext {
+    /** Tokens currently being constructed in this tree, outermost first. */
+    readonly path: ProviderToken[];
+    /** onModuleInit promises started during synchronous creation. */
+    readonly pendingInits: Promise<unknown>[];
+    enter(token: ProviderToken): void;
+    leave(token: ProviderToken): void;
+    isConstructing(token: ProviderToken): boolean;
+    /**
+     * Queues an init promise. A no-op rejection handler is attached right
+     * away so a failure is never reported as an unhandled rejection before
+     * drainPendingInits() collects it; the original promise still rejects.
+     */
+    addPendingInit(promise: Promise<unknown>): void;
+    /**
+     * Waits for every pending init (allSettled semantics), including ones
+     * added while draining, clears the list, then rethrows the first failure
+     * in queue order.
+     */
+    drainPendingInits(): Promise<void>;
+}

package/dist/types/core/resolver/resolver.d.ts

@@ -1,10 +1,128 @@
-import { type InjectionToken, type ModuleGraphInterface } from "../../interfaces";
-import { ProvidersContainer } from "./providers-container";
+import { type ModuleGraphInterface, type ParentLink, type ProviderToken } from "../../interfaces";
+import type { AnalyzeProvider } from "../graph/analyze-provider";
+import { type InjectOptions } from "../injection/injection-context";
+import { ResolutionContext } from "./resolution-context";
 export declare class Resolver {
     private readonly graph;
+    private readonly link;
     private readonly providersContainer;
-    constructor(graph: ModuleGraphInterface);
-    resolveProvider<T>(token: InjectionToken, resolveCache?: ProvidersContainer, isCircularDependency?: boolean): Promise<T | undefined>;
+    private readonly initializationOrder;
+    /** `lateBoundVisible` results, valid while the graph version matches. */
+    private readonly lateBoundMemo;
+    /**
+     * Singletons created by inject() whose onModuleInit (or the wait on
+     * inits queued before them) has not settled yet. Other resolution trees
+     * that hit such a cached singleton wait on this promise, so they never
+     * see it half-initialised or keep it after a failed init evicted it.
+     */
+    private readonly inFlightInits;
+    /**
+     * Singletons that resolveProvider is creating (construction through
+     * onModuleInit), not yet in the cache. Concurrent callers await the same
+     * promise, so each singleton is created once. An entry is removed when
+     * its creation settles: after the commit on success, so a token is always
+     * in the cache or here; on failure, so the next resolve retries.
+     */
+    private readonly inFlightCreations;
+    /**
+     * Set once close() starts. From then on nothing new is created or
+     * cached: creations still in flight are destroyed when they finish
+     * (close() does not wait for them, see commitCreation), and inject()
+     * in a resolution tree that outlived close() throws instead of creating.
+     */
+    private closed;
+    /**
+     * @param link - The parent chain of a child container. Edges marked
+     *   `external` resolve through it; their results are never cached here.
+     */
+    constructor(graph: ModuleGraphInterface, link?: ParentLink | null);
+    /**
+     * The link that satisfies an external edge. The graph marks an edge
+     * external only when a link can provide its target, so a missing link
+     * is an internal error, reported as not found rather than `undefined`.
+     */
+    private linkFor;
+    /** Cached singleton lookup; never creates. Uses has() so falsy values count. */
+    getInstantiated(token: ProviderToken): {
+        found: true;
+        instance: unknown;
+    } | {
+        found: false;
+    };
+    /**
+     * Marks the resolver closed without destroying anything; used when the
+     * container was closed before this resolver existed.
+     */
+    markClosed(): void;
+    close(): Promise<void>;
+    /**
+     * Destroys exactly the given singletons: `onModuleDestroy` in reverse
+     * initialization order, then removed from the cache and from
+     * `initializationOrder`. A token that was never instantiated (never
+     * resolved, or `Transient`/non-singleton scope) is silently skipped.
+     * Like `close()`, every hook runs even if some throw, the cleanup always
+     * completes, and the failures are thrown afterwards as one
+     * `AggregateError`.
+     */
+    destroy(tokens: ProviderToken[]): Promise<void>;
+    resolveProvider<T>(token: ProviderToken, ctx?: ResolutionContext, isCircularDependency?: boolean): Promise<T | undefined>;
+    /**
+     * Caches what `creation` produced, unless the creation went stale while
+     * it ran: close() or destroy() (an unload) dropped its in-flight entry.
+     * A stale instance is never cached. Its onModuleDestroy is called (best
+     * effort: a failure there is ignored, since the caller already gets the
+     * rejection below and nothing else holds the instance), and the caller
+     * gets ContainerClosedError after a close, ProviderUnloadedError after
+     * an unload.
+     */
+    private commitCreation;
+    /**
+     * Caching rules shared by the async and sync paths: Singletons go into the
+     * global cache and the destroy order. Nothing else is cached.
+     */
+    private commitInstance;
+    /** Undoes commitInstance for `instance`, if it is still the cached one. */
+    private evictInstance;
     private createInstance;
+    private createInstanceInContext;
+    /**
+     * inject() entry point: resolves `token` synchronously for `requester`.
+     * The token must be visible from the requester's module, the same rule
+     * as `@Inject`.
+     */
+    resolveSync(token: ProviderToken, ctx: ResolutionContext, requester: AnalyzeProvider, options: InjectOptions): unknown;
+    /**
+     * Synchronous counterpart of resolveProvider for a provider node whose
+     * reachability was already established (visibility check or graph edge).
+     */
+    private resolveProviderSync;
+    /** Resolves a static @Inject edge of `requester` on the synchronous path. */
+    private resolveEdgeSync;
+    /**
+     * Synchronous mirror of createInstance + resolveProvider caching, used
+     * when inject() reaches a provider that does not exist yet.
+     */
+    private createInstanceSync;
+    /** Runs a factory; factories must be synchronous. */
+    private callFactory;
+    /** Registers `init` as the in-flight init of a just-committed singleton. */
+    private trackInFlightInit;
+    /**
+     * Calls onModuleInit synchronously. A synchronous throw is wrapped and
+     * rethrown; an async result is returned with its rejection wrapped.
+     */
+    private callInitSync;
+    private wrapInitError;
+    private contextFor;
+    /**
+     * Whether a late-bound edge's target may be injected into `requester`:
+     * it exists now and is visible from the requester's module. The graph
+     * records the referrer (keeping the target's module alive) under the
+     * same rule, so injection and unload bookkeeping agree.
+     */
+    private lateBoundVisible;
+    private constructorEdges;
+    private propertyEdges;
+    private injectPropertyDependenciesSync;
     private injectPropertyDependencies;
 }

package/dist/types/decorators/inject.d.ts

@@ -1,24 +1,28 @@
 import "reflect-metadata";
-import { type Type } from "../interfaces";
+import { type ProviderToken } from "../interfaces";
+import type { ForwardRef } from "../utils/forward-ref";
 /**
  * Explicitly specifies the injection token for a constructor parameter or property.
  *
  * This decorator is used when:
- * - You need to inject a provider by a string or symbol token
+ * - You need to inject a provider by an InjectionToken, string or symbol token
  * - TypeScript's reflection cannot determine the type (e.g., interfaces, circular dependencies)
  * - You want to inject a different implementation than the declared type
  *
- * @param token - The injection token (class, string, or symbol)
+ * @param token - The provider token: class, InjectionToken, string or symbol, or a `forwardRef()`
  * @returns A decorator that can be applied to constructor parameters or properties
  * @throws {Error} If the token is undefined (often due to circular dependencies)
  *
  * @example
  * ```typescript
+ * // InjectionToken: a typed token for a value that has no class
+ * const DATABASE_CONFIG = new InjectionToken<DatabaseConfig>('DATABASE_CONFIG');
+ *
  * // Constructor parameter injection
  * @Injectable()
  * class UserService {
  *   constructor(
- *     @Inject('DATABASE_CONFIG') private config: DatabaseConfig,
+ *     @Inject(DATABASE_CONFIG) private config: DatabaseConfig,
  *     @Inject(Logger) private logger: Logger
  *   ) {}
  * }
@@ -39,4 +43,4 @@ import { type Type } from "../interfaces";
  * }
  * ```
  */
-export declare function Inject(token: Type | symbol | string): PropertyDecorator & ParameterDecorator;
+export declare function Inject(token: ProviderToken | ForwardRef): PropertyDecorator & ParameterDecorator;

package/dist/types/decorators/injectable.d.ts

@@ -9,7 +9,6 @@ import type { InjectableOptions } from "../interfaces";
  * @param options - Configuration options for the injectable
  * @param options.scope - The lifecycle scope of the provider:
  *   - `Scope.Singleton` (default): One instance shared across the entire application
- *   - `Scope.Request`: New instance for each container.get() call
  *   - `Scope.Transient`: New instance every time, even within the same dependency tree
  * @returns A class decorator
  *
@@ -21,12 +20,6 @@ import type { InjectableOptions } from "../interfaces";
  *   constructor(private db: Database) {}
  * }
  *
- * // Request scope
- * @Injectable({ scope: Scope.Request })
- * class RequestContext {
- *   requestId = Math.random();
- * }
- *
  * // Transient scope
  * @Injectable({ scope: Scope.Transient })
  * class Logger {