@nestarc/feature-flag 0.3.0 → 0.4.0

package/README.md

@@ -12,15 +12,17 @@ DB-backed feature flags for NestJS + Prisma + PostgreSQL -- attribute-targeted o
 
 - **Database-backed** -- flags stored in PostgreSQL via Prisma, no external service required
 - **Attribute-targeted overrides** -- exact-match targeting for tenants, users, environments, plans, regions, or custom dimensions
-- **Percentage rollouts** -- deterministic hashing (murmurhash3) for consistent per-user bucketing
+- **Percentage rollouts** -- deterministic hashing (murmurhash3) with explicit `targetingKey` / `bucketBy`
 - **Guard decorator** -- `@FeatureFlag()` automatically gates routes and controllers
 - **Bypass decorator** -- `@BypassFeatureFlag()` exempts health checks and public endpoints
-- **Programmatic evaluation** -- `isEnabled()` and `evaluateAll()` for service-layer logic
+- **Programmatic evaluation** -- `isEnabled()`, `evaluateBoolean()`, and `evaluateAll()` for service-layer logic
+- **Type-safe registry helpers** -- define flag keys, defaults, rollout bucket keys, exposure tracking, and lifecycle metadata in code
 - **Built-in caching** -- configurable TTL with manual invalidation; Redis Pub/Sub for multi-instance
 - **Pluggable persistence** -- `FeatureFlagRepository` interface for custom backends (Prisma default)
 - **Pluggable tenancy** -- `TenantContextProvider` interface for custom tenant resolution
 - **Admin REST API** -- opt-in `FeatureFlagAdminModule` with guard injection and proper error responses
 - **Event system** -- optional integration with `@nestjs/event-emitter` for audit and observability
+- **OpenFeature adapter** -- optional boolean-only provider at `@nestarc/feature-flag/openfeature`
 - **Testing utilities** -- drop-in `TestFeatureFlagModule` for unit and integration tests
 
 ## Installation
@@ -43,6 +45,9 @@ npm install @nestjs/event-emitter
 
 # Required only if you use RedisCacheAdapter
 npm install ioredis
+
+# Required only if you use the OpenFeature adapter with the SDK
+npm install @openfeature/server-sdk
 ```
 
 ## Redis Cache (Multi-Instance)
@@ -279,6 +284,14 @@ getPremiumContent() { ... }
 
 When the flag is disabled, the guard responds with the given `statusCode` (default `403`) and optional `fallback` body.
 
+Use `defaultValue` when a route should choose an invocation-specific fallback if a flag is missing or evaluation fails:
+
+```typescript
+@FeatureFlag('OPTIONAL_PREVIEW', { defaultValue: true })
+@Get('preview')
+getPreview() { ... }
+```
+
 ### Bypassing the guard
 
 Use `@BypassFeatureFlag()` on methods that should always be accessible, even when a class-level flag is applied:
@@ -348,6 +361,78 @@ Passing `null` explicitly clears that dimension, suppressing any ambient value f
 const globalResult = await this.flags.isEnabled('MY_FLAG', { userId: null });
 ```
 
+### Detailed boolean evaluation
+
+Use `evaluateBoolean()` when you need to explain why a flag resolved to a value:
+
+```typescript
+const details = await this.flags.evaluateBoolean(
+  'NEW_CHECKOUT',
+  { targetingKey: 'tenant-1', tenantId: 'tenant-1' },
+  { defaultValue: false, trackExposure: true },
+);
+
+console.log(details);
+// {
+//   flagKey: 'NEW_CHECKOUT',
+//   value: true,
+//   result: true,
+//   source: 'percentage',
+//   reason: 'PERCENTAGE_MATCH',
+//   defaultUsed: false,
+//   bucket: 17,
+//   targetingKey: 'tenant-1',
+//   evaluationTimeMs: 1
+// }
+```
+
+Missing flags and evaluation errors return the selected default instead of throwing. Default priority is:
+
+1. Invocation `defaultValue`
+2. Registry `defaultValue`
+3. Module `defaultOnMissing`
+4. `false`
+
+### Type-safe flag registry
+
+```typescript
+import { defineFlags, createFeatureFlagClient } from '@nestarc/feature-flag';
+
+export const flags = defineFlags({
+  NEW_CHECKOUT: {
+    defaultValue: false,
+    bucketBy: 'tenantId',
+    trackExposure: true,
+    owner: 'payments',
+    tags: ['checkout'],
+    staleAt: '2026-09-01',
+    expiresAt: '2026-12-01',
+  },
+});
+
+const flagClient = createFeatureFlagClient(featureFlagService, flags);
+const enabled = await flagClient.isEnabled('NEW_CHECKOUT', { tenantId: 'tenant-1' });
+```
+
+You can also pass the registry to `FeatureFlagModule.forRoot({ flags })` so service-level fallback and `bucketBy` defaults apply to direct `FeatureFlagService` calls.
+
+### OpenFeature boolean adapter
+
+The optional adapter lives on a separate subpath and delegates boolean resolution to `FeatureFlagService`:
+
+```typescript
+import { createOpenFeatureBooleanProvider } from '@nestarc/feature-flag/openfeature';
+
+const provider = createOpenFeatureBooleanProvider(featureFlagService);
+const result = await provider.resolveBooleanEvaluation(
+  'NEW_CHECKOUT',
+  false,
+  { targetingKey: 'tenant-1', tenantId: 'tenant-1', plan: 'pro' },
+);
+```
+
+Only boolean evaluation is supported in v0.4.0. Variant flags and string/number/json remote config remain out of scope.
+
 ## Attribute Targeting
 
 Overrides match exact attributes. Every key/value in an override's `attributes` object must exist in the evaluation context attributes for the override to apply.
@@ -432,6 +517,7 @@ export class AppModule {}
 | Event constant                           | Event string                       | Payload type         |
 | ---------------------------------------- | ---------------------------------- | -------------------- |
 | `FeatureFlagEvents.EVALUATED`            | `feature-flag.evaluated`           | `FlagEvaluatedEvent` |
+| `FeatureFlagEvents.EXPOSED`              | `feature-flag.exposed`             | `FlagExposedEvent`   |
 | `FeatureFlagEvents.CREATED`              | `feature-flag.created`             | `FlagMutationEvent`  |
 | `FeatureFlagEvents.UPDATED`              | `feature-flag.updated`             | `FlagMutationEvent`  |
 | `FeatureFlagEvents.ARCHIVED`             | `feature-flag.archived`            | `FlagMutationEvent`  |
