ts-ioc-container 72.1.0 → 72.3.0

package/typings/token/BindableToken.d.ts

@@ -0,0 +1,80 @@
+import { type DependencyKey, type IContainer } from '../container/IContainer.js';
+import { InjectionToken } from './InjectionToken.js';
+import { type BindToken } from './BindToken.js';
+import { type IRegistration } from '../registration/IRegistration.js';
+import { type ArgsFn, type ResolveOptions } from '../provider/IProvider.js';
+import { type Serializable } from '../utils/basic.js';
+import { type MultiVariantFeatureToken } from './MultiVariantFeatureToken.js';
+type NoInferVariant<V> = [V][V extends unknown ? 0 : never];
+/** Internal state of a {@link BindableToken}, propagated by its modifiers. Never pass it from outside. */
+export type BindableTokenOptions = {
+    getArgsFn?: ArgsFn;
+    isLazy?: boolean;
+    tags?: string[];
+    memberships?: DependencyKey[];
+};
+/**
+ * Base of every token a registration can be bound to (`SingleToken`,
+ * `SingleAliasToken`, `GroupAliasToken`): a key, the args / lazy / tags state
+ * every modifier copies, and the feature memberships the token declares.
+ *
+ * `T` is the type bound to the token, `R` the type resolving it returns (an
+ * alias group resolves `T[]`). A subclass says only how it binds (`bindKey`)
+ * and how it resolves.
+ */
+export declare abstract class BindableToken<T = any, R = T> extends InjectionToken<R> implements BindToken<T>, Serializable {
+    readonly token: DependencyKey;
+    private readonly getArgsFn;
+    private readonly isLazyByDefault;
+    private readonly memberships;
+    constructor(token: DependencyKey, { getArgsFn, isLazy, tags, memberships }?: BindableTokenOptions);
+    /** Binds `r` under this token, and into every feature this token declared itself a variant or fallback of. */
+    bindTo(r: IRegistration<T>): void;
+    /**
+     * Declares the dependency bound to this token the implementation of `feature`
+     * while the flag serves the variant `name`.
+     *
+     * @example
+     * const BlueButtonToken = new SingleToken<IButton>('BlueButton').variantOf(CheckoutButtonToken, 'blue');
+     *
+     * @register(BlueButtonToken)
+     * class BlueButton implements IButton {}
+     */
+    variantOf<V extends string>(feature: MultiVariantFeatureToken<T, V>, name: NoInferVariant<V>): this;
+    /**
+     * Declares the dependency bound to this token the primary variant of
+     * `feature`: used while the flag is on and no named variant implementation
+     * matches. The enabled implementation of a `ToggleFeatureToken`.
+     *
+     * @example
+     * const StripeGatewayToken = new SingleToken<IPaymentGateway>('StripeGateway').primaryVariantOf(PaymentGatewayToken);
+     *
+     * @register(StripeGatewayToken)
+     * class StripeGateway implements IPaymentGateway {}
+     */
+    primaryVariantOf(feature: MultiVariantFeatureToken<T, string>): this;
+    /**
+     * Declares the dependency bound to this token the fallback of `feature`: used
+     * whenever no variant implementation applies - the flag is off, serves
+     * nothing implemented, or its client throws.
+     *
+     * @example
+     * const LegacyGatewayToken = new SingleToken<IPaymentGateway>('LegacyGateway').fallbackOf(PaymentGatewayToken);
+     *
+     * @register(LegacyGatewayToken)
+     * class LegacyGateway implements IPaymentGateway {}
+     */
+    fallbackOf(feature: MultiVariantFeatureToken<T, string>): this;
+    args(...newArgs: unknown[]): this;
+    argsFn(fn: (s: IContainer) => unknown[]): this;
+    lazy(): this;
+    addTags(...tags: string[]): this;
+    toString(): string;
+    /** Binds `r` under this token's own key or alias. */
+    protected abstract bindKey(r: IRegistration<T>): void;
+    /** The options a subclass resolves with: runtime args first, then this token's args; lazy if either asks. */
+    protected toResolveOptions(s: IContainer, { args, lazy }?: ResolveOptions): ResolveOptions;
+    private copy;
+}
+export {};
+//# sourceMappingURL=BindableToken.d.ts.map

package/typings/token/BindableToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BindableToken.d.ts","sourceRoot":"","sources":["../../lib/token/BindableToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAe,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACnD,OAAO,EAAE,KAAK,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAG3E,KAAK,cAAc,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC;AAE5D,0GAA0G;AAC1G,MAAM,MAAM,oBAAoB,GAAG;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;IAChB,WAAW,CAAC,EAAE,aAAa,EAAE,CAAC;CAC/B,CAAC;AAEF;;;;;;;;GAQG;AACH,8BAAsB,aAAa,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,GAAG,CAAC,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAE,YAAW,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY;IAM/G,QAAQ,CAAC,KAAK,EAAE,aAAa;IAL/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAkB;gBAGnC,KAAK,EAAE,aAAa,EAC7B,EAAE,SAAuB,EAAE,MAAc,EAAE,IAAS,EAAE,WAAgB,EAAE,GAAE,oBAAyB;IAQrG,8GAA8G;IAC9G,MAAM,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI;IAOjC;;;;;;;;;OASG;IACH,SAAS,CAAC,CAAC,SAAS,MAAM,EAAE,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,GAAG,IAAI;IAInG;;;;;;;;;;OAUG;IACH,gBAAgB,CAAC,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI;IAIpE;;;;;;;;;;OAUG;IACH,UAAU,CAAC,OAAO,EAAE,wBAAwB,CAAC,CAAC,EAAE,MAAM,CAAC,GAAG,IAAI;IAI9D,IAAI,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI;IAKjC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO,EAAE,GAAG,IAAI;IAK9C,IAAI,IAAI,IAAI;IAIZ,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAIhC,QAAQ,IAAI,MAAM;IAIlB,qDAAqD;IACrD,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC,GAAG,IAAI;IAErD,6GAA6G;IAC7G,SAAS,CAAC,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,IAAS,EAAE,IAAI,EAAE,GAAE,cAAmB,GAAG,cAAc;IAKnG,OAAO,CAAC,IAAI;CAUb"}

