ts-ioc-container 72.2.0 → 72.3.0

package/esm/token/BindableToken.js

@@ -0,0 +1,59 @@
+import { forwardArgs, InjectionToken } from './InjectionToken.js';
+export class BindableToken extends InjectionToken {
+    token;
+    getArgsFn;
+    isLazyByDefault;
+    memberships;
+    constructor(token, { getArgsFn = forwardArgs, isLazy = false, tags = [], memberships = [] } = {}) {
+        super(tags);
+        this.token = token;
+        this.getArgsFn = getArgsFn;
+        this.isLazyByDefault = isLazy;
+        this.memberships = memberships;
+    }
+    bindTo(r) {
+        this.bindKey(r);
+        for (const alias of this.memberships) {
+            r.bindToAlias(alias);
+        }
+    }
+    variantOf(feature, name) {
+        return this.copy({ memberships: [...this.memberships, feature.variantAlias(name)] });
+    }
+    primaryVariantOf(feature) {
+        return this.copy({ memberships: [...this.memberships, feature.primaryAlias()] });
+    }
+    fallbackOf(feature) {
+        return this.copy({ memberships: [...this.memberships, feature.fallbackAlias()] });
+    }
+    args(...newArgs) {
+        const parentFn = this.getArgsFn;
+        return this.copy({ getArgsFn: (options) => [...parentFn(options), ...newArgs] });
+    }
+    argsFn(fn) {
+        const parentFn = this.getArgsFn;
+        return this.copy({ getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)] });
+    }
+    lazy() {
+        return this.copy({ isLazy: true });
+    }
+    addTags(...tags) {
+        return this.copy({ tags: [...this.getTags(), ...tags] });
+    }
+    toString() {
+        return this.token.toString();
+    }
+    toResolveOptions(s, { args = [], lazy } = {}) {
+        return { args: this.getArgsFn({ scope: s, args }), lazy: this.isLazyByDefault || lazy };
+    }
+    copy(overrides) {
+        const Self = this.constructor;
+        return new Self(this.token, {
+            getArgsFn: this.getArgsFn,
+            isLazy: this.isLazyByDefault,
+            tags: this.getTags(),
+            memberships: this.memberships,
+            ...overrides,
+        });
+    }
+}

package/esm/token/GroupAliasToken.js