@@ -449,11 +535,13 @@ import { FeatureFlagEvents, FlagEvaluatedEvent } from '@nestarc/feature-flag';
 export class FlagAuditListener {
   @OnEvent(FeatureFlagEvents.EVALUATED)
   handleEvaluation(event: FlagEvaluatedEvent) {
-    console.log(`Flag ${event.flagKey} = ${event.result} (source: ${event.source})`);
+    console.log(`Flag ${event.flagKey} = ${event.result} (${event.reason})`);
   }
 }
 ```
 
+Exposure events are opt-in per call, registry entry, or flag metadata via `trackExposure`. They do not persist analytics; attach your own listener if you need sampling, batching, or storage.
+
 ## Testing
 
 Import `TestFeatureFlagModule` from the `/testing` subpath to stub flag values in tests without a database connection:
@@ -489,11 +577,29 @@ describe('DashboardController', () => {
 
 `TestFeatureFlagModule.register()` provides a global mock of `FeatureFlagService`:
 - `isEnabled(key)` returns the boolean you specified (defaulting to `false` for unregistered keys)
+- `evaluateBoolean(key)` returns `BooleanEvaluationDetails`
 - `evaluateAll()` returns the full flag map
 - `create()`, `update()`, `archive()`, `findByKey()`, `findAll()` return full `FeatureFlagWithOverrides` stub objects
 - `findByKey()` throws `NotFoundException` for unknown keys
 
-This is a **stateless boolean stub** -- write operations do not persist state across calls. For stateful test doubles, use your own mock implementation.
+For registry-based tests, use `registerRegistry()` and the injected controller:
+
+```typescript
+import {
+  TestFeatureFlagController,
+  TestFeatureFlagModule,
+} from '@nestarc/feature-flag/testing';
+
+const module = await Test.createTestingModule({
+  imports: [TestFeatureFlagModule.registerRegistry(flags)],
+}).compile();
+
+const testFlags = module.get(TestFeatureFlagController);
+testFlags.set('NEW_CHECKOUT', true);
+testFlags.reset();
+```
+
+The testing controller keeps state inside the compiled testing module. CRUD-style write methods on the mocked service still return stub objects and do not persist database rows.
 
 ## Evaluation Priority
 
@@ -503,10 +609,10 @@ When `isEnabled()` is called, flags are evaluated through the current cascade. T
 | -------- | ---------------------- | ------------------------------------------------------------------ |
 | 1        | **Archived**           | If the flag has `archivedAt` set, evaluation always returns `false` |
 | 2        | **Attribute override** | Best override whose attributes are all present in the evaluation context |
-| 3        | **Percentage rollout** | Deterministic hash of `flagKey + userId` (or `tenantId`) mod 100   |
+| 3        | **Percentage rollout** | Deterministic hash of `flagKey + targetingKey` mod 100             |
 | 4        | **Global default**     | The flag's `enabled` field                                         |
 
-Percentage rollout uses murmurhash3 for deterministic bucketing: the same user always gets the same result for a given flag, ensuring a consistent experience across requests.
+Percentage rollout uses murmurhash3 for deterministic bucketing. The targeting key is resolved in this order: explicit `context.targetingKey`, registry or metadata `bucketBy`, then the legacy `userId ?? tenantId` fallback.
 
 ## Configuration Reference
 
@@ -520,6 +626,7 @@ Percentage rollout uses murmurhash3 for deterministic bucketing: the same user a
 | `defaultOnMissing`  | `boolean`                         | `false`   | Value returned when a flag key does not exist in the database   |
 | `emitEvents`        | `boolean`                         | `false`   | Emit lifecycle events via `@nestjs/event-emitter`               |
 | `cacheAdapter`      | `CacheAdapter`                    | `MemoryCacheAdapter` | Pluggable cache backend (e.g. `RedisCacheAdapter`)  |
+| `flags`             | `FlagRegistry`                    | `undefined` | Optional typed registry for defaults, `bucketBy`, and exposure settings |
 
 ### FeatureFlagModuleRootOptions
 
@@ -587,6 +694,7 @@ export class AppModule {}
 | GET | `/feature-flags/:key` | Get a single flag | 404 not found |
 | PATCH | `/feature-flags/:key` | Update a flag | 404 not found, 400 invalid percentage |
 | DELETE | `/feature-flags/:key` | Archive a flag | 404 not found |
+| POST | `/feature-flags/:key/evaluate` | Evaluate a flag without mutating it | |
 | POST | `/feature-flags/:key/overrides` | Set an override | 404 flag not found |
 | DELETE | `/feature-flags/:key/overrides` | Remove an override | 404 flag not found |
 

package/dist/admin/feature-flag-admin.controller.d.ts

@@ -1,6 +1,7 @@
 import { FeatureFlagService } from '../services/feature-flag.service';
 import { FeatureFlagWithOverrides } from '../interfaces/feature-flag.interface';
-import { CreateFeatureFlagDto, RemoveOverrideDto, SetOverrideDto, UpdateFeatureFlagDto } from './feature-flag-admin.dto';
+import { BooleanEvaluationDetails } from '../interfaces/evaluation-details.interface';
+import { CreateFeatureFlagDto, EvaluateFeatureFlagDto, RemoveOverrideDto, SetOverrideDto, UpdateFeatureFlagDto } from './feature-flag-admin.dto';
 export declare class FeatureFlagAdminController {
     private readonly service;
     constructor(service: FeatureFlagService);
@@ -9,6 +10,7 @@ export declare class FeatureFlagAdminController {
     findByKey(key: string): Promise<FeatureFlagWithOverrides>;
     update(key: string, input: UpdateFeatureFlagDto): Promise<FeatureFlagWithOverrides>;
     archive(key: string): Promise<FeatureFlagWithOverrides>;
+    evaluate(key: string, input: EvaluateFeatureFlagDto): Promise<BooleanEvaluationDetails>;
     setOverride(key: string, input: SetOverrideDto): Promise<void>;
     removeOverride(key: string, input: RemoveOverrideDto): Promise<void>;
 }

package/dist/admin/feature-flag-admin.controller.js

@@ -35,6 +35,10 @@ let FeatureFlagAdminController = class FeatureFlagAdminController {
     archive(key) {
         return this.service.archive(key);
     }
+    evaluate(key, input) {
+        const { context, ...options } = input;
+        return this.service.evaluateBoolean(key, context, options);
+    }
     setOverride(key, input) {
         return this.service.setOverride(key, input);
     }
@@ -78,6 +82,14 @@ __decorate([
     __metadata("design:paramtypes", [String]),
     __metadata("design:returntype", Promise)
 ], FeatureFlagAdminController.prototype, "archive", null);
+__decorate([
+    (0, common_1.Post)(':key/evaluate'),
+    __param(0, (0, common_1.Param)('key')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, feature_flag_admin_dto_1.EvaluateFeatureFlagDto]),
+    __metadata("design:returntype", Promise)
+], FeatureFlagAdminController.prototype, "evaluate", null);
 __decorate([
     (0, common_1.Post)(':key/overrides'),
     __param(0, (0, common_1.Param)('key')),

package/dist/admin/feature-flag-admin.controller.js.map

@@ -1 +1 @@
-{"version":3,"file":"feature-flag-admin.controller.js","sourceRoot":"","sources":["../../src/admin/feature-flag-admin.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAUwB;AACxB,2EAAsE;AAEtE,qEAKkC;AAU3B,IAAM,0BAA0B,GAAhC,MAAM,0BAA0B;IACrC,YAA6B,OAA2B;QAA3B,YAAO,GAAP,OAAO,CAAoB;IAAG,CAAC;IAG5D,MAAM,CAAS,KAA2B;QACxC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAGD,OAAO;QACL,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAChC,CAAC;IAGD,SAAS,CAAe,GAAW;QACjC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IAGD,MAAM,CACU,GAAW,EACjB,KAA2B;QAEnC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAGD,OAAO,CAAe,GAAW;QAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAGD,WAAW,CAAe,GAAW,EAAU,KAAqB;QAClE,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAGD,cAAc,CAAe,GAAW,EAAU,KAAwB;QACxE,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;CACF,CAAA;AAxCY,gEAA0B;AAIrC;IADC,IAAA,aAAI,GAAE;IACC,WAAA,IAAA,aAAI,GAAE,CAAA;;qCAAQ,6CAAoB;;wDAEzC;AAGD;IADC,IAAA,YAAG,GAAE;;;;yDAGL;AAGD;IADC,IAAA,YAAG,EAAC,MAAM,CAAC;IACD,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;;;;2DAEtB;AAGD;IADC,IAAA,cAAK,EAAC,MAAM,CAAC;IAEX,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;IACZ,WAAA,IAAA,aAAI,GAAE,CAAA;;6CAAQ,6CAAoB;;wDAGpC;AAGD;IADC,IAAA,eAAM,EAAC,MAAM,CAAC;IACN,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;;;;yDAEpB;AAGD;IADC,IAAA,aAAI,EAAC,gBAAgB,CAAC;IACV,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;IAAe,WAAA,IAAA,aAAI,GAAE,CAAA;;6CAAQ,uCAAc;;6DAEnE;AAGD;IADC,IAAA,eAAM,EAAC,gBAAgB,CAAC;IACT,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;IAAe,WAAA,IAAA,aAAI,GAAE,CAAA;;6CAAQ,0CAAiB;;gEAEzE;qCAvCU,0BAA0B;IARtC,IAAA,mBAAU,GAAE;IACZ,IAAA,iBAAQ,EACP,IAAI,uBAAc,CAAC;QACjB,SAAS,EAAE,IAAI;QACf,oBAAoB,EAAE,IAAI;QAC1B,SAAS,EAAE,IAAI;KAChB,CAAC,CACH;qCAEuC,yCAAkB;GAD7C,0BAA0B,CAwCtC"}
+{"version":3,"file":"feature-flag-admin.controller.js","sourceRoot":"","sources":["../../src/admin/feature-flag-admin.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAUwB;AACxB,2EAAsE;AAGtE,qEAMkC;AAU3B,IAAM,0BAA0B,GAAhC,MAAM,0BAA0B;IACrC,YAA6B,OAA2B;QAA3B,YAAO,GAAP,OAAO,CAAoB;IAAG,CAAC;IAG5D,MAAM,CAAS,KAA2B;QACxC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IACpC,CAAC;IAGD,OAAO;QACL,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;IAChC,CAAC;IAGD,SAAS,CAAe,GAAW;QACjC,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACrC,CAAC;IAGD,MAAM,CACU,GAAW,EACjB,KAA2B;QAEnC,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACzC,CAAC;IAGD,OAAO,CAAe,GAAW;QAC/B,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACnC,CAAC;IAGD,QAAQ,CACQ,GAAW,EACjB,KAA6B;QAErC,MAAM,EAAE,OAAO,EAAE,GAAG,OAAO,EAAE,GAAG,KAAK,CAAC;QACtC,OAAO,IAAI,CAAC,OAAO,CAAC,eAAe,CAAC,GAAG,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;IAC7D,CAAC;IAGD,WAAW,CAAe,GAAW,EAAU,KAAqB;QAClE,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAGD,cAAc,CAAe,GAAW,EAAU,KAAwB;QACxE,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;CACF,CAAA;AAjDY,gEAA0B;AAIrC;IADC,IAAA,aAAI,GAAE;IACC,WAAA,IAAA,aAAI,GAAE,CAAA;;qCAAQ,6CAAoB;;wDAEzC;AAGD;IADC,IAAA,YAAG,GAAE;;;;yDAGL;AAGD;IADC,IAAA,YAAG,EAAC,MAAM,CAAC;IACD,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;;;;2DAEtB;AAGD;IADC,IAAA,cAAK,EAAC,MAAM,CAAC;IAEX,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;IACZ,WAAA,IAAA,aAAI,GAAE,CAAA;;6CAAQ,6CAAoB;;wDAGpC;AAGD;IADC,IAAA,eAAM,EAAC,MAAM,CAAC;IACN,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;;;;yDAEpB;AAGD;IADC,IAAA,aAAI,EAAC,eAAe,CAAC;IAEnB,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;IACZ,WAAA,IAAA,aAAI,GAAE,CAAA;;6CAAQ,+CAAsB;;0DAItC;AAGD;IADC,IAAA,aAAI,EAAC,gBAAgB,CAAC;IACV,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;IAAe,WAAA,IAAA,aAAI,GAAE,CAAA;;6CAAQ,uCAAc;;6DAEnE;AAGD;IADC,IAAA,eAAM,EAAC,gBAAgB,CAAC;IACT,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;IAAe,WAAA,IAAA,aAAI,GAAE,CAAA;;6CAAQ,0CAAiB;;gEAEzE;qCAhDU,0BAA0B;IARtC,IAAA,mBAAU,GAAE;IACZ,IAAA,iBAAQ,EACP,IAAI,uBAAc,CAAC;QACjB,SAAS,EAAE,IAAI;QACf,oBAAoB,EAAE,IAAI;QAC1B,SAAS,EAAE,IAAI;KAChB,CAAC,CACH;qCAEuC,yCAAkB;GAD7C,0BAA0B,CAiDtC"}

package/dist/admin/feature-flag-admin.dto.d.ts

@@ -1,3 +1,5 @@
+import { EvaluationContext } from '../interfaces/evaluation-context.interface';
+import { EvaluateBooleanOptions } from '../interfaces/evaluation-details.interface';
 import { TargetingAttributes } from '../interfaces/feature-flag.interface';
 export declare class CreateFeatureFlagDto {
     key: string;
@@ -20,3 +22,9 @@ export declare class SetOverrideDto {
 export declare class RemoveOverrideDto {
     attributes: TargetingAttributes;
 }
+export declare class EvaluateFeatureFlagDto implements EvaluateBooleanOptions {
+    context?: EvaluationContext;
+    defaultValue?: boolean;
+    trackExposure?: boolean;
+    includeContextInEvent?: boolean;
+}

package/dist/admin/feature-flag-admin.dto.js

@@ -9,7 +9,7 @@ var __metadata = (this && this.__metadata) || function (k, v) {
     if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RemoveOverrideDto = exports.SetOverrideDto = exports.UpdateFeatureFlagDto = exports.CreateFeatureFlagDto = void 0;
+exports.EvaluateFeatureFlagDto = exports.RemoveOverrideDto = exports.SetOverrideDto = exports.UpdateFeatureFlagDto = exports.CreateFeatureFlagDto = void 0;
 const class_validator_1 = require("class-validator");
 const targeting_attributes_validator_1 = require("./targeting-attributes.validator");
 class CreateFeatureFlagDto {
@@ -90,4 +90,27 @@ __decorate([
     (0, targeting_attributes_validator_1.IsTargetingAttributes)(),
     __metadata("design:type", Object)
 ], RemoveOverrideDto.prototype, "attributes", void 0);
+class EvaluateFeatureFlagDto {
+}
+exports.EvaluateFeatureFlagDto = EvaluateFeatureFlagDto;
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsObject)(),
+    __metadata("design:type", Object)
+], EvaluateFeatureFlagDto.prototype, "context", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], EvaluateFeatureFlagDto.prototype, "defaultValue", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], EvaluateFeatureFlagDto.prototype, "trackExposure", void 0);
+__decorate([
+    (0, class_validator_1.IsOptional)(),
+    (0, class_validator_1.IsBoolean)(),
+    __metadata("design:type", Boolean)
+], EvaluateFeatureFlagDto.prototype, "includeContextInEvent", void 0);
 //# sourceMappingURL=feature-flag-admin.dto.js.map

package/dist/admin/feature-flag-admin.dto.js.map

@@ -1 +1 @@
-{"version":3,"file":"feature-flag-admin.dto.js","sourceRoot":"","sources":["../../src/admin/feature-flag-admin.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qDASyB;AAEzB,qFAAyE;AAEzE,MAAa,oBAAoB;CAsBhC;AAtBD,oDAsBC;AAnBC;IAFC,IAAA,0BAAQ,GAAE;IACV,IAAA,4BAAU,GAAE;;iDACA;AAIb;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;;yDACU;AAIrB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,2BAAS,GAAE;;qDACM;AAMlB;IAJC,IAAA,4BAAU,GAAE;IACZ,IAAA,uBAAK,GAAE;IACP,IAAA,qBAAG,EAAC,CAAC,CAAC;IACN,IAAA,qBAAG,EAAC,GAAG,CAAC;;wDACW;AAIpB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;;sDACwB;AAGrC,MAAa,oBAAoB;CAkBhC;AAlBD,oDAkBC;AAfC;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;;yDACU;AAIrB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,2BAAS,GAAE;;qDACM;AAMlB;IAJC,IAAA,4BAAU,GAAE;IACZ,IAAA,uBAAK,GAAE;IACP,IAAA,qBAAG,EAAC,CAAC,CAAC;IACN,IAAA,qBAAG,EAAC,GAAG,CAAC;;wDACW;AAIpB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;;sDACwB;AAGrC,MAAa,cAAc;CAU1B;AAVD,wCAUC;AARC;IADC,IAAA,sDAAqB,GAAE;;kDACS;AAGjC;IADC,IAAA,2BAAS,GAAE;;+CACM;AAIlB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,uBAAK,GAAE;;gDACU;AAGpB,MAAa,iBAAiB;CAG7B;AAHD,8CAGC;AADC;IADC,IAAA,sDAAqB,GAAE;;qDACS"}
+{"version":3,"file":"feature-flag-admin.dto.js","sourceRoot":"","sources":["../../src/admin/feature-flag-admin.dto.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qDASyB;AAIzB,qFAAyE;AAEzE,MAAa,oBAAoB;CAsBhC;AAtBD,oDAsBC;AAnBC;IAFC,IAAA,0BAAQ,GAAE;IACV,IAAA,4BAAU,GAAE;;iDACA;AAIb;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;;yDACU;AAIrB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,2BAAS,GAAE;;qDACM;AAMlB;IAJC,IAAA,4BAAU,GAAE;IACZ,IAAA,uBAAK,GAAE;IACP,IAAA,qBAAG,EAAC,CAAC,CAAC;IACN,IAAA,qBAAG,EAAC,GAAG,CAAC;;wDACW;AAIpB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;;sDACwB;AAGrC,MAAa,oBAAoB;CAkBhC;AAlBD,oDAkBC;AAfC;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;;yDACU;AAIrB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,2BAAS,GAAE;;qDACM;AAMlB;IAJC,IAAA,4BAAU,GAAE;IACZ,IAAA,uBAAK,GAAE;IACP,IAAA,qBAAG,EAAC,CAAC,CAAC;IACN,IAAA,qBAAG,EAAC,GAAG,CAAC;;wDACW;AAIpB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;;sDACwB;AAGrC,MAAa,cAAc;CAU1B;AAVD,wCAUC;AARC;IADC,IAAA,sDAAqB,GAAE;;kDACS;AAGjC;IADC,IAAA,2BAAS,GAAE;;+CACM;AAIlB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,uBAAK,GAAE;;gDACU;AAGpB,MAAa,iBAAiB;CAG7B;AAHD,8CAGC;AADC;IADC,IAAA,sDAAqB,GAAE;;qDACS;AAGnC,MAAa,sBAAsB;CAgBlC;AAhBD,wDAgBC;AAbC;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,0BAAQ,GAAE;;uDACiB;AAI5B;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,2BAAS,GAAE;;4DACW;AAIvB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,2BAAS,GAAE;;6DACY;AAIxB;IAFC,IAAA,4BAAU,GAAE;IACZ,IAAA,2BAAS,GAAE;;qEACoB"}

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

@@ -1,6 +1,8 @@
 import { EvaluationContext } from '../interfaces/evaluation-context.interface';
+import { EvaluationReason, EvaluationSource } from '../interfaces/evaluation-details.interface';
 export declare const FeatureFlagEvents: {
     readonly EVALUATED: "feature-flag.evaluated";
+    readonly EXPOSED: "feature-flag.exposed";
     readonly CREATED: "feature-flag.created";
     readonly UPDATED: "feature-flag.updated";
     readonly ARCHIVED: "feature-flag.archived";
@@ -11,13 +13,39 @@ export declare const FeatureFlagEvents: {
 export interface FlagEvaluatedEvent {
     flagKey: string;
     result: boolean;
-    context: EvaluationContext;
-    source: 'override' | 'percentage' | 'global';
+    value?: boolean;
+    context?: EvaluationContext;
+    source: EvaluationSource;
+    reason?: EvaluationReason;
+    defaultUsed?: boolean;
+    errorCode?: string;
+    errorMessage?: string;
+    matchedOverrideId?: string;
+    bucket?: number;
+    targetingKey?: string;
     evaluationTimeMs: number;
 }
+export interface FlagExposedEvent {
+    flagKey: string;
+    value: boolean;
+    result: boolean;
+    source: EvaluationSource;
+    reason: EvaluationReason;
+    defaultUsed: boolean;
+    context?: EvaluationContext;
+    matchedOverrideId?: string;
+    bucket?: number;
+    targetingKey?: string;
+    evaluationTimeMs?: number;
+}
 export interface FlagMutationEvent {
     flagKey: string;
     action: 'created' | 'updated' | 'archived';
+    actorId?: string;
+    actorType?: string;
+    reason?: string;
+    requestId?: string;
+    correlationId?: string;
 }
 export interface FlagOverrideEvent {
     flagKey: string;
@@ -25,4 +53,9 @@ export interface FlagOverrideEvent {
     enabled?: boolean;
     priority?: number;
     action: 'set' | 'removed';
+    actorId?: string;
+    actorType?: string;
+    reason?: string;
+    requestId?: string;
+    correlationId?: string;
 }

package/dist/events/feature-flag.events.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FeatureFlagEvents = void 0;
 exports.FeatureFlagEvents = {
     EVALUATED: 'feature-flag.evaluated',
+    EXPOSED: 'feature-flag.exposed',
     CREATED: 'feature-flag.created',
     UPDATED: 'feature-flag.updated',
     ARCHIVED: 'feature-flag.archived',

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

@@ -1 +1 @@
-{"version":3,"file":"feature-flag.events.js","sourceRoot":"","sources":["../../src/events/feature-flag.events.ts"],"names":[],"mappings":";;;AAEa,QAAA,iBAAiB,GAAG;IAC/B,SAAS,EAAE,wBAAwB;IACnC,OAAO,EAAE,sBAAsB;IAC/B,OAAO,EAAE,sBAAsB;IAC/B,QAAQ,EAAE,uBAAuB;IACjC,YAAY,EAAE,2BAA2B;IACzC,gBAAgB,EAAE,+BAA+B;IACjD,iBAAiB,EAAE,gCAAgC;CAC3C,CAAC"}
+{"version":3,"file":"feature-flag.events.js","sourceRoot":"","sources":["../../src/events/feature-flag.events.ts"],"names":[],"mappings":";;;AAMa,QAAA,iBAAiB,GAAG;IAC/B,SAAS,EAAE,wBAAwB;IACnC,OAAO,EAAE,sBAAsB;IAC/B,OAAO,EAAE,sBAAsB;IAC/B,OAAO,EAAE,sBAAsB;IAC/B,QAAQ,EAAE,uBAAuB;IACjC,YAAY,EAAE,2BAA2B;IACzC,gBAAgB,EAAE,+BAA+B;IACjD,iBAAiB,EAAE,gCAAgC;CAC3C,CAAC"}

package/dist/flag-registry.d.ts

@@ -0,0 +1,24 @@
+import { EvaluationContext } from './interfaces/evaluation-context.interface';
+import { BooleanEvaluationDetails, EvaluateBooleanOptions } from './interfaces/evaluation-details.interface';
+import { FeatureFlagGuardOptions } from './interfaces/feature-flag.interface';
+import { FeatureFlagLifecycleMetadata, FlagKey, FlagRegistry } from './interfaces/flag-registry.interface';
+import { FeatureFlagService } from './services/feature-flag.service';
+export interface TypedFeatureFlagClient<TFlags extends FlagRegistry> {
+    isEnabled<K extends FlagKey<TFlags>>(flagKey: K, context?: EvaluationContext, options?: EvaluateBooleanOptions): Promise<boolean>;
+    evaluateBoolean<K extends FlagKey<TFlags>>(flagKey: K, context?: EvaluationContext, options?: EvaluateBooleanOptions): Promise<BooleanEvaluationDetails>;
+    registry: TFlags;
+}
+export interface TypedFeatureFlagDecorators<TFlags extends FlagRegistry> {
+    FeatureFlag<K extends FlagKey<TFlags>>(flagKey: K, options?: FeatureFlagGuardOptions): ClassDecorator & MethodDecorator;
+}
+export type FlagLifecycleStatusName = 'active' | 'stale' | 'expired';
+export interface FlagLifecycleStatus extends FeatureFlagLifecycleMetadata {
+    status: FlagLifecycleStatusName;
+    tags: string[];
+    staleAt?: Date;
+    expiresAt?: Date;
+}
+export declare function defineFlags<const TFlags extends FlagRegistry>(flags: TFlags): TFlags;
+export declare function createFeatureFlagClient<TFlags extends FlagRegistry>(service: FeatureFlagService, registry: TFlags): TypedFeatureFlagClient<TFlags>;
+export declare function createFeatureFlagDecorators<TFlags extends FlagRegistry>(registry: TFlags): TypedFeatureFlagDecorators<TFlags>;
+export declare function getFlagLifecycleStatus(metadata: FeatureFlagLifecycleMetadata, now?: Date): FlagLifecycleStatus;

package/dist/flag-registry.js

@@ -0,0 +1,62 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineFlags = defineFlags;
+exports.createFeatureFlagClient = createFeatureFlagClient;
+exports.createFeatureFlagDecorators = createFeatureFlagDecorators;
+exports.getFlagLifecycleStatus = getFlagLifecycleStatus;
+const feature_flag_decorator_1 = require("./decorators/feature-flag.decorator");
+function defineFlags(flags) {
+    return flags;
+}
+function createFeatureFlagClient(service, registry) {
+    return {
+        registry,
+        isEnabled: (flagKey, context, options) => service.isEnabled(flagKey, context, mergeRegistryOptions(registry[flagKey], options)),
+        evaluateBoolean: (flagKey, context, options) => service.evaluateBoolean(flagKey, context, mergeRegistryOptions(registry[flagKey], options)),
+    };
+}
+function createFeatureFlagDecorators(registry) {
+    return {
+        FeatureFlag: (flagKey, options = {}) => (0, feature_flag_decorator_1.FeatureFlag)(flagKey, {
+            defaultValue: registry[flagKey].defaultValue,
+            ...options,
+        }),
+    };
+}
+function getFlagLifecycleStatus(metadata, now = new Date()) {
+    const staleAt = parseLifecycleDate(metadata.staleAt);
+    const expiresAt = parseLifecycleDate(metadata.expiresAt);
+    const status = getLifecycleStatusName(now, staleAt, expiresAt);
+    return {
+        ...metadata,
+        tags: [...(metadata.tags ?? [])],
+        staleAt,
+        expiresAt,
+        status,
+    };
+}
+function mergeRegistryOptions(definition, options = {}) {
+    const merged = {
+        defaultValue: definition.defaultValue,
+    };
+    if (definition.trackExposure !== undefined) {
+        merged.trackExposure = definition.trackExposure;
+    }
+    return { ...merged, ...options };
+}
+function getLifecycleStatusName(now, staleAt, expiresAt) {
+    if (expiresAt && now >= expiresAt) {
+        return 'expired';
+    }
+    if (staleAt && now >= staleAt) {
+        return 'stale';
+    }
+    return 'active';
+}
+function parseLifecycleDate(value) {
+    if (!value) {
+        return undefined;
+    }
+    return value instanceof Date ? value : new Date(value);
+}
+//# sourceMappingURL=flag-registry.js.map

package/dist/flag-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flag-registry.js","sourceRoot":"","sources":["../src/flag-registry.ts"],"names":[],"mappings":";;AA8CA,kCAEC;AAED,0DAeC;AAED,kEAUC;AAED,wDAeC;AA9FD,gFAAkE;AA8ClE,SAAgB,WAAW,CAAoC,KAAa;IAC1E,OAAO,KAAK,CAAC;AACf,CAAC;AAED,SAAgB,uBAAuB,CACrC,OAA2B,EAC3B,QAAgB;IAEhB,OAAO;QACL,QAAQ;QACR,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CACvC,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,OAAO,EAAE,oBAAoB,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CAAC;QACvF,eAAe,EAAE,CAAC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,CAC7C,OAAO,CAAC,eAAe,CACrB,OAAO,EACP,OAAO,EACP,oBAAoB,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC,CACjD;KACJ,CAAC;AACJ,CAAC;AAED,SAAgB,2BAA2B,CACzC,QAAgB;IAEhB,OAAO;QACL,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,GAAG,EAAE,EAAE,EAAE,CACrC,IAAA,oCAAW,EAAC,OAAO,EAAE;YACnB,YAAY,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,YAAY;YAC5C,GAAG,OAAO;SACX,CAAC;KACL,CAAC;AACJ,CAAC;AAED,SAAgB,sBAAsB,CACpC,QAAsC,EACtC,MAAY,IAAI,IAAI,EAAE;IAEtB,MAAM,OAAO,GAAG,kBAAkB,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACrD,MAAM,SAAS,GAAG,kBAAkB,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IACzD,MAAM,MAAM,GAAG,sBAAsB,CAAC,GAAG,EAAE,OAAO,EAAE,SAAS,CAAC,CAAC;IAE/D,OAAO;QACL,GAAG,QAAQ;QACX,IAAI,EAAE,CAAC,GAAG,CAAC,QAAQ,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAChC,OAAO;QACP,SAAS;QACT,MAAM;KACP,CAAC;AACJ,CAAC;AAED,SAAS,oBAAoB,CAC3B,UAAgC,EAChC,UAAkC,EAAE;IAEpC,MAAM,MAAM,GAA2B;QACrC,YAAY,EAAE,UAAU,CAAC,YAAY;KACtC,CAAC;IAEF,IAAI,UAAU,CAAC,aAAa,KAAK,SAAS,EAAE,CAAC;QAC3C,MAAM,CAAC,aAAa,GAAG,UAAU,CAAC,aAAa,CAAC;IAClD,CAAC;IAED,OAAO,EAAE,GAAG,MAAM,EAAE,GAAG,OAAO,EAAE,CAAC;AACnC,CAAC;AAED,SAAS,sBAAsB,CAC7B,GAAS,EACT,OAAc,EACd,SAAgB;IAEhB,IAAI,SAAS,IAAI,GAAG,IAAI,SAAS,EAAE,CAAC;QAClC,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,OAAO,IAAI,GAAG,IAAI,OAAO,EAAE,CAAC;QAC9B,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,SAAS,kBAAkB,CAAC,KAAgC;IAC1D,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,OAAO,KAAK,YAAY,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC;AACzD,CAAC"}

package/dist/guards/feature-flag.guard.js

@@ -35,7 +35,11 @@ let FeatureFlagGuard = class FeatureFlagGuard {
         const options = this.reflector.get(feature_flag_constants_1.FEATURE_FLAG_OPTIONS_KEY, handler) ??
             this.reflector.get(feature_flag_constants_1.FEATURE_FLAG_OPTIONS_KEY, classRef) ??
             {};
-        const enabled = await this.featureFlagService.isEnabled(flagKey);
+        const enabled = options.defaultValue === undefined
+            ? await this.featureFlagService.isEnabled(flagKey)
+            : await this.featureFlagService.isEnabled(flagKey, undefined, {
+                defaultValue: options.defaultValue,
+            });
         if (!enabled) {
             const statusCode = options.statusCode ?? 403;
             const body = options.fallback ?? { message: 'Feature not available' };

package/dist/guards/feature-flag.guard.js.map

@@ -1 +1 @@
-{"version":3,"file":"feature-flag.guard.js","sourceRoot":"","sources":["../../src/guards/feature-flag.guard.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA0F;AAC1F,uCAAyC;AACzC,2EAAsE;AACtE,sEAImC;AAI5B,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;IAC3B,YACmB,SAAoB,EACpB,kBAAsC;QADtC,cAAS,GAAT,SAAS,CAAW;QACpB,uBAAkB,GAAlB,kBAAkB,CAAoB;IACtD,CAAC;IAEJ,KAAK,CAAC,WAAW,CAAC,OAAyB;QACzC,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QAEpC,eAAe;QACf,MAAM,MAAM,GACV,IAAI,CAAC,SAAS,CAAC,GAAG,CAAU,gDAAuB,EAAE,OAAO,CAAC;YAC7D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAU,gDAAuB,EAAE,QAAQ,CAAC,CAAC;QACjE,IAAI,MAAM;YAAE,OAAO,IAAI,CAAC;QAExB,yDAAyD;QACzD,MAAM,OAAO,GACX,IAAI,CAAC,SAAS,CAAC,GAAG,CAAS,yCAAgB,EAAE,OAAO,CAAC;YACrD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAS,yCAAgB,EAAE,QAAQ,CAAC,CAAC;QACzD,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAE1B,MAAM,OAAO,GACX,IAAI,CAAC,SAAS,CAAC,GAAG,CAA0B,iDAAwB,EAAE,OAAO,CAAC;YAC9E,IAAI,CAAC,SAAS,CAAC,GAAG,CAA0B,iDAAwB,EAAE,QAAQ,CAAC;YAC/E,EAAE,CAAC;QAEL,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;QAEjE,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,CAAC;YAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC;YACtE,MAAM,IAAI,sBAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC5C,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF,CAAA;AArCY,4CAAgB;2BAAhB,gBAAgB;IAD5B,IAAA,mBAAU,GAAE;qCAGmB,gBAAS;QACA,yCAAkB;GAH9C,gBAAgB,CAqC5B"}
+{"version":3,"file":"feature-flag.guard.js","sourceRoot":"","sources":["../../src/guards/feature-flag.guard.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA0F;AAC1F,uCAAyC;AACzC,2EAAsE;AACtE,sEAImC;AAI5B,IAAM,gBAAgB,GAAtB,MAAM,gBAAgB;IAC3B,YACmB,SAAoB,EACpB,kBAAsC;QADtC,cAAS,GAAT,SAAS,CAAW;QACpB,uBAAkB,GAAlB,kBAAkB,CAAoB;IACtD,CAAC;IAEJ,KAAK,CAAC,WAAW,CAAC,OAAyB;QACzC,MAAM,OAAO,GAAG,OAAO,CAAC,UAAU,EAAE,CAAC;QACrC,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;QAEpC,eAAe;QACf,MAAM,MAAM,GACV,IAAI,CAAC,SAAS,CAAC,GAAG,CAAU,gDAAuB,EAAE,OAAO,CAAC;YAC7D,IAAI,CAAC,SAAS,CAAC,GAAG,CAAU,gDAAuB,EAAE,QAAQ,CAAC,CAAC;QACjE,IAAI,MAAM;YAAE,OAAO,IAAI,CAAC;QAExB,yDAAyD;QACzD,MAAM,OAAO,GACX,IAAI,CAAC,SAAS,CAAC,GAAG,CAAS,yCAAgB,EAAE,OAAO,CAAC;YACrD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAS,yCAAgB,EAAE,QAAQ,CAAC,CAAC;QACzD,IAAI,CAAC,OAAO;YAAE,OAAO,IAAI,CAAC;QAE1B,MAAM,OAAO,GACX,IAAI,CAAC,SAAS,CAAC,GAAG,CAA0B,iDAAwB,EAAE,OAAO,CAAC;YAC9E,IAAI,CAAC,SAAS,CAAC,GAAG,CAA0B,iDAAwB,EAAE,QAAQ,CAAC;YAC/E,EAAE,CAAC;QAEL,MAAM,OAAO,GACX,OAAO,CAAC,YAAY,KAAK,SAAS;YAChC,CAAC,CAAC,MAAM,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,OAAO,CAAC;YAClD,CAAC,CAAC,MAAM,IAAI,CAAC,kBAAkB,CAAC,SAAS,CAAC,OAAO,EAAE,SAAS,EAAE;gBAC1D,YAAY,EAAE,OAAO,CAAC,YAAY;aACnC,CAAC,CAAC;QAET,IAAI,CAAC,OAAO,EAAE,CAAC;YACb,MAAM,UAAU,GAAG,OAAO,CAAC,UAAU,IAAI,GAAG,CAAC;YAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,IAAI,EAAE,OAAO,EAAE,uBAAuB,EAAE,CAAC;YACtE,MAAM,IAAI,sBAAa,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC5C,CAAC;QAED,OAAO,IAAI,CAAC;IACd,CAAC;CACF,CAAA;AA1CY,4CAAgB;2BAAhB,gBAAgB;IAD5B,IAAA,mBAAU,GAAE;qCAGmB,gBAAS;QACA,yCAAkB;GAH9C,gBAAgB,CA0C5B"}

package/dist/index.d.ts

@@ -6,8 +6,11 @@ export { FeatureFlag } from './decorators/feature-flag.decorator';
 export { BypassFeatureFlag } from './decorators/bypass-feature-flag.decorator';
 export { FeatureFlagModuleOptions, FeatureFlagModuleAsyncOptions, FeatureFlagModuleOptionsFactory, } from './interfaces/feature-flag-options.interface';
 export { EvaluationContext } from './interfaces/evaluation-context.interface';
-export { CreateFeatureFlagInput, UpdateFeatureFlagInput, SetOverrideInput, RemoveOverrideInput, TargetingAttributeValue, TargetingAttributes, FeatureFlagGuardOptions, FeatureFlagWithOverrides, FlagOverride, } from './interfaces/feature-flag.interface';
-export { FeatureFlagEvents, FlagEvaluatedEvent, FlagMutationEvent, FlagOverrideEvent, } from './events/feature-flag.events';
+export { EvaluationSource, EvaluationReason, EvaluateBooleanOptions, BooleanEvaluationDetails, BucketBy, FlagEvaluatorOptions, } from './interfaces/evaluation-details.interface';
+export { FeatureFlagLifecycleMetadata, FeatureFlagType, FlagDefinition, FlagRegistry, FlagKey, } from './interfaces/flag-registry.interface';
+export { CreateFeatureFlagInput, UpdateFeatureFlagInput, SetOverrideInput, RemoveOverrideInput, TargetingAttributeValue, TargetingAttributes, FeatureFlagGuardOptions, FeatureFlagWithOverrides, FlagOverride, FlagMutationMetadata, } from './interfaces/feature-flag.interface';
+export { defineFlags, createFeatureFlagClient, createFeatureFlagDecorators, getFlagLifecycleStatus, TypedFeatureFlagClient, TypedFeatureFlagDecorators, FlagLifecycleStatus, FlagLifecycleStatusName, } from './flag-registry';
+export { FeatureFlagEvents, FlagEvaluatedEvent, FlagExposedEvent, FlagMutationEvent, FlagOverrideEvent, } from './events/feature-flag.events';
 export { FEATURE_FLAG_MODULE_OPTIONS, CACHE_ADAPTER, FEATURE_FLAG_REPOSITORY, TENANT_CONTEXT_PROVIDER, } from './feature-flag.constants';
 export type { CacheAdapter } from './interfaces/cache-adapter.interface';
 export { MemoryCacheAdapter } from './cache/memory-cache.adapter';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FeatureFlagAdminModule = exports.PrismaFeatureFlagRepository = exports.RedisCacheAdapter = exports.MemoryCacheAdapter = exports.TENANT_CONTEXT_PROVIDER = exports.FEATURE_FLAG_REPOSITORY = exports.CACHE_ADAPTER = exports.FEATURE_FLAG_MODULE_OPTIONS = exports.FeatureFlagEvents = exports.BypassFeatureFlag = exports.FeatureFlag = exports.FeatureFlagGuard = exports.FlagContext = exports.FeatureFlagService = exports.FeatureFlagModule = void 0;
+exports.FeatureFlagAdminModule = exports.PrismaFeatureFlagRepository = exports.RedisCacheAdapter = exports.MemoryCacheAdapter = exports.TENANT_CONTEXT_PROVIDER = exports.FEATURE_FLAG_REPOSITORY = exports.CACHE_ADAPTER = exports.FEATURE_FLAG_MODULE_OPTIONS = exports.FeatureFlagEvents = exports.getFlagLifecycleStatus = exports.createFeatureFlagDecorators = exports.createFeatureFlagClient = exports.defineFlags = exports.BypassFeatureFlag = exports.FeatureFlag = exports.FeatureFlagGuard = exports.FlagContext = exports.FeatureFlagService = exports.FeatureFlagModule = void 0;
 // Module
 var feature_flag_module_1 = require("./feature-flag.module");
 Object.defineProperty(exports, "FeatureFlagModule", { enumerable: true, get: function () { return feature_flag_module_1.FeatureFlagModule; } });
@@ -17,6 +17,12 @@ var feature_flag_decorator_1 = require("./decorators/feature-flag.decorator");
 Object.defineProperty(exports, "FeatureFlag", { enumerable: true, get: function () { return feature_flag_decorator_1.FeatureFlag; } });
 var bypass_feature_flag_decorator_1 = require("./decorators/bypass-feature-flag.decorator");
 Object.defineProperty(exports, "BypassFeatureFlag", { enumerable: true, get: function () { return bypass_feature_flag_decorator_1.BypassFeatureFlag; } });
+// Registry helpers
+var flag_registry_1 = require("./flag-registry");
+Object.defineProperty(exports, "defineFlags", { enumerable: true, get: function () { return flag_registry_1.defineFlags; } });
+Object.defineProperty(exports, "createFeatureFlagClient", { enumerable: true, get: function () { return flag_registry_1.createFeatureFlagClient; } });
+Object.defineProperty(exports, "createFeatureFlagDecorators", { enumerable: true, get: function () { return flag_registry_1.createFeatureFlagDecorators; } });
+Object.defineProperty(exports, "getFlagLifecycleStatus", { enumerable: true, get: function () { return flag_registry_1.getFlagLifecycleStatus; } });
 // Events
 var feature_flag_events_1 = require("./events/feature-flag.events");
 Object.defineProperty(exports, "FeatureFlagEvents", { enumerable: true, get: function () { return feature_flag_events_1.FeatureFlagEvents; } });

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,SAAS;AACT,6DAA2H;AAAlH,wHAAA,iBAAiB,OAAA;AAE1B,WAAW;AACX,wEAAqE;AAA5D,0HAAA,kBAAkB,OAAA;AAC3B,wDAAsD;AAA7C,2GAAA,WAAW,OAAA;AAEpB,QAAQ;AACR,kEAA+D;AAAtD,sHAAA,gBAAgB,OAAA;AAEzB,aAAa;AACb,8EAAkE;AAAzD,qHAAA,WAAW,OAAA;AACpB,4FAA+E;AAAtE,kIAAA,iBAAiB,OAAA;AAqB1B,SAAS;AACT,oEAKsC;AAJpC,wHAAA,iBAAiB,OAAA;AAMnB,YAAY;AACZ,mEAKkC;AAJhC,qIAAA,2BAA2B,OAAA;AAC3B,uHAAA,aAAa,OAAA;AACb,iIAAA,uBAAuB,OAAA;AACvB,iIAAA,uBAAuB,OAAA;AAKzB,qEAAkE;AAAzD,0HAAA,kBAAkB,OAAA;AAC3B,mEAA+F;AAAtF,wHAAA,iBAAiB,OAAA;AAQ1B,gGAA4F;AAAnF,6IAAA,2BAA2B,OAAA;AAKpC,eAAe;AACf,+EAA2E;AAAlE,mIAAA,sBAAsB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,SAAS;AACT,6DAA2H;AAAlH,wHAAA,iBAAiB,OAAA;AAE1B,WAAW;AACX,wEAAqE;AAA5D,0HAAA,kBAAkB,OAAA;AAC3B,wDAAsD;AAA7C,2GAAA,WAAW,OAAA;AAEpB,QAAQ;AACR,kEAA+D;AAAtD,sHAAA,gBAAgB,OAAA;AAEzB,aAAa;AACb,8EAAkE;AAAzD,qHAAA,WAAW,OAAA;AACpB,4FAA+E;AAAtE,kIAAA,iBAAiB,OAAA;AAqC1B,mBAAmB;AACnB,iDASyB;AARvB,4GAAA,WAAW,OAAA;AACX,wHAAA,uBAAuB,OAAA;AACvB,4HAAA,2BAA2B,OAAA;AAC3B,uHAAA,sBAAsB,OAAA;AAOxB,SAAS;AACT,oEAMsC;AALpC,wHAAA,iBAAiB,OAAA;AAOnB,YAAY;AACZ,mEAKkC;AAJhC,qIAAA,2BAA2B,OAAA;AAC3B,uHAAA,aAAa,OAAA;AACb,iIAAA,uBAAuB,OAAA;AACvB,iIAAA,uBAAuB,OAAA;AAKzB,qEAAkE;AAAzD,0HAAA,kBAAkB,OAAA;AAC3B,mEAA+F;AAAtF,wHAAA,iBAAiB,OAAA;AAQ1B,gGAA4F;AAAnF,6IAAA,2BAA2B,OAAA;AAKpC,eAAe;AACf,+EAA2E;AAAlE,mIAAA,sBAAsB,OAAA"}

package/dist/interfaces/evaluation-context.interface.d.ts

@@ -6,6 +6,8 @@ export interface EvaluationContext {
     tenantId?: string | null;
     /** Environment - auto-injected from module options. Can be explicitly overridden */
     environment?: string;
+    /** Explicit stable key for percentage rollout bucketing */
+    targetingKey?: string | null;
     /** Additional exact-match targeting attributes */
     attributes?: TargetingAttributes;
 }

package/dist/interfaces/evaluation-details.interface.d.ts

@@ -0,0 +1,29 @@
+export type EvaluationSource = 'override' | 'percentage' | 'global' | 'default';
+export type EvaluationReason = 'ARCHIVED' | 'OVERRIDE_MATCH' | 'PERCENTAGE_MATCH' | 'PERCENTAGE_MISS' | 'PERCENTAGE_NO_TARGETING_KEY' | 'GLOBAL' | 'FLAG_NOT_FOUND' | 'ERROR';
+export type BucketBy = 'userId' | 'tenantId' | 'environment' | 'targetingKey' | (string & {});
+export interface EvaluateBooleanOptions {
+    /** Invocation-level default used when the flag is missing or evaluation fails. */
+    defaultValue?: boolean;
+    /** Emit an exposure event for this evaluation. */
+    trackExposure?: boolean;
+    /** Include the full resolved context in evaluation/exposure events. */
+    includeContextInEvent?: boolean;
+}
+export interface BooleanEvaluationDetails {
+    flagKey: string;
+    value: boolean;
+    /** Backward-compatible alias for value. */
+    result: boolean;
+    source: EvaluationSource;
+    reason: EvaluationReason;
+    defaultUsed: boolean;
+    errorCode?: string;
+    errorMessage?: string;
+    matchedOverrideId?: string;
+    bucket?: number;
+    targetingKey?: string;
+    evaluationTimeMs?: number;
+}
+export interface FlagEvaluatorOptions {
+    bucketBy?: BucketBy;
+}

package/dist/interfaces/evaluation-details.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=evaluation-details.interface.js.map

package/dist/interfaces/evaluation-details.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"evaluation-details.interface.js","sourceRoot":"","sources":["../../src/interfaces/evaluation-details.interface.ts"],"names":[],"mappings":""}

package/dist/interfaces/feature-flag-options.interface.d.ts

@@ -1,6 +1,7 @@
 import { ModuleMetadata, Type } from '@nestjs/common';
 import { Request } from 'express';
 import { CacheAdapter } from './cache-adapter.interface';
+import { FlagRegistry } from './flag-registry.interface';
 export interface FeatureFlagModuleOptions {
     /** Current environment (e.g., 'development', 'staging', 'production') */
     environment: string;
@@ -14,6 +15,8 @@ export interface FeatureFlagModuleOptions {
     emitEvents?: boolean;
     /** Custom cache adapter implementation. If not provided, an in-memory cache is used. */
     cacheAdapter?: CacheAdapter;
+    /** Optional type-safe flag registry used for defaults and evaluation metadata. */
+    flags?: FlagRegistry;
 }
 export interface FeatureFlagModuleOptionsFactory {
     createFeatureFlagOptions(): Promise<FeatureFlagModuleOptions & {