ts-ioc-container 72.3.0 → 72.3.1

package/README.md

@@ -52,6 +52,7 @@ 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)
@@ -2796,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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ts-ioc-container",
-  "version": "72.3.0",
+  "version": "72.3.1",
   "description": "Fast, lightweight TypeScript dependency injection container with a clean API, scoped lifecycles, decorators, tokens, hooks, lazy injection, customizable providers, and no global container objects.",
   "publishConfig": {
     "access": "public",
@@ -90,7 +90,7 @@
     "build:cjm": "node ../scripts/build.mjs cjm",
     "build:esm": "node ../scripts/build.mjs esm",
     "build:types": "node ../scripts/build.mjs types",
-    "generate:docs": "../scripts/generate-readme/generate-readme.ts && git add README.md",
+    "generate:docs": "../scripts/generate-readme/generate-readme.ts",
     "build": "pnpm run build:cjm && pnpm run build:esm && pnpm run build:types",
     "test": "vitest run",
     "test:spec": "vitest run __tests__/specs",