@@ -1,58 +1,13 @@
-import { forwardArgs, InjectionToken } from './InjectionToken.js';
-export class GroupAliasToken extends InjectionToken {
-    token;
-    _getArgsFn;
-    _isLazy;
-    constructor(token, { getArgsFn = forwardArgs, isLazy = false, tags = [], } = {}) {
-        super(tags);
-        this.token = token;
-        this._getArgsFn = getArgsFn;
-        this._isLazy = isLazy;
-    }
+import { BindableToken } from './BindableToken.js';
+export class GroupAliasToken extends BindableToken {
     select(fn) {
         return (s) => fn(this.resolve(s));
     }
-    resolve(s, { args = [], lazy } = {}) {
-        return s.resolveByAlias(this.token, {
-            args: this._getArgsFn({ scope: s, args }),
-            lazy: this._isLazy || lazy,
-        });
+    resolve(s, options) {
+        return s.resolveByAlias(this.token, this.toResolveOptions(s, options));
     }
-    bindTo(r) {
+    bindKey(r) {
         r.bindToAlias(this.token);
     }
-    args(...newArgs) {
-        const parentFn = this._getArgsFn;
-        return new GroupAliasToken(this.token, {
-            getArgsFn: (options) => [...parentFn(options), ...newArgs],
-            isLazy: this._isLazy,
-            tags: this.getTags(),
-        });
-    }
-    argsFn(fn) {
-        const parentFn = this._getArgsFn;
-        return new GroupAliasToken(this.token, {
-            getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)],
-            isLazy: this._isLazy,
-            tags: this.getTags(),
-        });
-    }
-    lazy() {
-        return new GroupAliasToken(this.token, {
-            getArgsFn: this._getArgsFn,
-            isLazy: true,
-            tags: this.getTags(),
-        });
-    }
-    addTags(...tags) {
-        return new GroupAliasToken(this.token, {
-            getArgsFn: this._getArgsFn,
-            isLazy: this._isLazy,
-            tags: [...this.getTags(), ...tags],
-        });
-    }
-    toString() {
-        return this.token.toString();
-    }
 }
 export const toGroupAlias = (token) => new GroupAliasToken(token);

package/esm/token/MultiVariantFeatureToken.js

@@ -0,0 +1,80 @@
+import { forwardArgs, InjectionToken } from './InjectionToken.js';
+import { ProxyRegistry } from '../utils/ProxyRegistry.js';
+import { DependencyNotFoundError } from '../errors/DependencyNotFoundError.js';
+import { IFeatureContextToken, IFeatureFlagsToken, } from '../feature/IFeatureFlags.js';
+export class MultiVariantFeatureToken extends InjectionToken {
+    flag;
+    _getArgsFn;
+    _isLazy;
+    constructor(flag, { getArgsFn = forwardArgs, isLazy = false, tags = [] } = {}) {
+        super(tags);
+        this.flag = flag;
+        this._getArgsFn = getArgsFn;
+        this._isLazy = isLazy;
+    }
+    variantAlias(name) {
+        return `feature:${this.flag}:variant:${name}`;
+    }
+    primaryAlias() {
+        return `feature:${this.flag}:primary`;
+    }
+    fallbackAlias() {
+        return `feature:${this.flag}:fallback`;
+    }
+    resolve(s, { args = [], lazy } = {}) {
+        const resolveSelected = () => s.resolveOneByAlias(this.selectAlias(s), { args: this._getArgsFn({ scope: s, args }) });
+        return ProxyRegistry.getInstance().toLazyIf(resolveSelected, this._isLazy || lazy);
+    }
+    args(...newArgs) {
+        const parentFn = this._getArgsFn;
+        return this.copy({ getArgsFn: (options) => [...parentFn(options), ...newArgs] });
+    }
+    argsFn(fn) {
+        const parentFn = this._getArgsFn;
+        return this.copy({ getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)] });
+    }
+    lazy() {
+        return this.copy({ isLazy: true });
+    }
+    addTags(...tags) {
+        return this.copy({ tags: [...this.getTags(), ...tags] });
+    }
+    toString() {
+        return this.flag;
+    }
+    evaluate(flags, context) {
+        const served = flags.getVariant(this.flag, context);
+        return served.enabled
+            ? { enabled: true, variant: served.name }
+            : { enabled: flags.isEnabled(this.flag, context) };
+    }
+    copy(overrides) {
+        const Self = this.constructor;
+        return new Self(this.flag, {
+            getArgsFn: this._getArgsFn,
+            isLazy: this._isLazy,
+            tags: this.getTags(),
+            ...overrides,
+        });
+    }
+    selectAlias(s) {
+        const fallback = this.fallbackAlias();
+        if (!s.hasAlias(fallback)) {
+            throw new DependencyNotFoundError(`Feature flag "${this.flag}" has no fallback: a flag always has one. ` +
+                `Register it with @register(token.fallbackOf(feature)) in this scope or a parent.`);
+        }
+        const flags = IFeatureFlagsToken.resolve(s);
+        const context = IFeatureContextToken.resolve(s);
+        let served = { enabled: false };
+        try {
+            served = this.evaluate(flags, context);
+        }
+        catch {
+        }
+        const candidates = [
+            served.variant === undefined ? undefined : this.variantAlias(served.variant),
+            served.enabled ? this.primaryAlias() : undefined,
+        ];
+        return candidates.find((alias) => alias !== undefined && s.hasAlias(alias)) ?? fallback;
+    }
+}

package/esm/token/SingleAliasToken.js