package/typings/token/ClassToken.d.ts

@@ -2,6 +2,7 @@ import { IContainer } from '../container/IContainer.js';
 import { InjectionToken } from './InjectionToken.js';
 import { type constructor, Serializable } from '../utils/basic.js';
 import { ArgsFn, ResolveOptions } from '../provider/IProvider.js';
+/** A token for a class: resolves it through the scope's injector. `toToken(Class)` creates one. */
 export declare class ClassToken<T = any> extends InjectionToken<T> implements Serializable {
     private readonly target;
     private readonly _getArgsFn;
@@ -19,3 +20,4 @@ export declare class ClassToken<T = any> extends InjectionToken<T> implements Se
     addTags(...tags: string[]): ClassToken<T>;
     toString(): string;
 }
+//# sourceMappingURL=ClassToken.d.ts.map

package/typings/token/ClassToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ClassToken.d.ts","sourceRoot":"","sources":["../../lib/token/ClassToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AACrD,OAAO,EAAe,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,KAAK,WAAW,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAChE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE/D,mGAAmG;AACnG,qBAAa,UAAU,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAE,YAAW,YAAY;IAK9E,OAAO,CAAC,QAAQ,CAAC,MAAM;IAJzB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAGf,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,EACvC,EACE,SAAuB,EACvB,MAAc,EACd,IAAS,GACV,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO;IAOnE,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,IACpB,GAAG,UAAU;IAGvB,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,IAAS,EAAE,IAAI,EAAE,GAAE,cAAmB,GAAG,CAAC;IAOnE,IAAI,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE;IAS1B,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO,EAAE;IASvC,IAAI;IAQJ,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,CAAC,CAAC;IAQzC,QAAQ,IAAI,MAAM;CAGnB"}

package/typings/token/ConstantToken.d.ts

@@ -1,15 +1,29 @@
 import type { IContainer } from '../container/IContainer.js';
 import { InjectionToken } from './InjectionToken.js';
 import { Serializable } from '../utils/basic.js';
+/** A token that always resolves to a fixed value. It takes no args and cannot be lazy. */
 export declare class ConstantToken<T = any> extends InjectionToken<T> implements Serializable {
     private readonly token;
     constructor(token: T, { tags }?: {
         tags?: string[];
     });
     resolve(s: IContainer): T;
+    /**
+     * @throws {MethodNotImplementedError} always — a constant token cannot receive static args.
+     */
     args(...deps: unknown[]): InjectionToken<T>;
+    /**
+     * @throws {MethodNotImplementedError} always — a constant token cannot receive resolved args.
+     */
     argsFn(getArgsFn: (s: IContainer) => unknown[]): InjectionToken<T>;
+    /**
+     * @throws {MethodNotImplementedError} always — a constant token cannot be made lazy.
+     */
     lazy(): InjectionToken<T>;
     addTags(...tags: string[]): ConstantToken<T>;
+    /**
+     * @throws {MethodNotImplementedError} always — a constant token has no underlying key.
+     */
     toString(): string;
 }
+//# sourceMappingURL=ConstantToken.d.ts.map

package/typings/token/ConstantToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ConstantToken.d.ts","sourceRoot":"","sources":["../../lib/token/ConstantToken.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAElD,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C,0FAA0F;AAC1F,qBAAa,aAAa,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAE,YAAW,YAAY;IAEjF,OAAO,CAAC,QAAQ,CAAC,KAAK;gBAAL,KAAK,EAAE,CAAC,EACzB,EAAE,IAAS,EAAE,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO;IAKzC,OAAO,CAAC,CAAC,EAAE,UAAU,GAAG,CAAC;IAIzB;;OAEG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC;IAI3C;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC;IAIlE;;OAEG;IACH,IAAI,IAAI,cAAc,CAAC,CAAC,CAAC;IAIzB,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC;IAI5C;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/typings/token/FunctionToken.d.ts

@@ -3,6 +3,12 @@ import { InjectionToken } from './InjectionToken.js';
 import { InjectFn } from '../hooks/hook.js';
 import { ArgsFn, ResolveOptions } from '../provider/IProvider.js';
 import { Serializable } from '../utils/basic.js';
+/**
+ * A token that resolves by calling an `InjectFn` with the resolution context.
+ *
+ * @example
+ * const CurrentScope = new FunctionToken(({ scope }) => scope);
+ */
 export declare class FunctionToken<T = any> extends InjectionToken<T> implements Serializable {
     private readonly fn;
     private readonly _getArgsFn;
@@ -17,5 +23,9 @@ export declare class FunctionToken<T = any> extends InjectionToken<T> implements
     argsFn(fn: (s: IContainer) => unknown[]): InjectionToken<T>;
     lazy(): InjectionToken<T>;
     addTags(...tags: string[]): FunctionToken<T>;
+    /**
+     * @throws {MethodNotImplementedError} always — a function token has no underlying key.
+     */
     toString(): string;
 }
