ts-ioc-container 72.2.0 → 72.3.1

package/README.md

@@ -52,7 +52,9 @@ provider pipelines, aliases, and custom injector strategies.
 - [Registration](#registration) `@register`
   - [Token](#token) `bindTo`
   - [Scope](#scope) `scope`
+  - [Environment-based registration](#environment-based-registration) `Env`
   - [Composing decorators](#composing-decorators) `createComposeClassDecorator`
+  - [Feature flags](#feature-flags) `MultiVariantFeatureToken` `ToggleFeatureToken`
 - [Module](#module)
 - [Hook](#hook) `@hook`
   - [Hook domains](#hook-domains) `ScopeHook` `InjectorHook` `ProviderHook`
@@ -2795,6 +2797,78 @@ describe('Scopes', function () {
 
 ```
 
+### Environment-based registration
+
+Picking an implementation by deployment environment (`prod` / `dev` / `test`)
+needs no dedicated API - it is the same `scope()` mechanism as above: tag the
+container with its env and scope each implementation to the env it belongs to.
+Multiple registrations share the same key; only the one whose scope rule
+matches the container's tag registers there.
+
+```typescript
+import { bindTo, Container, register, Registration as R, scope, SingleToken } from 'ts-ioc-container';
+
+/**
+ * Environment-based Registration
+ *
+ * An app often needs a different implementation per deployment environment -
+ * a real payment gateway in production, a stub in tests, a verbose one in dev.
+ * This is a plain application of `scope()`: tag the container with its env and
+ * scope each implementation to the env tag it belongs to. No dedicated API is
+ * needed - the same `ScopeMatchRule` mechanism used for `request` / `transaction`
+ * scopes applies here too.
+ */
+type Env = 'prod' | 'dev' | 'test';
+
+interface IPaymentGateway {
+  charge(amount: number): string;
+}
+
+const PaymentGatewayToken = new SingleToken<IPaymentGateway>('IPaymentGateway');
+
+@register(bindTo(PaymentGatewayToken), scope((c) => c.hasTag('prod')))
+class StripeGateway implements IPaymentGateway {
+  charge(amount: number): string {
+    return `charged $${amount} via Stripe`;
+  }
+}
+
+@register(bindTo(PaymentGatewayToken), scope((c) => c.hasTag('dev')))
+class LoggingGateway implements IPaymentGateway {
+  charge(amount: number): string {
+    return `[dev] would charge $${amount}`;
+  }
+}
+
+@register(bindTo(PaymentGatewayToken), scope((c) => c.hasTag('test')))
+class FakeGateway implements IPaymentGateway {
+  charge(amount: number): string {
+    return `faked charge of $${amount}`;
+  }
+}
+
+const createContainerForEnv = (env: Env) =>
+  new Container({ tags: [env] })
+    .addRegistration(R.fromClass(StripeGateway))
+    .addRegistration(R.fromClass(LoggingGateway))
+    .addRegistration(R.fromClass(FakeGateway));
+
+describe('Environment-based registration', function () {
+  it('should resolve the implementation whose scope tag matches the container env', function () {
+    expect(PaymentGatewayToken.resolve(createContainerForEnv('prod'))).toBeInstanceOf(StripeGateway);
+    expect(PaymentGatewayToken.resolve(createContainerForEnv('dev'))).toBeInstanceOf(LoggingGateway);
+    expect(PaymentGatewayToken.resolve(createContainerForEnv('test'))).toBeInstanceOf(FakeGateway);
+  });
+
+  it('should behave like the environment it was resolved for', function () {
+    const gateway = PaymentGatewayToken.resolve(createContainerForEnv('test'));
+
+    expect(gateway.charge(10)).toBe('faked charge of $10');
+  });
+});
+
+```
+
 ### Composing decorators
 
 A decorator stack repeated on every class of a layer is worth a name.
@@ -2887,6 +2961,174 @@ describe('composing decorators', () => {
 
 ```
 
+### Feature flags
+
+Feature tokens let a feature flag choose which implementation is injected, so
+consumers depend on one type and never see the flag. The implementations
+decide where they belong - each one's own token declares its role:
+
+- `token.variantOf(Feature, 'blue')` - used while the flag serves the variant `blue` (`getVariant`)
+- `token.primaryVariantOf(Feature)` - used while the flag is on and no named variant implementation matches
+- `token.fallbackOf(Feature)` - used otherwise: the flag is off, serves nothing implemented, or its client throws
+
+**Every flag has a fallback**: resolving a feature without one registered is a
+`DependencyNotFoundError`, whatever the flag serves. `MultiVariantFeatureToken<T, V>`
+is the general case; `ToggleFeatureToken<T>` is its on/off case - no named
+variants, only a primary one (`isEnabled`). Each implementation stays
+injectable through its own token.
+
+The flag client comes from `IFeatureFlagsToken` and the context it evaluates
+for from `IFeatureContextToken`, both resolved from the resolving scope on every
+resolution - register the context in your `request` scope. A missing client or
+context is a `DependencyNotFoundError`, never a silent fallback.
+
+`IFeatureFlags` is shaped after Unleash (`isEnabled(name, context)`,
+`getVariant(name, context)`), so an Unleash client is registered as is:
+`R.fromValue(unleash).bindTo(IFeatureFlagsToken)`. Resolution is synchronous;
+wrap an asynchronous client (e.g. the OpenFeature server SDK) in an adapter
+that evaluates ahead of time. `Feature.lazy()` defers the evaluation to first use.
+
+```typescript
+import 'reflect-metadata';
+import {
+  by,
+  Container,
+  type FeatureContext,
+  type FeatureVariant,
+  type IFeatureFlags,
+  IFeatureContextToken,
+  IFeatureFlagsToken,
+  inject,
+  MultiVariantFeatureToken,
+  register,
+  Registration as R,
+  SingleToken,
+  ToggleFeatureToken,
+} from 'ts-ioc-container';
+
+/**
+ * Checkout Domain - Feature Flags
+ *
+ * A flag chooses which implementation is injected; the consumer depends on one
+ * type and never sees the flag. The implementations decide where they belong:
+ * each one's own token declares it
+ *
+ * - `.variantOf(feature, name)` - used while the flag serves the variant `name`;
+ * - `.primaryVariantOf(feature)` - used while the flag is on and no named
+ *   variant implementation matches (the "on" side of a toggle);
+ * - `.fallbackOf(feature)` - used otherwise. Every flag has one.
+ *
+ * `ToggleFeatureToken` is the on/off case of `MultiVariantFeatureToken`: no
+ * named variants, only a primary one.
+ *
+ * The flag client is any object with `isEnabled(name, context)` and
+ * `getVariant(name, context)` - an Unleash client works as is:
+ *   container.addRegistration(R.fromValue(unleash).bindTo(IFeatureFlagsToken));
+ */
+
+// Toggle: new checkout on / off
+interface IPaymentGateway {
+  pay(amount: number): string;
+}
+
+const PaymentGatewayToken = new ToggleFeatureToken<IPaymentGateway>('new-checkout');
+
+// Each implementation's own token declares where it belongs
+@register(new SingleToken<IPaymentGateway>('LegacyGateway').fallbackOf(PaymentGatewayToken))
+class LegacyGateway implements IPaymentGateway {
+  pay(amount: number) {
+    return `legacy charged ${amount}`;
+  }
+}
+
+@register(new SingleToken<IPaymentGateway>('StripeGateway').primaryVariantOf(PaymentGatewayToken))
+class StripeGateway implements IPaymentGateway {
+  pay(amount: number) {
+    return `stripe charged ${amount}`;
+  }
+}
+
+// Multi-variant: A/B/n experiment on the checkout button
+interface ICheckoutButton {
+  render(): string;
+}
+
+const CheckoutButtonToken = new MultiVariantFeatureToken<ICheckoutButton, 'blue' | 'green'>('checkout-button');
+
+@register(new SingleToken<ICheckoutButton>('GreyButton').fallbackOf(CheckoutButtonToken))
+class GreyButton implements ICheckoutButton {
+  render() {
+    return 'grey button';
+  }
+}
+
+@register(new SingleToken<ICheckoutButton>('BlueButton').variantOf(CheckoutButtonToken, 'blue'))
+class BlueButton implements ICheckoutButton {
+  render() {
+    return 'blue button';
+  }
+}
+
+@register(new SingleToken<ICheckoutButton>('GreenButton').variantOf(CheckoutButtonToken, 'green'))
+class GreenButton implements ICheckoutButton {
+  render() {
+    return 'green button';
+  }
+}
+
+class CheckoutPage {
+  constructor(
+    @inject(by(PaymentGatewayToken)) private readonly gateway: IPaymentGateway,
+    @inject(by(CheckoutButtonToken)) private readonly button: ICheckoutButton,
+  ) {}
+
+  render(amount: number) {
+    return `${this.button.render()}, ${this.gateway.pay(amount)}`;
+  }
+}
+
+// Stands in for an Unleash client
+class InMemoryFlags implements IFeatureFlags {
+  isEnabled(name: string, context?: FeatureContext) {
+    return name === 'new-checkout' && context?.userId === 'beta-tester';
+  }
+
+  getVariant(name: string, context?: FeatureContext): FeatureVariant {
+    const bucket = { 'beta-tester': 'green', 'user-1': 'blue' }[context?.userId ?? ''];
+    return name === 'checkout-button' && bucket
+      ? { name: bucket, enabled: true }
+      : { name: 'disabled', enabled: false };
+  }
+}
+
+describe('Feature flags', () => {
+  const app = new Container({ tags: ['application'] })
+    .addRegistration(R.fromValue(new InMemoryFlags()).bindTo(IFeatureFlagsToken))
+    .addRegistration(R.fromClass(LegacyGateway))
+    .addRegistration(R.fromClass(GreyButton))
+    .addRegistration(R.fromClass(StripeGateway))
+    .addRegistration(R.fromClass(BlueButton))
+    .addRegistration(R.fromClass(GreenButton));
+
+  // The context is per request: each request evaluates the flags for its own user
+  const handleRequest = (userId: string) => {
+    const request = app.createScope({ tags: ['request'] });
+    request.addRegistration(R.fromValue({ userId }).bindTo(IFeatureContextToken));
+    return request.resolve(CheckoutPage).render(42);
+  };
+
+  it('serves each user the implementations their flags select', () => {
+    expect(handleRequest('beta-tester')).toBe('green button, stripe charged 42');
+    expect(handleRequest('user-1')).toBe('blue button, legacy charged 42');
+  });
+
+  it('serves the fallbacks to everyone else', () => {
+    expect(handleRequest('regular-user')).toBe('grey button, legacy charged 42');
+  });
+});
+
+```
+
 ## Module
 
 Sometimes you want to encapsulate registration logic in separate module. This is what `IContainerModule` is for.

package/cjm/container/Container.js

@@ -129,6 +129,9 @@ class Container {
     hasRegistration(key) {
         return this.registrations.some((r) => r.getKeyOrFail() === key) || this.parent.hasRegistration(key);
     }
+    hasAlias(alias) {
+        return this.aliases.getKeysByAlias(alias).length > 0 || this.parent.hasAlias(alias);
+    }
     addInstance(instance) {
         this.instances.add(instance);
     }

package/cjm/container/EmptyContainer.js

@@ -47,6 +47,9 @@ class EmptyContainer {
     hasRegistration(key) {
         return false;
     }
+    hasAlias(alias) {
+        return false;
+    }
     removeScope() { }
     useModule(module) {
         throw new MethodNotImplementedError_1.MethodNotImplementedError('EmptyContainer.useModule is not implemented');

package/cjm/feature/IFeatureFlags.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IFeatureContextToken = exports.IFeatureFlagsToken = void 0;
+const SingleToken_1 = require("../token/SingleToken");
+exports.IFeatureFlagsToken = new SingleToken_1.SingleToken('IFeatureFlags');
+exports.IFeatureContextToken = new SingleToken_1.SingleToken('IFeatureContext');

package/cjm/index.js

@@ -1,8 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createHookContextFactory = exports.HookContext = exports.toHookFn = exports.hasHooks = exports.hook = exports.getHooks = exports.ArgumentNotFoundError = exports.TypedEventDisposedError = exports.UnsupportedTokenTypeError = exports.CannonSingletonApplyTwiceError = exports.CannotApplySingletonTwiceError = exports.ProviderDisposedError = exports.ContainerDisposedError = exports.MethodNotImplementedError = exports.DependencyMissingKeyError = exports.ContainerNotFoundError = exports.DependencyNotFoundError = exports.ContainerError = exports.Registration = exports.onResolve = exports.appendArgsFn = exports.appendArgs = exports.decorate = exports.singleton = exports.autoResolve = exports.lazy = exports.scopeAccess = exports.scope = exports.bindTo = exports.register = exports.toRegistrationFn = exports.toProviderFn = exports.toBindToken = exports.registerPipe = exports.isProviderPipe = exports.Provider = exports.ProxyInjector = exports.SimpleInjector = exports.resolveArgs = exports.by = exports.argsFn = exports.args = exports.arg = exports.inject = exports.MetadataInjector = exports.Injector = exports.EmptyContainer = exports.AutoResolveModule = exports.Container = exports.isDependencyKey = void 0;
-exports.shallowCache = exports.debounce = exports.throttle = exports.runAtOnce = exports.runInOrder = exports.handleAsyncError = exports.handleError = exports.createComposeMethodDecorator = exports.getMethodTags = exports.addMethodTag = exports.getMethodLabels = exports.addMethodLabel = exports.getMethodMeta = exports.addMethodMeta = exports.createComposeParameterDecorator = exports.getParamTags = exports.addParamTag = exports.getParamLabels = exports.addParamLabel = exports.getParamMeta = exports.addParamMeta = exports.createComposeClassDecorator = exports.getClassTags = exports.addClassTag = exports.getClassLabels = exports.addClassLabel = exports.getClassMeta = exports.addClassMeta = exports.resolveConstructor = exports.GroupInstanceToken = exports.ConstantToken = exports.FunctionToken = exports.SingleToken = exports.ClassToken = exports.toSingleAlias = exports.SingleAliasToken = exports.toGroupAlias = exports.GroupAliasToken = exports.argToToken = exports.toToken = exports.forwardArgs = exports.isInjectionToken = exports.InjectionToken = exports.toTask = exports.HookCollector = exports.oncePerInstance = exports.parallel = exports.sequential = exports.injectProp = exports.createHookExecutionContext = void 0;
-exports.isSerializable = exports.Is = exports.unwrapProxy = exports.ProxyRegistry = exports.findOrFail = exports.pipe = exports.select = exports.TypedEvent = exports.getConstructorChain = exports.memoize = exports.once = void 0;
+exports.handleAsyncError = exports.handleError = exports.createComposeMethodDecorator = exports.getMethodTags = exports.addMethodTag = exports.getMethodLabels = exports.addMethodLabel = exports.getMethodMeta = exports.addMethodMeta = exports.createComposeParameterDecorator = exports.getParamTags = exports.addParamTag = exports.getParamLabels = exports.addParamLabel = exports.getParamMeta = exports.addParamMeta = exports.createComposeClassDecorator = exports.getClassTags = exports.addClassTag = exports.getClassLabels = exports.addClassLabel = exports.getClassMeta = exports.addClassMeta = exports.resolveConstructor = exports.IFeatureContextToken = exports.IFeatureFlagsToken = exports.ToggleFeatureToken = exports.MultiVariantFeatureToken = exports.GroupInstanceToken = exports.ConstantToken = exports.FunctionToken = exports.SingleToken = exports.BindableToken = exports.ClassToken = exports.toSingleAlias = exports.SingleAliasToken = exports.toGroupAlias = exports.GroupAliasToken = exports.argToToken = exports.toToken = exports.forwardArgs = exports.isInjectionToken = exports.InjectionToken = exports.toTask = exports.HookCollector = exports.oncePerInstance = exports.parallel = exports.sequential = exports.injectProp = exports.createHookExecutionContext = void 0;
+exports.isSerializable = exports.Is = exports.unwrapProxy = exports.ProxyRegistry = exports.findOrFail = exports.pipe = exports.select = exports.TypedEvent = exports.getConstructorChain = exports.memoize = exports.once = exports.shallowCache = exports.debounce = exports.throttle = exports.runAtOnce = exports.runInOrder = void 0;
 var IContainer_1 = require("./container/IContainer");
 Object.defineProperty(exports, "isDependencyKey", { enumerable: true, get: function () { return IContainer_1.isDependencyKey; } });
 var Container_1 = require("./container/Container");
@@ -103,6 +103,8 @@ Object.defineProperty(exports, "SingleAliasToken", { enumerable: true, get: func
 Object.defineProperty(exports, "toSingleAlias", { enumerable: true, get: function () { return SingleAliasToken_1.toSingleAlias; } });
 var ClassToken_1 = require("./token/ClassToken");
 Object.defineProperty(exports, "ClassToken", { enumerable: true, get: function () { return ClassToken_1.ClassToken; } });
+var BindableToken_1 = require("./token/BindableToken");
+Object.defineProperty(exports, "BindableToken", { enumerable: true, get: function () { return BindableToken_1.BindableToken; } });
 var SingleToken_1 = require("./token/SingleToken");
 Object.defineProperty(exports, "SingleToken", { enumerable: true, get: function () { return SingleToken_1.SingleToken; } });
 var FunctionToken_1 = require("./token/FunctionToken");
@@ -111,6 +113,13 @@ var ConstantToken_1 = require("./token/ConstantToken");
 Object.defineProperty(exports, "ConstantToken", { enumerable: true, get: function () { return ConstantToken_1.ConstantToken; } });
 var GroupInstanceToken_1 = require("./token/GroupInstanceToken");
 Object.defineProperty(exports, "GroupInstanceToken", { enumerable: true, get: function () { return GroupInstanceToken_1.GroupInstanceToken; } });
+var MultiVariantFeatureToken_1 = require("./token/MultiVariantFeatureToken");
+Object.defineProperty(exports, "MultiVariantFeatureToken", { enumerable: true, get: function () { return MultiVariantFeatureToken_1.MultiVariantFeatureToken; } });
+var ToggleFeatureToken_1 = require("./token/ToggleFeatureToken");
+Object.defineProperty(exports, "ToggleFeatureToken", { enumerable: true, get: function () { return ToggleFeatureToken_1.ToggleFeatureToken; } });
+var IFeatureFlags_1 = require("./feature/IFeatureFlags");
+Object.defineProperty(exports, "IFeatureFlagsToken", { enumerable: true, get: function () { return IFeatureFlags_1.IFeatureFlagsToken; } });
+Object.defineProperty(exports, "IFeatureContextToken", { enumerable: true, get: function () { return IFeatureFlags_1.IFeatureContextToken; } });
 var target_1 = require("./metadata/target");
 Object.defineProperty(exports, "resolveConstructor", { enumerable: true, get: function () { return target_1.resolveConstructor; } });
 var class_1 = require("./metadata/class");

package/cjm/token/BindableToken.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BindableToken = void 0;
+const InjectionToken_1 = require("./InjectionToken");
+class BindableToken extends InjectionToken_1.InjectionToken {
+    token;
+    getArgsFn;
+    isLazyByDefault;
+    memberships;
+    constructor(token, { getArgsFn = InjectionToken_1.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,
+        });
+    }
+}
+exports.BindableToken = BindableToken;

package/cjm/token/GroupAliasToken.js

@@ -1,62 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toGroupAlias = exports.GroupAliasToken = void 0;
-const InjectionToken_1 = require("./InjectionToken");
-class GroupAliasToken extends InjectionToken_1.InjectionToken {
-    token;
-    _getArgsFn;
-    _isLazy;
-    constructor(token, { getArgsFn = InjectionToken_1.forwardArgs, isLazy = false, tags = [], } = {}) {
-        super(tags);
-        this.token = token;
-        this._getArgsFn = getArgsFn;
-        this._isLazy = isLazy;
-    }
+const BindableToken_1 = require("./BindableToken");
+class GroupAliasToken extends BindableToken_1.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();
-    }
 }
 exports.GroupAliasToken = GroupAliasToken;
 const toGroupAlias = (token) => new GroupAliasToken(token);

package/cjm/token/MultiVariantFeatureToken.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultiVariantFeatureToken = void 0;
+const InjectionToken_1 = require("./InjectionToken");
+const ProxyRegistry_1 = require("../utils/ProxyRegistry");
+const DependencyNotFoundError_1 = require("../errors/DependencyNotFoundError");
+const IFeatureFlags_1 = require("../feature/IFeatureFlags");
+class MultiVariantFeatureToken extends InjectionToken_1.InjectionToken {
+    flag;
+    _getArgsFn;
+    _isLazy;
+    constructor(flag, { getArgsFn = InjectionToken_1.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_1.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_1.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 = IFeatureFlags_1.IFeatureFlagsToken.resolve(s);
+        const context = IFeatureFlags_1.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;
+    }
+}
+exports.MultiVariantFeatureToken = MultiVariantFeatureToken;

package/cjm/token/SingleAliasToken.js

@@ -1,62 +1,17 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toSingleAlias = exports.SingleAliasToken = void 0;
-const InjectionToken_1 = require("./InjectionToken");
-class SingleAliasToken extends InjectionToken_1.InjectionToken {
-    token;
-    _getArgsFn;
-    _isLazy;
-    constructor(token, { getArgsFn = InjectionToken_1.forwardArgs, isLazy = false, tags = [], } = {}) {
-        super(tags);
-        this.token = token;
-        this._getArgsFn = getArgsFn;
-        this._isLazy = isLazy;
-    }
+const BindableToken_1 = require("./BindableToken");
+class SingleAliasToken extends BindableToken_1.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();
-    }
 }
 exports.SingleAliasToken = SingleAliasToken;
 const toSingleAlias = (token) => new SingleAliasToken(token);

package/cjm/token/SingleToken.js

@@ -1,61 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.SingleToken = void 0;
-const InjectionToken_1 = require("./InjectionToken");
-class SingleToken extends InjectionToken_1.InjectionToken {
-    token;
-    _getArgsFn;
-    _isLazy;
-    constructor(token, { getArgsFn = InjectionToken_1.forwardArgs, isLazy = false, tags = [], } = {}) {
-        super(tags);
-        this.token = token;
-        this._getArgsFn = getArgsFn;
-        this._isLazy = isLazy;
-    }
+const BindableToken_1 = require("./BindableToken");
+class SingleToken extends BindableToken_1.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();
-    }
 }
 exports.SingleToken = SingleToken;