@cqrs-ddd/pipeline-feature-flags 0.0.0-stage → 0.5.0

package/README.md

@@ -1,3 +1,36 @@
-# Temporary Holding Version
+# @cqrs-ddd/pipeline-feature-flags
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Feature flags for `@cqrs-ddd/pipeline` through [OpenFeature](https://openfeature.dev): an
+operation runs only while its boolean flag is on, with any OpenFeature provider
+(Unleash, Flagsmith, LaunchDarkly, a file). `createFeatureFlagClient()` registers the
+provider and resolves the client; `toHttpResponse()` from
+`@cqrs-ddd/pipeline-feature-flags/http` turns a disabled feature into a 403, or a 404 that
+hides it.
+
+**Documentation:** [guide](https://aristoteliss.github.io/ddd-cqrs/packages/pipeline-feature-flags/) · [API reference](https://aristoteliss.github.io/ddd-cqrs/api/cqrs-ddd/pipeline-feature-flags/) · [all packages](https://aristoteliss.github.io/ddd-cqrs/)
+
+## Installation
+
+```bash
+pnpm add @cqrs-ddd/pipeline-feature-flags @cqrs-ddd/pipeline @openfeature/server-sdk
+```
+
+Requires Node.js 22.12 or later. Published as an ES module; a CommonJS application loads
+it with `require()`.
+
+## Example
+
+```ts
+const client = await createFeatureFlagClient({ provider: new UnleashProvider(config) });
+const pipeline = createPipeline({ behaviors: [new FeatureFlagBehavior(client)] });
+
+export const checkout = pipeline.wrap(
+  { name: 'checkout', kind: 'command' },
+  featureFlag({ flag: 'new-checkout' }),
+)(async (cart: Cart) => orders.place(cart));
+```
+
+## License
+
+Dual-licensed under **AGPLv3** and a **Commercial License**. See `LICENSE` and
+`COMMERCIAL_LICENSE.txt`.

package/dist/errors/feature-disabled.error.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Thrown by {@link FeatureFlagBehavior} when a handler is gated behind a flag
+ * that resolves to disabled and no `fallback` was configured.
+ *
+ * Over HTTP, register {@link FeatureDisabledFilter}: it answers `403 Forbidden`
+ * with the flag, or a plain `404 Not Found` to hide the feature.
+ */
+export declare class FeatureDisabledError extends Error {
+    /** The flag key that gated the request. */
+    readonly flag: string;
+    /** The request that was blocked, e.g. `CreateUserCommand`. */
+    readonly requestName: string;
+    constructor(flag: string, requestName: string);
+}
+//# sourceMappingURL=feature-disabled.error.d.ts.map

package/dist/errors/feature-disabled.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-disabled.error.d.ts","sourceRoot":"","sources":["../../src/errors/feature-disabled.error.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAC7C,2CAA2C;IAC3C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,8DAA8D;IAC9D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAE7B,YAAY,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAK5C;CACF"}

package/dist/errors/feature-disabled.error.js

@@ -0,0 +1,21 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/**
+ * Thrown by {@link FeatureFlagBehavior} when a handler is gated behind a flag
+ * that resolves to disabled and no `fallback` was configured.
+ *
+ * Over HTTP, register {@link FeatureDisabledFilter}: it answers `403 Forbidden`
+ * with the flag, or a plain `404 Not Found` to hide the feature.
+ */
+export class FeatureDisabledError extends Error {
+    /** The flag key that gated the request. */
+    flag;
+    /** The request that was blocked, e.g. `CreateUserCommand`. */
+    requestName;
+    constructor(flag, requestName) {
+        super(`Feature "${flag}" is disabled for ${requestName}`);
+        this.name = 'FeatureDisabledError';
+        this.flag = flag;
+        this.requestName = requestName;
+    }
+}
+//# sourceMappingURL=feature-disabled.error.js.map

package/dist/errors/feature-disabled.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-disabled.error.js","sourceRoot":"","sources":["../../src/errors/feature-disabled.error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE;;;;;;GAMG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IAC7C,2CAA2C;IAClC,IAAI,CAAS;IACtB,8DAA8D;IACrD,WAAW,CAAS;IAE7B,YAAY,IAAY,EAAE,WAAmB;QAC3C,KAAK,CAAC,YAAY,IAAI,qBAAqB,WAAW,EAAE,CAAC,CAAC;QAC1D,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;CACF"}

package/dist/errors/feature-flag-evaluation.error.d.ts

@@ -0,0 +1,17 @@
+/** Raised when feature evaluation is configured to surface provider failures. */
+export declare class FeatureFlagEvaluationError extends Error {
+    readonly flag: string;
+    readonly requestName: string;
+    readonly errorCode?: string | undefined;
+    readonly providerMessage?: string | undefined;
+    readonly name = "FeatureFlagEvaluationError";
+    constructor(flag: string, requestName: string, errorCode?: string | undefined, providerMessage?: string | undefined, 
+    /**
+     * The provider error, when one was thrown. It becomes the error's `cause`,
+     * which keeps its stack and any provider-specific fields.
+     */
+    options?: {
+        cause?: unknown;
+    });
+}
+//# sourceMappingURL=feature-flag-evaluation.error.d.ts.map

package/dist/errors/feature-flag-evaluation.error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag-evaluation.error.d.ts","sourceRoot":"","sources":["../../src/errors/feature-flag-evaluation.error.ts"],"names":[],"mappings":"AAEA,iFAAiF;AACjF,qBAAa,0BAA2B,SAAQ,KAAK;aAIjC,IAAI,EAAE,MAAM;aACZ,WAAW,EAAE,MAAM;aACnB,SAAS,CAAC,EAAE,MAAM;aAClB,eAAe,CAAC,EAAE,MAAM;IAN1C,SAAkB,IAAI,gCAAgC;IAEtD,YACkB,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,YAAA,EAClB,eAAe,CAAC,EAAE,MAAM,YAAA;IACxC;;;OAGG;IACH,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,EAQ9B;CACF"}

package/dist/errors/feature-flag-evaluation.error.js

@@ -0,0 +1,24 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+/** Raised when feature evaluation is configured to surface provider failures. */
+export class FeatureFlagEvaluationError extends Error {
+    flag;
+    requestName;
+    errorCode;
+    providerMessage;
+    name = 'FeatureFlagEvaluationError';
+    constructor(flag, requestName, errorCode, providerMessage, 
+    /**
+     * The provider error, when one was thrown. It becomes the error's `cause`,
+     * which keeps its stack and any provider-specific fields.
+     */
+    options) {
+        super(`Feature flag "${flag}" could not be evaluated for ${requestName}` +
+            (errorCode ? ` (${errorCode})` : '') +
+            (providerMessage ? `: ${providerMessage}` : ''), options?.cause !== undefined ? { cause: options.cause } : undefined);
+        this.flag = flag;
+        this.requestName = requestName;
+        this.errorCode = errorCode;
+        this.providerMessage = providerMessage;
+    }
+}
+//# sourceMappingURL=feature-flag-evaluation.error.js.map

package/dist/errors/feature-flag-evaluation.error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag-evaluation.error.js","sourceRoot":"","sources":["../../src/errors/feature-flag-evaluation.error.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAEtE,iFAAiF;AACjF,MAAM,OAAO,0BAA2B,SAAQ,KAAK;IAIjC,IAAI;IACJ,WAAW;IACX,SAAS;IACT,eAAe;IANf,IAAI,GAAG,4BAA4B,CAAC;IAEtD,YACkB,IAAY,EACZ,WAAmB,EACnB,SAAkB,EAClB,eAAwB;IACxC;;;OAGG;IACH,OAA6B;QAE7B,KAAK,CACH,iBAAiB,IAAI,gCAAgC,WAAW,EAAE;YAChE,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,SAAS,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YACpC,CAAC,eAAe,CAAC,CAAC,CAAC,KAAK,eAAe,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EACjD,OAAO,EAAE,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CACpE,CAAC;oBAfc,IAAI;2BACJ,WAAW;yBACX,SAAS;+BACT,eAAe;IAajC,CAAC;CACF"}

package/dist/feature-flag.behavior.d.ts

@@ -0,0 +1,148 @@
+import { type IPipelineBehavior, type IPipelineBehaviorContract, type IPipelineBehaviorOptionsResolver, type IPipelineContext, type NextDelegate, PIPELINE_BEHAVIOR_CONTRACT, type PipelineItemToken, type PipelineLogger } from '@cqrs-ddd/pipeline';
+import type { Client, EvaluationContext } from '@openfeature/server-sdk';
+import type { FeatureFlagBehaviorOptions, FeatureFlagDecision, TargetingKeyFactory } from './interfaces/feature-flags-options.interface.js';
+/**
+ * Unique symbol key set on `context.items` recording the final boolean gate
+ * decision (`true` means the handler was allowed to execute).
+ *
+ * Use this when only the final gate result is needed. For provider variant,
+ * reason, error metadata, and targeting identity use
+ * {@link FEATURE_FLAG_DECISION_ITEM}.
+ *
+ * @example
+ * ```ts
+ * const isEnabled = context.items.get(FEATURE_FLAG_ITEM) === true;
+ * ```
+ */
+export declare const FEATURE_FLAG_ITEM: unique symbol;
+/**
+ * Typed token for {@link FEATURE_FLAG_ITEM}: the feature flag gate decision. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export declare const FEATURE_FLAG_ITEM_TOKEN: PipelineItemToken<boolean>;
+/**
+ * Unique symbol key set on `context.items` recording the evaluated feature flag
+ * key string.
+ *
+ * @example
+ * ```ts
+ * const flagKey = context.items.get(FEATURE_FLAG_KEY_ITEM) as string | undefined;
+ * ```
+ */
+export declare const FEATURE_FLAG_KEY_ITEM: unique symbol;
+/**
+ * Typed token for {@link FEATURE_FLAG_KEY_ITEM}: the evaluated feature flag key. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export declare const FEATURE_FLAG_KEY_ITEM_TOKEN: PipelineItemToken<string>;
+/**
+ * Unique symbol key set on `context.items` with the full
+ * {@link FeatureFlagDecision}: raw boolean value, final enabled decision,
+ * provider variant/reason/error metadata, and targeting key when available.
+ *
+ * This lets audit/logging/telemetry behaviors inspect the exact decision without
+ * evaluating the flag a second time.
+ *
+ * @example
+ * ```ts
+ * const decision = context.items.get(FEATURE_FLAG_DECISION_ITEM) as
+ *   | FeatureFlagDecision
+ *   | undefined;
+ *
+ * if (decision?.variant === 'treatment-a') {
+ *   // enrich telemetry/audit metadata
+ * }
+ * ```
+ */
+export declare const FEATURE_FLAG_DECISION_ITEM: unique symbol;
+/**
+ * Typed token for {@link FEATURE_FLAG_DECISION_ITEM}: the feature flag decision. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export declare const FEATURE_FLAG_DECISION_ITEM_TOKEN: PipelineItemToken<FeatureFlagDecision>;
+/**
+ * Pipeline behavior that gates a handler behind an OpenFeature boolean flag.
+ *
+ * Provider-agnostic by design: it talks only to the OpenFeature {@link Client},
+ * so the backing provider (Unleash, Flagsmith, LaunchDarkly, a local file, …) is
+ * a drop-in swap of the client passed to the constructor (see `createFeatureFlagClient`).
+ * OpenFeature remains the feature-flag abstraction; this behavior adds only the
+ * pipeline-specific semantics that an application repeatedly needs.
+ *
+ * Resolution of the effective options for a handler:
+ * 1. Application-wide defaults, the second constructor argument.
+ * 2. Per-operation options from the `featureFlag({ ... })` entry,
+ *    shallow-merged on top of the defaults (handler keys win).
+ *
+ * Behavior:
+ * - No `flag` configured → transparent pass-through.
+ * - Flag evaluates `true` and optional `allowedVariants` accepts the provider
+ *   variant → run the handler.
+ * - Final gate disabled → return `fallback(context)` when provided, otherwise
+ *   throw {@link FeatureDisabledError}.
+ * - Provider evaluation error → use the configured `defaultValue` by default,
+ *   or throw {@link FeatureFlagEvaluationError} with `errorPolicy: 'throw'`.
+ *
+ * ### Stable rollout identity
+ *
+ * Percentage/gradual rollouts should use a stable user/account/device/tenant
+ * identity through `targetingKeyFactory`.
+ *
+ * @example Simple gate
+ * ```ts
+ * class NewCheckoutHandler {
+ *   @pipeline.wrap({ kind: 'command' }, [FeatureFlagBehavior, { flag: 'new-checkout' }])
+ *   async handle(command: NewCheckoutCommand) {}
+ * }
+ * ```
+ *
+ * @example Sticky user rollout with graceful fallback
+ * ```ts
+ * class GetRecommendationsHandler {
+ *   @pipeline.wrap({ kind: 'query' }, [FeatureFlagBehavior, {
+ *     flag: 'recommendations-v2',
+ *     targetingKeyFactory: (ctx) =>
+ *       ctx.items.get('currentUserId') as string | undefined,
+ *     fallback: () => [],
+ *   }])
+ *   async handle(query: GetRecommendationsQuery) {}
+ * }
+ * ```
+ *
+ * @example Run only for one experiment variant
+ * ```ts
+ * @pipeline.wrap({ kind: 'command' }, [FeatureFlagBehavior, {
+ *   flag: 'checkout-experiment',
+ *   allowedVariants: ['treatment-a'],
+ * }])
+ * ```
+ *
+ * @example Make flag-provider failure visible instead of using the default
+ * ```ts
+ * @pipeline.wrap({ kind: 'command' }, [FeatureFlagBehavior, {
+ *   flag: 'critical-kill-switch',
+ *   errorPolicy: 'throw',
+ * }])
+ * ```
+ */
+export declare class FeatureFlagBehavior implements IPipelineBehavior, IPipelineBehaviorOptionsResolver<FeatureFlagBehaviorOptions> {
+    private readonly client;
+    private readonly moduleContext?;
+    private readonly moduleTargetingKeyFactory?;
+    static readonly [PIPELINE_BEHAVIOR_CONTRACT]: IPipelineBehaviorContract;
+    private readonly logger;
+    private readonly defaults;
+    constructor(client: Client, defaults?: FeatureFlagBehaviorOptions, moduleContext?: EvaluationContext | undefined, logger?: PipelineLogger, moduleTargetingKeyFactory?: TargetingKeyFactory | undefined);
+    handle(context: IPipelineContext, next: NextDelegate): Promise<unknown>;
+    /**
+     * Resolves OpenFeature details without applying the handler's error policy.
+     *
+     * Provider failures are normalized into a decision plus a `failure`
+     * descriptor so the caller can publish telemetry/audit state before deciding
+     * whether to use the default value or throw.
+     */
+    private evaluate;
+    /** Shallow-merges pipeline-level options over the application defaults. */
+    resolveEffectiveOptions(options?: FeatureFlagBehaviorOptions): FeatureFlagBehaviorOptions;
+}
+//# sourceMappingURL=feature-flag.behavior.d.ts.map

package/dist/feature-flag.behavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag.behavior.d.ts","sourceRoot":"","sources":["../src/feature-flag.behavior.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,iBAAiB,EACtB,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,EACrC,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,0BAA0B,EAG1B,KAAK,iBAAiB,EACtB,KAAK,cAAc,EAEpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,MAAM,EAAE,iBAAiB,EAAE,MAAM,yBAAyB,CAAC;AAIzE,OAAO,KAAK,EACV,0BAA0B,EAC1B,mBAAmB,EACnB,mBAAmB,EACpB,MAAM,iDAAiD,CAAC;AAEzD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,iBAAiB,eAA8B,CAAC;AAE7D;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAE,iBAAiB,CAAC,OAAO,CACM,CAAC;AAEtE;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,eAAkC,CAAC;AAErE;;;GAGG;AACH,eAAO,MAAM,2BAA2B,EAAE,iBAAiB,CAAC,MAAM,CACU,CAAC;AAE7E;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,0BAA0B,eAAuC,CAAC;AAE/E;;;GAGG;AACH,eAAO,MAAM,gCAAgC,EAAE,iBAAiB,CAAC,mBAAmB,CAIjF,CAAC;AAWJ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgEG;AACH,qBAAa,mBACX,YACE,iBAAiB,EACjB,gCAAgC,CAAC,0BAA0B,CAAC;IAiD5D,OAAO,CAAC,QAAQ,CAAC,MAAM;IAEvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC;IAE/B,OAAO,CAAC,QAAQ,CAAC,yBAAyB,CAAC;IAnD7C,MAAM,CAAC,QAAQ,CAAC,CAAC,0BAA0B,CAAC,EAAE,yBAAyB,CAyCrE;IAEF,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAiB;IACxC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IAEtD,YACmB,MAAM,EAAE,MAAM,EAC/B,QAAQ,CAAC,EAAE,0BAA0B,EACpB,aAAa,CAAC,EAAE,iBAAiB,YAAA,EAClD,MAAM,CAAC,EAAE,cAAc,EACN,yBAAyB,CAAC,EAAE,mBAAmB,YAAA,EASjE;IAEK,MAAM,CACV,OAAO,EAAE,gBAAgB,EACzB,IAAI,EAAE,YAAY,GACjB,OAAO,CAAC,OAAO,CAAC,CA2ElB;IAED;;;;;;OAMG;YACW,QAAQ;IA2CtB,2EAA2E;IAC3E,uBAAuB,CACrB,OAAO,CAAC,EAAE,0BAA0B,GACnC,0BAA0B,CAE5B;CACF"}

package/dist/feature-flag.behavior.js

@@ -0,0 +1,261 @@
+/* Copyright (C) 2026-present Aristotelis — see repository license. */
+import { createPipelineItem, PIPELINE_BEHAVIOR_CONTRACT, setPipelineItem, } from '@cqrs-ddd/pipeline';
+import { FeatureDisabledError } from './errors/feature-disabled.error.js';
+import { FeatureFlagEvaluationError } from './errors/feature-flag-evaluation.error.js';
+import { buildEvaluationContext } from './helpers/evaluation-context.js';
+/**
+ * Unique symbol key set on `context.items` recording the final boolean gate
+ * decision (`true` means the handler was allowed to execute).
+ *
+ * Use this when only the final gate result is needed. For provider variant,
+ * reason, error metadata, and targeting identity use
+ * {@link FEATURE_FLAG_DECISION_ITEM}.
+ *
+ * @example
+ * ```ts
+ * const isEnabled = context.items.get(FEATURE_FLAG_ITEM) === true;
+ * ```
+ */
+export const FEATURE_FLAG_ITEM = Symbol('FEATURE_FLAG_ITEM');
+/**
+ * Typed token for {@link FEATURE_FLAG_ITEM}: the feature flag gate decision. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export const FEATURE_FLAG_ITEM_TOKEN = createPipelineItem('FEATURE_FLAG_ITEM', FEATURE_FLAG_ITEM);
+/**
+ * Unique symbol key set on `context.items` recording the evaluated feature flag
+ * key string.
+ *
+ * @example
+ * ```ts
+ * const flagKey = context.items.get(FEATURE_FLAG_KEY_ITEM) as string | undefined;
+ * ```
+ */
+export const FEATURE_FLAG_KEY_ITEM = Symbol('FEATURE_FLAG_KEY_ITEM');
+/**
+ * Typed token for {@link FEATURE_FLAG_KEY_ITEM}: the evaluated feature flag key. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export const FEATURE_FLAG_KEY_ITEM_TOKEN = createPipelineItem('FEATURE_FLAG_KEY_ITEM', FEATURE_FLAG_KEY_ITEM);
+/**
+ * Unique symbol key set on `context.items` with the full
+ * {@link FeatureFlagDecision}: raw boolean value, final enabled decision,
+ * provider variant/reason/error metadata, and targeting key when available.
+ *
+ * This lets audit/logging/telemetry behaviors inspect the exact decision without
+ * evaluating the flag a second time.
+ *
+ * @example
+ * ```ts
+ * const decision = context.items.get(FEATURE_FLAG_DECISION_ITEM) as
+ *   | FeatureFlagDecision
+ *   | undefined;
+ *
+ * if (decision?.variant === 'treatment-a') {
+ *   // enrich telemetry/audit metadata
+ * }
+ * ```
+ */
+export const FEATURE_FLAG_DECISION_ITEM = Symbol('FEATURE_FLAG_DECISION_ITEM');
+/**
+ * Typed token for {@link FEATURE_FLAG_DECISION_ITEM}: the feature flag decision. Reads and writes the same
+ * `context.items` entry through `getPipelineItem` / `requirePipelineItem`.
+ */
+export const FEATURE_FLAG_DECISION_ITEM_TOKEN = createPipelineItem('FEATURE_FLAG_DECISION_ITEM', FEATURE_FLAG_DECISION_ITEM);
+/**
+ * Pipeline behavior that gates a handler behind an OpenFeature boolean flag.
+ *
+ * Provider-agnostic by design: it talks only to the OpenFeature {@link Client},
+ * so the backing provider (Unleash, Flagsmith, LaunchDarkly, a local file, …) is
+ * a drop-in swap of the client passed to the constructor (see `createFeatureFlagClient`).
+ * OpenFeature remains the feature-flag abstraction; this behavior adds only the
+ * pipeline-specific semantics that an application repeatedly needs.
+ *
+ * Resolution of the effective options for a handler:
+ * 1. Application-wide defaults, the second constructor argument.
+ * 2. Per-operation options from the `featureFlag({ ... })` entry,
+ *    shallow-merged on top of the defaults (handler keys win).
+ *
+ * Behavior:
+ * - No `flag` configured → transparent pass-through.
+ * - Flag evaluates `true` and optional `allowedVariants` accepts the provider
+ *   variant → run the handler.
+ * - Final gate disabled → return `fallback(context)` when provided, otherwise
+ *   throw {@link FeatureDisabledError}.
+ * - Provider evaluation error → use the configured `defaultValue` by default,
+ *   or throw {@link FeatureFlagEvaluationError} with `errorPolicy: 'throw'`.
+ *
+ * ### Stable rollout identity
+ *
+ * Percentage/gradual rollouts should use a stable user/account/device/tenant
+ * identity through `targetingKeyFactory`.
+ *
+ * @example Simple gate
+ * ```ts
+ * class NewCheckoutHandler {
+ *   @pipeline.wrap({ kind: 'command' }, [FeatureFlagBehavior, { flag: 'new-checkout' }])
+ *   async handle(command: NewCheckoutCommand) {}
+ * }
+ * ```
+ *
+ * @example Sticky user rollout with graceful fallback
+ * ```ts
+ * class GetRecommendationsHandler {
+ *   @pipeline.wrap({ kind: 'query' }, [FeatureFlagBehavior, {
+ *     flag: 'recommendations-v2',
+ *     targetingKeyFactory: (ctx) =>
+ *       ctx.items.get('currentUserId') as string | undefined,
+ *     fallback: () => [],
+ *   }])
+ *   async handle(query: GetRecommendationsQuery) {}
+ * }
+ * ```
+ *
+ * @example Run only for one experiment variant
+ * ```ts
+ * @pipeline.wrap({ kind: 'command' }, [FeatureFlagBehavior, {
+ *   flag: 'checkout-experiment',
+ *   allowedVariants: ['treatment-a'],
+ * }])
+ * ```
+ *
+ * @example Make flag-provider failure visible instead of using the default
+ * ```ts
+ * @pipeline.wrap({ kind: 'command' }, [FeatureFlagBehavior, {
+ *   flag: 'critical-kill-switch',
+ *   errorPolicy: 'throw',
+ * }])
+ * ```
+ */
+export class FeatureFlagBehavior {
+    client;
+    moduleContext;
+    moduleTargetingKeyFactory;
+    static [PIPELINE_BEHAVIOR_CONTRACT] = {
+        validate: (context) => {
+            const options = context.effectiveOptions;
+            if (options?.flag !== undefined &&
+                (typeof options.flag !== 'string' || options.flag.trim() === '')) {
+                return [
+                    {
+                        handlerName: context.handlerName,
+                        behaviorName: FeatureFlagBehavior.name,
+                        message: 'FeatureFlagBehavior `flag` option must be a non-empty string',
+                        fix: 'Provide a valid string flag name in options or omit options for pass-through.',
+                    },
+                ];
+            }
+            if ((context.declarationSource === 'handler' ||
+                context.declarationSource === 'both') &&
+                options?.flag === undefined) {
+                return [
+                    {
+                        handlerName: context.handlerName,
+                        behaviorName: FeatureFlagBehavior.name,
+                        message: 'Explicit FeatureFlagBehavior intent requires a non-empty `flag` name',
+                        fix: 'Provide flag in the featureFlag({ flag: "flag-name" }) entry.',
+                    },
+                ];
+            }
+            return undefined;
+        },
+    };
+    logger;
+    defaults;
+    constructor(client, defaults, moduleContext, logger, moduleTargetingKeyFactory) {
+        this.client = client;
+        this.moduleContext = moduleContext;
+        this.moduleTargetingKeyFactory = moduleTargetingKeyFactory;
+        if (typeof client?.getBooleanDetails !== 'function') {
+            throw new TypeError('FeatureFlagBehavior requires an OpenFeature client, such as the one createFeatureFlagClient() resolves.');
+        }
+        this.defaults = defaults ?? {};
+        this.logger = logger ?? console;
+    }
+    async handle(context, next) {
+        const options = this.resolveEffectiveOptions(context.getBehaviorOptions(FeatureFlagBehavior));
+        if (!options.flag)
+            return next();
+        const targetingKeyFactory = options.targetingKeyFactory ?? this.moduleTargetingKeyFactory;
+        const evaluationContext = buildEvaluationContext(context, this.moduleContext, options.context, targetingKeyFactory);
+        const defaultValue = options.defaultValue ?? false;
+        const { details, failure } = await this.evaluate(options.flag, defaultValue, evaluationContext);
+        // A boolean true is necessary but, when allowedVariants is configured, not
+        // sufficient: the provider must also resolve one of the selected variants.
+        const variantAllowed = !options.allowedVariants?.length ||
+            (!!details.variant && options.allowedVariants.includes(details.variant));
+        const enabled = details.value && variantAllowed;
+        const decision = {
+            flagKey: options.flag,
+            value: details.value,
+            enabled,
+            ...(details.variant ? { variant: details.variant } : {}),
+            ...(details.reason ? { reason: details.reason } : {}),
+            ...(details.errorCode !== undefined
+                ? { errorCode: String(details.errorCode) }
+                : {}),
+            ...(details.errorMessage ? { errorMessage: details.errorMessage } : {}),
+            ...(evaluationContext.targetingKey
+                ? { targetingKey: evaluationContext.targetingKey }
+                : {}),
+        };
+        // Publish the decision before applying the throw policy so outer audit and
+        // telemetry behaviors can observe provider failures.
+        setPipelineItem(context, FEATURE_FLAG_KEY_ITEM_TOKEN, options.flag);
+        setPipelineItem(context, FEATURE_FLAG_ITEM_TOKEN, enabled);
+        setPipelineItem(context, FEATURE_FLAG_DECISION_ITEM_TOKEN, decision);
+        if (failure && (options.errorPolicy ?? 'use-default') === 'throw') {
+            throw new FeatureFlagEvaluationError(options.flag, context.requestName, failure.errorCode, failure.message, { cause: failure.cause });
+        }
+        const variantSuffix = details.variant ? ` variant=${details.variant}` : '';
+        const reasonSuffix = details.reason ? ` reason=${details.reason}` : '';
+        const state = enabled ? 'enabled' : 'disabled';
+        this.logger.debug?.(`Feature "${options.flag}" ${state} for ${context.requestName}${variantSuffix}${reasonSuffix}`, FeatureFlagBehavior.name);
+        if (enabled)
+            return next();
+        if (options.fallback)
+            return options.fallback(context);
+        throw new FeatureDisabledError(options.flag, context.requestName);
+    }
+    /**
+     * Resolves OpenFeature details without applying the handler's error policy.
+     *
+     * Provider failures are normalized into a decision plus a `failure`
+     * descriptor so the caller can publish telemetry/audit state before deciding
+     * whether to use the default value or throw.
+     */
+    async evaluate(flag, defaultValue, evaluationContext) {
+        let details;
+        try {
+            details = (await this.client.getBooleanDetails(flag, defaultValue, evaluationContext));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                details: {
+                    value: defaultValue,
+                    reason: 'ERROR',
+                    errorMessage: message,
+                },
+                failure: { message, cause: error },
+            };
+        }
+        // A provider that reports an error in its details rather than throwing is
+        // the same outcome from the application's point of view.
+        if (details.errorCode !== undefined) {
+            return {
+                details,
+                failure: {
+                    message: details.errorMessage ?? String(details.errorCode),
+                    errorCode: String(details.errorCode),
+                },
+            };
+        }
+        return { details };
+    }
+    /** Shallow-merges pipeline-level options over the application defaults. */
+    resolveEffectiveOptions(options) {
+        return options ? { ...this.defaults, ...options } : this.defaults;
+    }
+}
+//# sourceMappingURL=feature-flag.behavior.js.map

package/dist/feature-flag.behavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag.behavior.js","sourceRoot":"","sources":["../src/feature-flag.behavior.ts"],"names":[],"mappings":"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"}

package/dist/helpers/build-attributes.d.ts

@@ -0,0 +1,48 @@
+import { type IPipelineContext } from '@cqrs-ddd/pipeline';
+/**
+ * The feature-flag decision of one execution as flat attributes, named after
+ * the OpenTelemetry feature-flag conventions: `feature_flag.key` and
+ * `feature_flag.enabled`, plus `feature_flag.variant` and `feature_flag.reason`
+ * when the provider reported them, and `feature_flag.error_code` only when
+ * evaluation failed. `{}` when `FeatureFlagBehavior` did not run. The targeting
+ * key and the provider's error message are never included.
+ *
+ * The result is plain data and needs no telemetry package: put it on a span, a
+ * log line, an audit record or a metric label (bounded values only).
+ *
+ * @param context - The pipeline execution, read after `FeatureFlagBehavior` ran.
+ * @returns The attributes; empty when the behavior did not run.
+ *
+ * @example Span attributes
+ * With `AttributesBehavior` of `@cqrs-ddd/pipeline-opentelemetry`:
+ * ```ts
+ * createPipeline({
+ *   globalBehaviors: {
+ *     before: [TraceBehavior, [AttributesBehavior, { factories: [buildFeatureFlagAttributes] }]],
+ *   },
+ * });
+ * ```
+ *
+ * @example Audit metadata
+ * `audit()` is declared outside `featureFlag()`, so the record is built after its decision:
+ * ```ts
+ * @pipeline.wrap(
+ *   { kind: 'command' },
+ *   audit({ action: 'order.create', metadata: buildFeatureFlagAttributes }),
+ *   featureFlag({ flag: 'checkout' }),
+ * )
+ * ```
+ *
+ * @example A log line from a custom behavior, after the chain ran
+ * ```ts
+ * async handle(context: IPipelineContext, next: NextDelegate) {
+ *   try {
+ *     return await next();
+ *   } finally {
+ *     this.logger.log({ request: context.requestName, ...buildFeatureFlagAttributes(context) });
+ *   }
+ * }
+ * ```
+ */
+export declare function buildFeatureFlagAttributes(context: IPipelineContext): Record<string, string | boolean>;
+//# sourceMappingURL=build-attributes.d.ts.map

package/dist/helpers/build-attributes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-attributes.d.ts","sourceRoot":"","sources":["../../src/helpers/build-attributes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,0BAA0B,CACxC,OAAO,EAAE,gBAAgB,GACxB,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAYlC"}