+//# sourceMappingURL=FunctionToken.d.ts.map

package/typings/token/FunctionToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FunctionToken.d.ts","sourceRoot":"","sources":["../../lib/token/FunctionToken.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAe,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE/D,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE9C;;;;;GAKG;AACH,qBAAa,aAAa,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,cAAc,CAAC,CAAC,CAAE,YAAW,YAAY;IAKjF,OAAO,CAAC,QAAQ,CAAC,EAAE;IAJrB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAGf,EAAE,EAAE,QAAQ,CAAC,CAAC,CAAC,EAChC,EACE,SAAuB,EACvB,MAAc,EACd,IAAS,GACV,GAAE;QAAE,SAAS,CAAC,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;KAAO;IAOnE,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,IAAS,EAAE,IAAI,EAAE,GAAE,cAAmB,GAAG,CAAC;IAQnE,IAAI,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC;IAS9C,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC;IAS3D,IAAI,IAAI,cAAc,CAAC,CAAC,CAAC;IAQzB,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,aAAa,CAAC,CAAC,CAAC;IAQ5C;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/typings/token/GroupAliasToken.d.ts

@@ -1,25 +1,24 @@
-import { DependencyKey, IContainer } from '../container/IContainer.js';
-import { InjectionToken } from './InjectionToken.js';
-import { IRegistration } from '../registration/IRegistration.js';
-import { BindToken } from './BindToken.js';
-import { ArgsFn, ResolveOptions } from '../provider/IProvider.js';
-import { Serializable } from '../utils/basic.js';
-export declare class GroupAliasToken<T = any> extends InjectionToken<T[]> implements BindToken<T>, Serializable {
-    readonly token: DependencyKey;
-    private readonly _getArgsFn;
-    private readonly _isLazy;
-    constructor(token: DependencyKey, { getArgsFn, isLazy, tags, }?: {
-        getArgsFn?: ArgsFn;
-        isLazy?: boolean;
-        tags?: string[];
-    });
+import { type DependencyKey, type IContainer } from '../container/IContainer.js';
+import { BindableToken } from './BindableToken.js';
+import { type IRegistration } from '../registration/IRegistration.js';
+import { type ResolveOptions } from '../provider/IProvider.js';
+/**
+ * A token for every dependency registered under an alias. As a `@register(...)`
+ * target it adds the alias; resolving returns all matches as an array.
+ *
+ * @example
+ * const IMiddlewareToken = toGroupAlias<IMiddleware>('IMiddleware');
+ *
+ * @register(IMiddlewareToken)
+ * class Auth implements IMiddleware {}
+ *
+ * IMiddlewareToken.resolve(scope); // IMiddleware[]
+ */
+export declare class GroupAliasToken<T = any> extends BindableToken<T, T[]> {
     select<R>(fn: (target: T[]) => R[]): (s: IContainer) => R[];
-    resolve(s: IContainer, { args, lazy }?: ResolveOptions): T[];
-    bindTo(r: IRegistration<T>): void;
-    args(...newArgs: unknown[]): GroupAliasToken<T>;
-    argsFn(fn: (s: IContainer) => unknown[]): GroupAliasToken<T>;
-    lazy(): GroupAliasToken<T>;
-    addTags(...tags: string[]): GroupAliasToken<T>;
-    toString(): string;
+    resolve(s: IContainer, options?: ResolveOptions): T[];
+    protected bindKey(r: IRegistration<T>): void;
 }
+/** Creates a {@link GroupAliasToken} for `token`. */
 export declare const toGroupAlias: <T>(token: DependencyKey) => GroupAliasToken<T>;
+//# sourceMappingURL=GroupAliasToken.d.ts.map

package/typings/token/GroupAliasToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroupAliasToken.d.ts","sourceRoot":"","sources":["../../lib/token/GroupAliasToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,qBAAa,eAAe,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,aAAa,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IACjE,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,IACxB,GAAG,UAAU;IAGvB,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,CAAC,EAAE;IAIrD,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC;CAGtC;AAED,qDAAqD;AACrD,eAAO,MAAM,YAAY,GAAI,CAAC,EAAE,OAAO,aAAa,uBAAkC,CAAC"}

package/typings/token/GroupInstanceToken.d.ts

@@ -1,7 +1,12 @@
 import { InjectionToken } from './InjectionToken.js';
 import type { IContainer } from '../container/IContainer.js';
 import { Instance, Serializable } from '../utils/basic.js';
+/** Selects instances for a {@link GroupInstanceToken}. */
 export type InstancePredicate = (dep: unknown) => boolean;
+/**
+ * Resolves the instances already created in a scope (and, by default, its
+ * child scopes) that match a predicate. Created by `select.instances(...)`.
+ */
 export declare class GroupInstanceToken extends InjectionToken<Instance[]> implements Serializable {
     private predicate;
     private isCascade;
@@ -10,11 +15,25 @@ export declare class GroupInstanceToken extends InjectionToken<Instance[]> imple
         isCascade?: boolean;
     });
     select<R>(fn: (target: Instance) => R): (s: IContainer) => R[];