@@ -1,58 +1,13 @@
-import { forwardArgs, InjectionToken } from './InjectionToken.js';
-export class SingleAliasToken extends InjectionToken {
-    token;
-    _getArgsFn;
-    _isLazy;
-    constructor(token, { getArgsFn = forwardArgs, isLazy = false, tags = [], } = {}) {
-        super(tags);
-        this.token = token;
-        this._getArgsFn = getArgsFn;
-        this._isLazy = isLazy;
-    }
+import { BindableToken } from './BindableToken.js';
+export class SingleAliasToken extends BindableToken {
     select(fn) {
         return (s) => fn(this.resolve(s));
     }
-    resolve(s, { args = [], lazy } = {}) {
-        return s.resolveOneByAlias(this.token, {
-            args: this._getArgsFn({ scope: s, args }),
-            lazy: this._isLazy || lazy,
-        });
+    resolve(s, options) {
+        return s.resolveOneByAlias(this.token, this.toResolveOptions(s, options));
     }
-    bindTo(r) {
+    bindKey(r) {
         r.bindToAlias(this.token);
     }
-    args(...newArgs) {
-        const parentFn = this._getArgsFn;
-        return new SingleAliasToken(this.token, {
-            getArgsFn: (options) => [...parentFn(options), ...newArgs],
-            isLazy: this._isLazy,
-            tags: this.getTags(),
-        });
-    }
-    argsFn(fn) {
-        const parentFn = this._getArgsFn;
-        return new SingleAliasToken(this.token, {
-            getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)],
-            isLazy: this._isLazy,
-            tags: this.getTags(),
-        });
-    }
-    lazy() {
-        return new SingleAliasToken(this.token, {
-            getArgsFn: this._getArgsFn,
-            isLazy: true,
-            tags: this.getTags(),
-        });
-    }
-    addTags(...tags) {
-        return new SingleAliasToken(this.token, {
-            getArgsFn: this._getArgsFn,
-            isLazy: this._isLazy,
-            tags: [...this.getTags(), ...tags],
-        });
-    }
-    toString() {
-        return this.token.toString();
-    }
 }
 export const toSingleAlias = (token) => new SingleAliasToken(token);

package/esm/token/SingleToken.js

@@ -1,57 +1,12 @@
-import { forwardArgs, InjectionToken } from './InjectionToken.js';
-export class SingleToken extends InjectionToken {
-    token;
-    _getArgsFn;
-    _isLazy;
-    constructor(token, { getArgsFn = forwardArgs, isLazy = false, tags = [], } = {}) {
-        super(tags);
-        this.token = token;
-        this._getArgsFn = getArgsFn;
-        this._isLazy = isLazy;
-    }
+import { BindableToken } from './BindableToken.js';
+export class SingleToken extends BindableToken {
     select(fn) {
         return (s) => fn(this.resolve(s));
     }
-    resolve(s, { args = [], lazy } = {}) {
-        return s.resolve(this.token, {
-            args: this._getArgsFn({ scope: s, args }),
-            lazy: this._isLazy || lazy,
-        });
+    resolve(s, options) {
+        return s.resolve(this.token, this.toResolveOptions(s, options));
     }
-    bindTo(r) {
+    bindKey(r) {
         r.bindToKey(this.token);
     }
-    args(...newArgs) {
-        const parentFn = this._getArgsFn;
-        return new SingleToken(this.token, {
-            getArgsFn: (options) => [...parentFn(options), ...newArgs],
-            isLazy: this._isLazy,
-            tags: this.getTags(),
-        });
-    }
-    argsFn(fn) {
-        const parentFn = this._getArgsFn;
-        return new SingleToken(this.token, {
-            getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)],
-            isLazy: this._isLazy,
-            tags: this.getTags(),
-        });
-    }
-    lazy() {
-        return new SingleToken(this.token, {
-            getArgsFn: this._getArgsFn,
-            isLazy: true,
-            tags: this.getTags(),
-        });
-    }
-    addTags(...tags) {
-        return new SingleToken(this.token, {
-            getArgsFn: this._getArgsFn,
-            isLazy: this._isLazy,
-            tags: [...this.getTags(), ...tags],
-        });
-    }
-    toString() {
-        return this.token.toString();
-    }
 }

package/esm/token/ToggleFeatureToken.js

@@ -0,0 +1,6 @@
+import { MultiVariantFeatureToken } from './MultiVariantFeatureToken.js';
+export class ToggleFeatureToken extends MultiVariantFeatureToken {
+    evaluate(flags, context) {
+        return { enabled: flags.isEnabled(this.flag, context) };
+    }
+}

package/lib/container/Container.ts

@@ -235,6 +235,10 @@ export class Container implements IContainer {
     return this.registrations.some((r) => r.getKeyOrFail() === key) || this.parent.hasRegistration(key);
   }
 
+  hasAlias(alias: DependencyKey): boolean {
+    return this.aliases.getKeysByAlias(alias).length > 0 || this.parent.hasAlias(alias);
+  }
+
   addInstance(instance: Instance) {
     this.instances.add(instance);
   }

package/lib/container/EmptyContainer.ts

@@ -103,6 +103,10 @@ export class EmptyContainer implements IContainer {
     return false;
   }
 
+  hasAlias(alias: DependencyKey): boolean {
+    return false;
+  }
+
   removeScope(): void {}
 
   /**

package/lib/container/IContainer.ts

@@ -99,6 +99,9 @@ export interface IContainer extends Tagged {
   /** Whether a provider is registered under `key` in this scope (parents are not checked). */
   hasRegistration(key: DependencyKey): boolean;
 
+  /** Whether a provider carrying `alias` is registered in this scope or a parent. Never throws for a missing alias. */
+  hasAlias(alias: DependencyKey): boolean;
+
   /**
    * Resolves a key, or constructs a class with the injector. Takes a key or a
    * class, not a token: for a token call `token.resolve(scope)`.

package/lib/feature/IFeatureFlags.ts

@@ -0,0 +1,44 @@
+import { SingleToken } from '../token/SingleToken';
+
+/**
+ * What a flag is evaluated for - usually the current user. Shaped after the
+ * Unleash context, so an Unleash client accepts it as is.
+ */
+export type FeatureContext = {
+  userId?: string;
+  sessionId?: string;
+  remoteAddress?: string;
+  environment?: string;
+  properties?: Record<string, string | number | undefined>;
+  [key: string]: unknown;
+};
+
+/** A variant served for a flag. Unleash reports `{ name: 'disabled', enabled: false }` for a flag that is off. */
+export type FeatureVariant = { name: string; enabled: boolean };
+
+/**
+ * The flag client feature tokens ask: `getVariant` for a
+ * `MultiVariantFeatureToken`, `isEnabled` for a `ToggleFeatureToken`.
+ * Synchronous, because resolution is. An Unleash client satisfies it
+ * structurally - register the instance itself; an asynchronous client
+ * (OpenFeature server SDK) needs an adapter which evaluates ahead of time and
+ * answers from that snapshot.
+ *
+ * @example
+ * container.addRegistration(Registration.fromValue(unleash).bindTo(IFeatureFlagsToken));
+ */
+export interface IFeatureFlags {
+  isEnabled(name: string, context?: FeatureContext): boolean;
+
+  getVariant(name: string, context?: FeatureContext): FeatureVariant;
+}
+
+/** Where feature tokens find the flag client. */
+export const IFeatureFlagsToken = new SingleToken<IFeatureFlags>('IFeatureFlags');
+
+/**
+ * Where feature tokens find the context to evaluate a flag for. Register it
+ * in the scope that knows the user (e.g. `request`); register `{}` for flags
+ * that do not depend on one.
+ */
+export const IFeatureContextToken = new SingleToken<FeatureContext>('IFeatureContext');

package/lib/index.ts

@@ -126,10 +126,26 @@ export { type Injectable, toToken, argToToken } from './token/toToken';
 export { GroupAliasToken, toGroupAlias } from './token/GroupAliasToken';
 export { SingleAliasToken, toSingleAlias } from './token/SingleAliasToken';
 export { ClassToken } from './token/ClassToken';
+export { BindableToken, type BindableTokenOptions } from './token/BindableToken';
 export { SingleToken } from './token/SingleToken';
 export { FunctionToken } from './token/FunctionToken';
 export { ConstantToken } from './token/ConstantToken';
 export { type InstancePredicate, GroupInstanceToken } from './token/GroupInstanceToken';
+export {
+  MultiVariantFeatureToken,
+  type FeatureTokenOptions,
+  type FeatureEvaluation,
+} from './token/MultiVariantFeatureToken';
+export { ToggleFeatureToken } from './token/ToggleFeatureToken';
+
+// Feature flags
+export {
+  type IFeatureFlags,
+  type FeatureContext,
+  type FeatureVariant,
+  IFeatureFlagsToken,
+  IFeatureContextToken,
+} from './feature/IFeatureFlags';
 
 // Metadata
 export { resolveConstructor } from './metadata/target';

package/lib/registration/IRegistration.ts

@@ -106,11 +106,16 @@ export const getTransformers = (Target: constructor<unknown>) =>
 
 /**
  * Class decorator that configures how `Registration.fromClass(Target)` registers
- * the class: binding keys, scope rules and provider pipes. A bare key or token
- * is shorthand for `bindTo(...)`. Without a key the class name is used.
+ * the class: binding keys, scope rules and provider pipes. Without a key the
+ * class name is used.
+ *
+ * Pass a key or a token directly - `@register(ILoggerToken)`, `@register('ILogger')`.
+ * It is bound exactly as `bindTo(...)` would bind it, so wrapping it in
+ * `bindTo(...)` here is redundant; `bindTo` is for the fluent
+ * `Registration...` chain.
  *
  * @example
- * @register(bindTo(ILoggerToken), scope((s) => s.hasTag('application')), singleton())
+ * @register(ILoggerToken, scope((s) => s.hasTag('application')), singleton())
  * class Logger implements ILogger {}
  *
  * container.addRegistration(Registration.fromClass(Logger));
@@ -125,9 +130,11 @@ export const register = (...mappers: RegistrationMapper[]) =>
  * Binds a registration to one or more keys or tokens. A `SingleToken` binds its
  * key; an alias token (`toSingleAlias`, `toGroupAlias`) adds an alias.
  *
+ * Inside `@register(...)` pass the token itself instead - `@register(ILoggerToken)`
+ * binds it the same way, so `@register(bindTo(ILoggerToken))` is redundant.
+ *
  * @example
- * @register(bindTo(ILoggerToken))
- * class Logger {}
+ * Registration.fromClass(Logger).bindTo(ILoggerToken);
  *
  * @example
  * Registration.fromValue(config).bindTo('Config');

package/lib/token/BindableToken.ts

@@ -0,0 +1,137 @@
+import { type DependencyKey, type IContainer } from '../container/IContainer';
+import { forwardArgs, InjectionToken } from './InjectionToken';
+import { type BindToken } from './BindToken';
+import { type IRegistration } from '../registration/IRegistration';
+import { type ArgsFn, type ResolveOptions } from '../provider/IProvider';
+import { type Serializable } from '../utils/basic';
+import { type MultiVariantFeatureToken } from './MultiVariantFeatureToken';
+
+// Blocks inference from `name` so it must be one of the feature's variants (TS < 5.4 has no NoInfer).
+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 abstract class BindableToken<T = any, R = T> extends InjectionToken<R> implements BindToken<T>, Serializable {
+  private readonly getArgsFn: ArgsFn;
+  private readonly isLazyByDefault: boolean;
+  private readonly memberships: DependencyKey[];
+
+  constructor(
+    readonly token: DependencyKey,
+    { getArgsFn = forwardArgs, isLazy = false, tags = [], memberships = [] }: BindableTokenOptions = {},
+  ) {
+    super(tags);
+    this.getArgsFn = getArgsFn;
+    this.isLazyByDefault = isLazy;
+    this.memberships = memberships;
+  }
+
+  /** Binds `r` under this token, and into every feature this token declared itself a variant or fallback of. */
+  bindTo(r: IRegistration<T>): void {
+    this.bindKey(r);
+    for (const alias of this.memberships) {
+      r.bindToAlias(alias);
+    }
+  }
+
+  /**
+   * 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 {
+    return this.copy({ memberships: [...this.memberships, feature.variantAlias(name)] });
+  }
+
+  /**
+   * 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 {
+    return this.copy({ memberships: [...this.memberships, feature.primaryAlias()] });
+  }
+
+  /**
+   * 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 {
+    return this.copy({ memberships: [...this.memberships, feature.fallbackAlias()] });
+  }
+
+  args(...newArgs: unknown[]): this {
+    const parentFn = this.getArgsFn;
+    return this.copy({ getArgsFn: (options) => [...parentFn(options), ...newArgs] });
+  }
+
+  argsFn(fn: (s: IContainer) => unknown[]): this {
+    const parentFn = this.getArgsFn;
+    return this.copy({ getArgsFn: (options) => [...parentFn(options), ...fn(options.scope)] });
+  }
+
+  lazy(): this {
+    return this.copy({ isLazy: true });
+  }
+
+  addTags(...tags: string[]): this {
+    return this.copy({ tags: [...this.getTags(), ...tags] });
+  }
+
+  toString(): string {
+    return this.token.toString();
+  }
+
+  /** 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 {
+    // `lazy` stays undefined unless someone asked, so a provider's own `lazy()` pipe still applies.
+    return { args: this.getArgsFn({ scope: s, args }), lazy: this.isLazyByDefault || lazy };
+  }
+
+  private copy(overrides: BindableTokenOptions): this {
+    const Self = this.constructor as new (token: DependencyKey, options: BindableTokenOptions) => this;
+    return new Self(this.token, {
+      getArgsFn: this.getArgsFn,
+      isLazy: this.isLazyByDefault,
+      tags: this.getTags(),
+      memberships: this.memberships,
+      ...overrides,
+    });
+  }
+}