+    /**
+     * @throws {MethodNotImplementedError} always — a group instance token cannot receive static args.
+     */
     args(...deps: unknown[]): this;
+    /**
+     * @throws {MethodNotImplementedError} always — a group instance token cannot receive resolved args.
+     */
     argsFn(getArgsFn: (s: IContainer) => unknown[]): InjectionToken<Instance[]>;
+    /**
+     * @throws {MethodNotImplementedError} always — a group instance token cannot be made lazy.
+     */
     lazy(): InjectionToken<Instance[]>;
+    /** Whether instances of child scopes are included (default `true`). */
     cascade(isTrue: boolean): this;
     resolve(c: IContainer): Instance[];
     addTags(...tags: string[]): GroupInstanceToken;
+    /**
+     * @throws {MethodNotImplementedError} always — a group instance token has no underlying key.
+     */
     toString(): string;
 }
+//# sourceMappingURL=GroupInstanceToken.d.ts.map

package/typings/token/GroupInstanceToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GroupInstanceToken.d.ts","sourceRoot":"","sources":["../../lib/token/GroupInstanceToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG1D,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAExD,0DAA0D;AAC1D,MAAM,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAC;AAE1D;;;GAGG;AACH,qBAAa,kBAAmB,SAAQ,cAAc,CAAC,QAAQ,EAAE,CAAE,YAAW,YAAY;IAItF,OAAO,CAAC,SAAS;IAHnB,OAAO,CAAC,SAAS,CAAU;gBAGjB,SAAS,EAAE,iBAAiB,EACpC,EAAE,IAAS,EAAE,SAAgB,EAAE,GAAE;QAAE,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO;IAMhF,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,QAAQ,KAAK,CAAC,IAC3B,GAAG,UAAU;IAGvB;;OAEG;IACH,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,IAAI;IAI9B;;OAEG;IACH,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO,EAAE,GAAG,cAAc,CAAC,QAAQ,EAAE,CAAC;IAI3E;;OAEG;IACH,IAAI,IAAI,cAAc,CAAC,QAAQ,EAAE,CAAC;IAIlC,uEAAuE;IACvE,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;IAK9B,OAAO,CAAC,CAAC,EAAE,UAAU,GAAG,QAAQ,EAAE;IAIlC,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,kBAAkB;IAI9C;;OAEG;IACH,QAAQ,IAAI,MAAM;CAGnB"}

package/typings/token/InjectionToken.d.ts

@@ -1,6 +1,12 @@
 import { type IContainer, type Tag } from '../container/IContainer.js';
 import { ArgsFn, ResolveOptions } from '../provider/IProvider.js';
+/**
+ * The default `getArgsFn` of every token: the runtime `args` a token is
+ * resolved with reach the provider as they are, and `token.args(...)` /
+ * `token.argsFn(...)` append after them.
+ */
 export declare const forwardArgs: ArgsFn;
+/** Base class of every token: something resolvable from a scope that can be specialized with args, lazy and tags. */
 export declare abstract class InjectionToken<T = any> {
     private readonly tags;
     protected constructor(tags?: Tag[]);
@@ -12,4 +18,6 @@ export declare abstract class InjectionToken<T = any> {
     hasTag(tag: Tag): boolean;
     protected getTags(): Tag[];
 }
+/** Narrows `target` to an {@link InjectionToken}. */
 export declare function isInjectionToken<T = any>(target: unknown): target is InjectionToken<T>;
+//# sourceMappingURL=InjectionToken.d.ts.map

package/typings/token/InjectionToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InjectionToken.d.ts","sourceRoot":"","sources":["../../lib/token/InjectionToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,KAAK,GAAG,EAAE,MAAM,yBAAyB,CAAC;AACpE,OAAO,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAG/D;;;;GAIG;AACH,eAAO,MAAM,WAAW,EAAE,MAAgC,CAAC;AAE3D,qHAAqH;AACrH,8BAAsB,cAAc,CAAC,CAAC,GAAG,GAAG;IAC1C,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAW;IAEhC,SAAS,aAAa,IAAI,GAAE,GAAG,EAAO;IAItC,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,CAAC;IAC5D,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC;IACpD,QAAQ,CAAC,MAAM,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC;IAC3E,QAAQ,CAAC,IAAI,IAAI,cAAc,CAAC,CAAC,CAAC;IAClC,QAAQ,CAAC,OAAO,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,GAAG,cAAc,CAAC,CAAC,CAAC;IAEnD,MAAM,CAAC,GAAG,EAAE,GAAG,GAAG,OAAO;IAIzB,SAAS,CAAC,OAAO,IAAI,GAAG,EAAE;CAG3B;AAED,qDAAqD;AACrD,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,GAAG,EAAE,MAAM,EAAE,OAAO,GAAG,MAAM,IAAI,cAAc,CAAC,CAAC,CAAC,CAUtF"}

package/typings/token/MultiVariantFeatureToken.d.ts

@@ -0,0 +1,79 @@
+import { type DependencyKey, type IContainer } from '../container/IContainer.js';
+import { InjectionToken } from './InjectionToken.js';
+import { type ArgsFn, type ResolveOptions } from '../provider/IProvider.js';
+import { type Serializable } from '../utils/basic.js';
+import { type FeatureContext, type IFeatureFlags } from '../feature/IFeatureFlags.js';
+export type FeatureTokenOptions = {
+    getArgsFn?: ArgsFn;
+    isLazy?: boolean;
+    tags?: string[];
+};
+/** What a feature token reads from its flag: whether it is on, and the named variant served, if any. */
+export type FeatureEvaluation<V extends string = string> = {
+    enabled: boolean;
+    variant?: V;
+};
+/**
+ * A dependency switched by a multi-variant feature flag. The implementations
+ * decide where they belong - a bindable token declares itself
+ *
+ * - a named variant with `variantOf(feature, name)`: used while the flag serves `name`;
+ * - the primary variant with `primaryVariantOf(feature)`: used while the flag is
+ *   on and no named variant implementation matches;
+ * - the fallback with `fallbackOf(feature)`: used otherwise - the flag is off,
+ *   or its client throws.
+ *
+ * A flag always has a fallback: resolving a feature without one registered fails.
+ *
+ * `flag` is the flag's name on the flag service. `V` narrows the variant names
+ * implementations may claim. The flag client comes from `IFeatureFlagsToken`
+ * and the context from `IFeatureContextToken`, both resolved from the resolving
+ * scope, on every resolution.
+ *
+ * Subclasses change only how the served variant is evaluated - see
+ * `ToggleFeatureToken`, the on/off case.
+ *
+ * @example
+ * const CheckoutButtonToken = new MultiVariantFeatureToken<IButton, 'blue' | 'green'>('checkout-button');
+ *
+ * @register(new SingleToken<IButton>('GreyButton').fallbackOf(CheckoutButtonToken))
+ * class GreyButton implements IButton {}
+ *
+ * @register(new SingleToken<IButton>('BlueButton').variantOf(CheckoutButtonToken, 'blue'))
+ * class BlueButton implements IButton {}
+ *
+ * @register(new SingleToken<IButton>('GreenButton').primaryVariantOf(CheckoutButtonToken))
+ * class GreenButton implements IButton {}
+ */
+export declare class MultiVariantFeatureToken<T = any, V extends string = string> extends InjectionToken<T> implements Serializable {
+    readonly flag: string;
+    private readonly _getArgsFn;
+    private readonly _isLazy;
+    constructor(flag: string, { getArgsFn, isLazy, tags }?: FeatureTokenOptions);
+    /** The alias an implementation of the variant `name` is bound to. Declare it with `token.variantOf(feature, name)`. */
+    variantAlias(name: V): DependencyKey;
+    /** The alias the primary variant is bound to. Declare it with `token.primaryVariantOf(feature)`. */
+    primaryAlias(): DependencyKey;
+    /** The alias the fallback is bound to. Declare it with `token.fallbackOf(feature)`. */
+    fallbackAlias(): DependencyKey;
+    /**
+     * @throws {DependencyNotFoundError} when the flag has no fallback, or the flag client, the feature context or the selected implementation cannot be resolved.
+     * @throws {ContainerDisposedError} when `s` has already been disposed.
+     */
+    resolve(s: IContainer, { args, lazy }?: ResolveOptions): T;
+    args(...newArgs: unknown[]): this;
+    argsFn(fn: (s: IContainer) => unknown[]): this;
+    lazy(): this;
+    addTags(...tags: string[]): this;
+    toString(): string;
+    /** Whether the flag is on for `context`, and the named variant it serves, if any. */
+    protected evaluate(flags: IFeatureFlags, context: FeatureContext): FeatureEvaluation<V>;
+    private copy;
+    /**
+     * The alias of the served variant's implementation, or of the fallback.
+     *
+     * @throws {DependencyNotFoundError} when the flag has no fallback, or the flag client or the feature context cannot be resolved.
+     */
+    private selectAlias;
+}
+//# sourceMappingURL=MultiVariantFeatureToken.d.ts.map

package/typings/token/MultiVariantFeatureToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"MultiVariantFeatureToken.d.ts","sourceRoot":"","sources":["../../lib/token/MultiVariantFeatureToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAe,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC/D,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACzE,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAGnB,MAAM,0BAA0B,CAAC;AAElC,MAAM,MAAM,mBAAmB,GAAG;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC;AAE5F,wGAAwG;AACxG,MAAM,MAAM,iBAAiB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,IAAI;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC,CAAA;CAAE,CAAC;AAE7F;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,qBAAa,wBAAwB,CAAC,CAAC,GAAG,GAAG,EAAE,CAAC,SAAS,MAAM,GAAG,MAAM,CACtE,SAAQ,cAAc,CAAC,CAAC,CACxB,YAAW,YAAY;IAMrB,QAAQ,CAAC,IAAI,EAAE,MAAM;IAJvB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBAGvB,IAAI,EAAE,MAAM,EACrB,EAAE,SAAuB,EAAE,MAAc,EAAE,IAAS,EAAE,GAAE,mBAAwB;IAOlF,uHAAuH;IACvH,YAAY,CAAC,IAAI,EAAE,CAAC,GAAG,aAAa;IAIpC,oGAAoG;IACpG,YAAY,IAAI,aAAa;IAI7B,uFAAuF;IACvF,aAAa,IAAI,aAAa;IAI9B;;;OAGG;IACH,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,IAAS,EAAE,IAAI,EAAE,GAAE,cAAmB,GAAG,CAAC;IAMnE,IAAI,CAAC,GAAG,OAAO,EAAE,OAAO,EAAE,GAAG,IAAI;IAKjC,MAAM,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,UAAU,KAAK,OAAO,EAAE,GAAG,IAAI;IAK9C,IAAI,IAAI,IAAI;IAIZ,OAAO,CAAC,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI;IAIhC,QAAQ,IAAI,MAAM;IAIlB,qFAAqF;IACrF,SAAS,CAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,GAAG,iBAAiB,CAAC,CAAC,CAAC;IAOvF,OAAO,CAAC,IAAI;IAUZ;;;;OAIG;IACH,OAAO,CAAC,WAAW;CAuBpB"}

package/typings/token/SingleAliasToken.d.ts

@@ -1,25 +1,19 @@
-import { DependencyKey, IContainer } from '../container/IContainer.js';
-import { InjectionToken } from './InjectionToken.js';
-import { IRegistration } from '../registration/IRegistration.js';
-import { BindToken } from './BindToken.js';
-import { ArgsFn, ResolveOptions } from '../provider/IProvider.js';
-import { Serializable } from '../utils/basic.js';
-export declare class SingleAliasToken<T = any> extends InjectionToken<T> implements BindToken<T>, Serializable {
-    readonly token: DependencyKey;
-    private readonly _getArgsFn;
-    private readonly _isLazy;
-    constructor(token: DependencyKey, { getArgsFn, isLazy, tags, }?: {
-        getArgsFn?: ArgsFn;
-        isLazy?: boolean;
-        tags?: string[];
-    });
+import { type DependencyKey, type IContainer } from '../container/IContainer.js';
+import { BindableToken } from './BindableToken.js';
+import { type IRegistration } from '../registration/IRegistration.js';
+import { type ResolveOptions } from '../provider/IProvider.js';
+/**
+ * Like {@link GroupAliasToken}, but resolves exactly one dependency registered
+ * under the alias, and throws `DependencyNotFoundError` when there is none.
+ */
+export declare class SingleAliasToken<T = any> extends BindableToken<T> {
     select<R>(fn: (target: T) => R): (s: IContainer) => R;
-    resolve(s: IContainer, { args, lazy }?: ResolveOptions): T;
-    bindTo(r: IRegistration<T>): void;
-    args(...newArgs: unknown[]): SingleAliasToken<T>;
-    argsFn(fn: (s: IContainer) => unknown[]): SingleAliasToken<T>;
-    lazy(): SingleAliasToken<T>;
-    addTags(...tags: string[]): SingleAliasToken<T>;
-    toString(): string;
+    /**
+     * @throws {DependencyNotFoundError} when no accessible registration carries the alias.
+     */
+    resolve(s: IContainer, options?: ResolveOptions): T;
+    protected bindKey(r: IRegistration<T>): void;
 }
+/** Creates a {@link SingleAliasToken} for `token`. */
 export declare const toSingleAlias: <T>(token: DependencyKey) => SingleAliasToken<T>;
+//# sourceMappingURL=SingleAliasToken.d.ts.map

package/typings/token/SingleAliasToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SingleAliasToken.d.ts","sourceRoot":"","sources":["../../lib/token/SingleAliasToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAE,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC9E,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;GAGG;AACH,qBAAa,gBAAgB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;IAC7D,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,IACpB,GAAG,UAAU;IAGvB;;OAEG;IACH,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,CAAC;IAInD,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC;CAGtC;AAED,sDAAsD;AACtD,eAAO,MAAM,aAAa,GAAI,CAAC,EAAE,OAAO,aAAa,wBAAmC,CAAC"}

package/typings/token/SingleToken.d.ts

@@ -1,23 +1,27 @@
-import { DependencyKey, IContainer } from '../container/IContainer.js';
-import { InjectionToken } from './InjectionToken.js';
-import { IRegistration } from '../registration/IRegistration.js';
-import { ArgsFn, ResolveOptions } from '../provider/IProvider.js';
-import { Serializable } from '../utils/basic.js';
-export declare class SingleToken<T = any> extends InjectionToken<T> implements Serializable {
-    token: DependencyKey;
-    private readonly _getArgsFn;
-    private readonly _isLazy;
-    constructor(token: DependencyKey, { getArgsFn, isLazy, tags, }?: {
-        getArgsFn?: ArgsFn;
-        isLazy?: boolean;
-        tags?: string[];
-    });
+import { type IContainer } from '../container/IContainer.js';
+import { BindableToken } from './BindableToken.js';
+import { type IRegistration } from '../registration/IRegistration.js';
+import { type ResolveOptions } from '../provider/IProvider.js';
+/**
+ * A typed handle for one dependency key - the usual way to name a dependency.
+ * `args(...)`, `argsFn(...)` and `lazy()` return a new token and never change
+ * this one, so one token can be specialized per injection site.
+ *
+ * @example
+ * const ILoggerToken = new SingleToken<ILogger>('ILogger');
+ *
+ * @register(ILoggerToken)
+ * class Logger implements ILogger {}
+ *
+ * class App {
+ *   constructor(@inject(by(ILoggerToken)) logger: ILogger) {}
+ * }
+ * ILoggerToken.resolve(scope);
+ * ILoggerToken.args('prefix').lazy().resolve(scope);
+ */
+export declare class SingleToken<T = any> extends BindableToken<T> {
     select<R>(fn: (target: T) => R): (s: IContainer) => R;
-    resolve(s: IContainer, { args, lazy }?: ResolveOptions): T;
-    bindTo(r: IRegistration<T>): void;
-    args(...newArgs: unknown[]): SingleToken<T>;
-    argsFn(fn: (s: IContainer) => unknown[]): SingleToken<T>;
-    lazy(): SingleToken<T>;
-    addTags(...tags: string[]): SingleToken<T>;
-    toString(): string;
+    resolve(s: IContainer, options?: ResolveOptions): T;
+    protected bindKey(r: IRegistration<T>): void;
 }
+//# sourceMappingURL=SingleToken.d.ts.map

package/typings/token/SingleToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SingleToken.d.ts","sourceRoot":"","sources":["../../lib/token/SingleToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,KAAK,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,KAAK,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAE5D;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,WAAW,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;IACxD,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,IACpB,GAAG,UAAU;IAGvB,OAAO,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,cAAc,GAAG,CAAC;IAInD,SAAS,CAAC,OAAO,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC,CAAC;CAGtC"}

package/typings/token/ToggleFeatureToken.d.ts

@@ -0,0 +1,25 @@
+import { type FeatureEvaluation, MultiVariantFeatureToken } from './MultiVariantFeatureToken.js';
+import { type FeatureContext, type IFeatureFlags } from '../feature/IFeatureFlags.js';
+/**
+ * The on/off case of {@link MultiVariantFeatureToken}: a flag with no named
+ * variants, only a primary one, served while `isEnabled` says so. Everything
+ * else - the fallback, the context, args and laziness - is the multi-variant
+ * token's.
+ *
+ * @example
+ * const PaymentGatewayToken = new ToggleFeatureToken<IPaymentGateway>('new-checkout');
+ *
+ * @register(new SingleToken<IPaymentGateway>('LegacyGateway').fallbackOf(PaymentGatewayToken))
+ * class LegacyGateway implements IPaymentGateway {}
+ *
+ * @register(new SingleToken<IPaymentGateway>('StripeGateway').primaryVariantOf(PaymentGatewayToken))
+ * class StripeGateway implements IPaymentGateway {}
+ *
+ * class Checkout {
+ *   constructor(@inject(by(PaymentGatewayToken)) gateway: IPaymentGateway) {}
+ * }
+ */
+export declare class ToggleFeatureToken<T = any> extends MultiVariantFeatureToken<T, never> {
+    protected evaluate(flags: IFeatureFlags, context: FeatureContext): FeatureEvaluation<never>;
+}
+//# sourceMappingURL=ToggleFeatureToken.d.ts.map

package/typings/token/ToggleFeatureToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ToggleFeatureToken.d.ts","sourceRoot":"","sources":["../../lib/token/ToggleFeatureToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,iBAAiB,EAAE,wBAAwB,EAAE,MAAM,4BAA4B,CAAC;AAC9F,OAAO,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,0BAA0B,CAAC;AAEnF;;;;;;;;;;;;;;;;;;GAkBG;AACH,qBAAa,kBAAkB,CAAC,CAAC,GAAG,GAAG,CAAE,SAAQ,wBAAwB,CAAC,CAAC,EAAE,KAAK,CAAC;cAC9D,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,GAAG,iBAAiB,CAAC,KAAK,CAAC;CAGrG"}

package/typings/token/toToken.d.ts

@@ -2,6 +2,18 @@ import { DependencyKey } from '../container/IContainer.js';
 import { InjectionToken } from './InjectionToken.js';
 import { InjectFn } from '../hooks/hook.js';
 import { type constructor } from '../utils/basic.js';
+/** Anything `toToken(...)` turns into a token: a token, a key, a class or an `InjectFn`. */
 export type Injectable<T = any> = InjectFn<T> | InjectionToken<T> | DependencyKey | constructor<T>;
+/**
+ * @throws {UnsupportedTokenTypeError} when `token` is not an `InjectionToken`, a `DependencyKey`, a constructor, or a function.
+ */
 export declare const toToken: <T = any>(token: Injectable<T>) => InjectionToken<T>;
+/**
+ * Wraps a runtime argument so it can be resolved uniformly: an `InjectionToken`
+ * is returned as-is, anything else becomes a `ConstantToken` of itself. The
+ * library never applies it to the args list - a call site that wants
+ * "resolve tokens, pass literals through" does so explicitly, e.g.
+ * `@inject(({ scope, args = [] }) => argToToken(args[0]).resolve(scope))`.
+ */
 export declare const argToToken: <T = unknown>(v: T) => InjectionToken<T>;
+//# sourceMappingURL=toToken.d.ts.map

package/typings/token/toToken.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toToken.d.ts","sourceRoot":"","sources":["../../lib/token/toToken.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAmB,MAAM,yBAAyB,CAAC;AAKzE,OAAO,EAAE,cAAc,EAAoB,MAAM,kBAAkB,CAAC;AACpE,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,KAAK,WAAW,EAAM,MAAM,gBAAgB,CAAC;AAGtD,4FAA4F;AAC5F,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,GAAG,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG,cAAc,CAAC,CAAC,CAAC,GAAG,aAAa,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;AAEnG;;GAEG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,GAAG,GAAG,EAAE,OAAO,UAAU,CAAC,CAAC,CAAC,KAAG,cAAc,CAAC,CAAC,CAoBvE,CAAC;AAEF;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GAAI,CAAC,GAAG,OAAO,EAAE,GAAG,CAAC,KAAG,cAAc,CAAC,CAAC,CAAwD,CAAC"}

package/typings/utils/ProxyRegistry.d.ts

@@ -1,20 +1,83 @@
+/**
+ * The proxy operations the library depends on. Depend on this rather than on
+ * {@link ProxyRegistry} itself, so a caller can substitute its own
+ * implementation - the concrete registry is a singleton and cannot be
+ * constructed a second time.
+ */
 export interface IProxyRegistry {
+    /**
+     * Returns the real object behind `value`, unwrapping proxies stacked to any
+     * depth. A value that is not a proxy is returned as is.
+     *
+     * The library calls this itself wherever a proxy would give the wrong answer -
+     * every read of class metadata (see `resolveConstructor`, `getHooks`,
+     * `resolveArgs`) and every identity check against a tracked instance (see
+     * `IContainer.hasInstance`). Pass the container's own values to those APIs as
+     * they come; unwrapping by hand is for code that needs the real object for its
+     * own reasons.
+     */
     unwrap<T extends object>(value: T): T;
     createProxy<T extends object>(target: T, handler?: ProxyHandler<T>): T;
+    /**
+     * Creates a proxy that resolves its target on first access and caches it.
+     */
     createLazyProxy<T extends object>(resolveInstance: () => T): T;
+    /**
+     * Wraps `resolveInstance` in a lazy proxy when `isLazy`, otherwise calls it
+     * right away.
+     */
     toLazyIf<T extends object>(resolveInstance: () => T, isLazy?: boolean): T;
 }
+/**
+ * Creates proxies and tracks them, so a proxy can be traced back to the real
+ * object it stands for. The library's own {@link IProxyRegistry}.
+ *
+ * Process-wide singleton: a proxy created anywhere must be unwrappable
+ * everywhere, and the registry holds no configuration that would justify a
+ * second instance. Obtain it with {@link ProxyRegistry.getInstance}.
+ *
+ * Entries are held weakly - a proxy that becomes unreachable is collected along
+ * with its state.
+ */
 export declare class ProxyRegistry implements IProxyRegistry {
     private static instance?;
     private readonly states;
     private constructor();
     static getInstance(): ProxyRegistry;
+    /**
+     * Returns the real object behind `value`, unwrapping proxies stacked to any
+     * depth. A value that is not a proxy is returned as is.
+     */
     unwrap<T extends object>(value: T): T;
     createProxy<T extends object>(target: T, handler?: ProxyHandler<T>): T;
+    /**
+     * Creates a proxy that resolves its target on first access and caches it.
+     * The target is unwrapped on resolution, so wrapping a lazy proxy in another
+     * lazy proxy never stacks beyond one level.
+     */
     createLazyProxy<T extends object>(resolveInstance: () => T): T;
+    /**
+     * Wraps `resolveInstance` in a lazy proxy when `isLazy`, otherwise calls it
+     * right away.
+     */
     toLazyIf<T extends object>(resolveInstance: () => T, isLazy?: boolean): T;
     private isProxy;
     private getTarget;
     private register;
 }
+/**
+ * The real object behind `value`, unwrapping proxies stacked to any depth. A
+ * value that is not a proxy is returned as is.
+ *
+ * A shortcut for `ProxyRegistry.getInstance().unwrap(value)` - the registry is a
+ * process-wide singleton, so unwrapping never needs an instance of its own. The
+ * library already unwraps wherever a proxy would give the wrong answer (reading
+ * class metadata, and `IContainer.hasInstance`), so reach for this only when
+ * your own code needs the real object - an identity check of your own, or
+ * bypassing a lazy proxy on purpose.
+ *
+ * Note that unwrapping a lazy proxy resolves its target, which is the point:
+ * there is no real object to hand back until it does.
+ */
 export declare const unwrapProxy: <T extends object>(value: T) => T;
+//# sourceMappingURL=ProxyRegistry.d.ts.map

package/typings/utils/ProxyRegistry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ProxyRegistry.d.ts","sourceRoot":"","sources":["../../lib/utils/ProxyRegistry.ts"],"names":[],"mappings":"AAIA;;;;;GAKG;AACH,MAAM,WAAW,cAAc;IAC7B;;;;;;;;;;OAUG;IACH,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC;IAEtC,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAEvE;;OAEG;IACH,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,eAAe,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC;IAE/D;;;OAGG;IACH,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC;CAC3E;AAED;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,YAAW,cAAc;IAClD,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAgB;IAExC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA6C;IAEpE,OAAO;IAEP,MAAM,CAAC,WAAW,IAAI,aAAa;IAKnC;;;OAGG;IACH,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC;IAIrC,WAAW,CAAC,CAAC,SAAS,MAAM,EAAE,MAAM,EAAE,CAAC,EAAE,OAAO,GAAE,YAAY,CAAC,CAAC,CAAM,GAAG,CAAC;IAK1E;;;;OAIG;IACH,eAAe,CAAC,CAAC,SAAS,MAAM,EAAE,eAAe,EAAE,MAAM,CAAC,GAAG,CAAC;IAgC9D;;;OAGG;IACH,QAAQ,CAAC,CAAC,SAAS,MAAM,EAAE,eAAe,EAAE,MAAM,CAAC,EAAE,MAAM,GAAE,OAAe,GAAG,CAAC;IAIhF,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,SAAS;IAKjB,OAAO,CAAC,QAAQ;CAIjB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,MAAM,EAAE,OAAO,CAAC,KAAG,CAA8C,CAAC"}