@nestarc/feature-flag 0.1.0 → 0.2.0

package/README.md

@@ -1,5 +1,11 @@
 # @nestarc/feature-flag
 
+[![npm version](https://img.shields.io/npm/v/@nestarc/feature-flag.svg)](https://www.npmjs.com/package/@nestarc/feature-flag)
+[![npm downloads](https://img.shields.io/npm/dm/@nestarc/feature-flag.svg)](https://www.npmjs.com/package/@nestarc/feature-flag)
+[![CI](https://github.com/nestarc/nestjs-feature-flag/actions/workflows/ci.yml/badge.svg)](https://github.com/nestarc/nestjs-feature-flag/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Docs](https://img.shields.io/badge/docs-nestarc.dev-blue.svg)](https://nestarc.dev/packages/feature-flag/)
+
 DB-backed feature flags for NestJS + Prisma + PostgreSQL -- tenant-aware overrides, percentage rollouts, and zero external dependencies.
 
 ## Features
@@ -10,7 +16,10 @@ DB-backed feature flags for NestJS + Prisma + PostgreSQL -- tenant-aware overrid
 - **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
-- **Built-in caching** -- configurable TTL with manual invalidation
+- **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
 - **Testing utilities** -- drop-in `TestFeatureFlagModule` for unit and integration tests
 
@@ -31,8 +40,35 @@ npm install @nestjs/common @nestjs/core @prisma/client rxjs reflect-metadata
 ```bash
 # Required only if you enable emitEvents
 npm install @nestjs/event-emitter
+
+# Required only if you use RedisCacheAdapter
+npm install ioredis
+```
+
+## Redis Cache (Multi-Instance)
+
+For production deployments with multiple instances, use `RedisCacheAdapter` for shared caching and real-time invalidation via Redis Pub/Sub:
+
+```typescript
+import { FeatureFlagModule, RedisCacheAdapter } from '@nestarc/feature-flag';
+import { Redis } from 'ioredis';
+
+const redisClient = new Redis({ host: 'localhost', port: 6379 });
+
+FeatureFlagModule.forRoot({
+  environment: 'production',
+  prisma,
+  cacheAdapter: new RedisCacheAdapter({
+    client: redisClient,
+    // subscriber is auto-created via client.duplicate()
+    // keyPrefix: 'feature-flag:',   // default
+    // channel: 'feature-flag:invalidate',  // default
+  }),
+})
 ```
 
+When a flag is updated on any instance, all other instances are notified via Pub/Sub and invalidate their cache immediately — eliminating the stale-cache window.
+
 ## Prisma Schema
 
 Add the following models to your `schema.prisma`:
@@ -438,7 +474,13 @@ describe('DashboardController', () => {
 });
 ```
 
-`TestFeatureFlagModule.register()` provides a global mock of `FeatureFlagService` where `isEnabled(key)` returns the boolean you specified (defaulting to `false` for unregistered keys) and `evaluateAll()` returns the full map.
+`TestFeatureFlagModule.register()` provides a global mock of `FeatureFlagService`:
+- `isEnabled(key)` returns the boolean you specified (defaulting to `false` for unregistered keys)
+- `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.
 
 ## Evaluation Priority
 
@@ -466,6 +508,7 @@ Percentage rollout uses murmurhash3 for deterministic bucketing: the same user a
 | `userIdExtractor`   | `(req: Request) => string \| null`| `undefined`| Extracts user ID from the incoming request                     |
 | `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`)  |
 
 ### FeatureFlagModuleRootOptions
 
@@ -504,6 +547,111 @@ const allFlags = await this.flags.findAll();
 this.flags.invalidateCache();
 ```
 
+## Admin REST API
+
+`FeatureFlagAdminModule` provides a REST API for managing flags. It requires a guard — the module won't register without one:
+
+```typescript
+import { FeatureFlagAdminModule } from '@nestarc/feature-flag';
+import { AdminAuthGuard } from './guards/admin-auth.guard';
+
+@Module({
+  imports: [
+    FeatureFlagModule.forRoot({ ... }),
+    FeatureFlagAdminModule.register({
+      guard: AdminAuthGuard,
+      // path: 'feature-flags',  // default
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+### Endpoints
+
+| Method | Route | Description | Error Responses |
+|--------|-------|-------------|-----------------|
+| POST | `/feature-flags` | Create a flag | 409 duplicate key, 400 invalid percentage |
+| GET | `/feature-flags` | List all flags | |
+| 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/overrides` | Set an override | 404 flag not found |
+| DELETE | `/feature-flags/:key/overrides` | Remove an override | 404 flag not found |
+
+Percentage values must be between 0 and 100 (inclusive). Invalid values return 400 Bad Request.
+
+## Custom Persistence (Advanced)
+
+The default `PrismaFeatureFlagRepository` can be replaced with any implementation of `FeatureFlagRepository`:
+
+```typescript
+import {
+  FeatureFlagModule,
+  FEATURE_FLAG_REPOSITORY,
+  FeatureFlagRepository,
+} from '@nestarc/feature-flag';
+
+@Module({
+  imports: [
+    FeatureFlagModule.forRoot({
+      environment: 'production',
+      prisma, // still required for module init, but unused if you override the repository
+    }),
+  ],
+  providers: [
+    {
+      provide: FEATURE_FLAG_REPOSITORY,
+      useClass: MyCustomRepository, // implements FeatureFlagRepository
+    },
+  ],
+})
+export class AppModule {}
+```
+
+## Custom Tenant Resolution (Advanced)
+
+Override the default `@nestarc/tenancy` integration with your own `TenantContextProvider`:
+
+```typescript
+import {
+  FeatureFlagModule,
+  TENANT_CONTEXT_PROVIDER,
+  TenantContextProvider,
+} from '@nestarc/feature-flag';
+
+@Injectable()
+class MyTenantProvider implements TenantContextProvider {
+  getCurrentTenantId(): string | null {
+    // your custom tenant resolution logic
+    return 'tenant-from-custom-source';
+  }
+}
+
+@Module({
+  imports: [FeatureFlagModule.forRoot({ ... })],
+  providers: [
+    { provide: TENANT_CONTEXT_PROVIDER, useClass: MyTenantProvider },
+  ],
+})
+export class AppModule {}
+```
+
+## Performance
+
+Measured with PostgreSQL 16, Prisma 6, 500 iterations on Apple Silicon:
+
+| Scenario | Avg | P50 | P95 | P99 |
+|----------|-----|-----|-----|-----|
+| **isEnabled() — cache hit** | **0.04ms** | **0.03ms** | **0.05ms** | **0.07ms** |
+| isEnabled() — cache miss (DB lookup) | 1.30ms | 1.14ms | 2.54ms | 3.69ms |
+| isEnabled() — override cascade (cold) | 1.07ms | 1.02ms | 1.43ms | 2.11ms |
+| **evaluateAll() — 50 flags (mixed)** | **0.19ms** | **0.04ms** | **1.55ms** | **1.71ms** |
+
+Cache speedup: **32.5x** (hit vs miss). Keep the default 30s cache TTL for optimal performance.
+
+> Reproduce: `docker compose up -d && dotenv -e .env.test -- npx ts-node benchmarks/evaluation-overhead.ts`
+
 ## License
 
 MIT

package/dist/admin/admin-options.interface.d.ts

@@ -0,0 +1,5 @@
+import { CanActivate, Type } from '@nestjs/common';
+export interface FeatureFlagAdminOptions {
+    guard: Type<CanActivate>;
+    path?: string;
+}

package/dist/admin/admin-options.interface.js

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

package/dist/admin/admin-options.interface.js.map

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

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

@@ -0,0 +1,14 @@
+import { FeatureFlagService } from '../services/feature-flag.service';
+import { CreateFeatureFlagInput, UpdateFeatureFlagInput, SetOverrideInput, FeatureFlagWithOverrides } from '../interfaces/feature-flag.interface';
+import { RemoveOverrideInput } from '../interfaces/feature-flag.interface';
+export declare class FeatureFlagAdminController {
+    private readonly service;
+    constructor(service: FeatureFlagService);
+    create(input: CreateFeatureFlagInput): Promise<FeatureFlagWithOverrides>;
+    findAll(): Promise<FeatureFlagWithOverrides[]>;
+    findByKey(key: string): Promise<FeatureFlagWithOverrides>;
+    update(key: string, input: UpdateFeatureFlagInput): Promise<FeatureFlagWithOverrides>;
+    archive(key: string): Promise<FeatureFlagWithOverrides>;
+    setOverride(key: string, input: SetOverrideInput): Promise<void>;
+    removeOverride(key: string, input: RemoveOverrideInput): Promise<void>;
+}

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

@@ -0,0 +1,100 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureFlagAdminController = void 0;
+const common_1 = require("@nestjs/common");
+const feature_flag_service_1 = require("../services/feature-flag.service");
+let FeatureFlagAdminController = class FeatureFlagAdminController {
+    constructor(service) {
+        this.service = service;
+    }
+    create(input) {
+        return this.service.create(input);
+    }
+    findAll() {
+        return this.service.findAll();
+    }
+    findByKey(key) {
+        return this.service.findByKey(key);
+    }
+    update(key, input) {
+        return this.service.update(key, input);
+    }
+    archive(key) {
+        return this.service.archive(key);
+    }
+    setOverride(key, input) {
+        return this.service.setOverride(key, input);
+    }
+    removeOverride(key, input) {
+        return this.service.removeOverride(key, input);
+    }
+};
+exports.FeatureFlagAdminController = FeatureFlagAdminController;
+__decorate([
+    (0, common_1.Post)(),
+    __param(0, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [Object]),
+    __metadata("design:returntype", Promise)
+], FeatureFlagAdminController.prototype, "create", null);
+__decorate([
+    (0, common_1.Get)(),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], FeatureFlagAdminController.prototype, "findAll", null);
+__decorate([
+    (0, common_1.Get)(':key'),
+    __param(0, (0, common_1.Param)('key')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], FeatureFlagAdminController.prototype, "findByKey", null);
+__decorate([
+    (0, common_1.Patch)(':key'),
+    __param(0, (0, common_1.Param)('key')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], FeatureFlagAdminController.prototype, "update", null);
+__decorate([
+    (0, common_1.Delete)(':key'),
+    __param(0, (0, common_1.Param)('key')),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String]),
+    __metadata("design:returntype", Promise)
+], FeatureFlagAdminController.prototype, "archive", null);
+__decorate([
+    (0, common_1.Post)(':key/overrides'),
+    __param(0, (0, common_1.Param)('key')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], FeatureFlagAdminController.prototype, "setOverride", null);
+__decorate([
+    (0, common_1.Delete)(':key/overrides'),
+    __param(0, (0, common_1.Param)('key')),
+    __param(1, (0, common_1.Body)()),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", [String, Object]),
+    __metadata("design:returntype", Promise)
+], FeatureFlagAdminController.prototype, "removeOverride", null);
+exports.FeatureFlagAdminController = FeatureFlagAdminController = __decorate([
+    (0, common_1.Controller)(),
+    __metadata("design:paramtypes", [feature_flag_service_1.FeatureFlagService])
+], FeatureFlagAdminController);
+//# sourceMappingURL=feature-flag-admin.controller.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag-admin.controller.js","sourceRoot":"","sources":["../../src/admin/feature-flag-admin.controller.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;AAAA,2CAQwB;AACxB,2EAAsE;AAU/D,IAAM,0BAA0B,GAAhC,MAAM,0BAA0B;IACrC,YAA6B,OAA2B;QAA3B,YAAO,GAAP,OAAO,CAAoB;IAAG,CAAC;IAG5D,MAAM,CAAS,KAA6B;QAC1C,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,KAA6B;QAErC,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,CACK,GAAW,EACjB,KAAuB;QAE/B,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IAC9C,CAAC;IAGD,cAAc,CACE,GAAW,EACjB,KAA0B;QAElC,OAAO,IAAI,CAAC,OAAO,CAAC,cAAc,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;IACjD,CAAC;CACF,CAAA;AA9CY,gEAA0B;AAIrC;IADC,IAAA,aAAI,GAAE;IACC,WAAA,IAAA,aAAI,GAAE,CAAA;;;;wDAEb;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;;;;wDAGR;AAGD;IADC,IAAA,eAAM,EAAC,MAAM,CAAC;IACN,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;;;;yDAEpB;AAGD;IADC,IAAA,aAAI,EAAC,gBAAgB,CAAC;IAEpB,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;IACZ,WAAA,IAAA,aAAI,GAAE,CAAA;;;;6DAGR;AAGD;IADC,IAAA,eAAM,EAAC,gBAAgB,CAAC;IAEtB,WAAA,IAAA,cAAK,EAAC,KAAK,CAAC,CAAA;IACZ,WAAA,IAAA,aAAI,GAAE,CAAA;;;;gEAGR;qCA7CU,0BAA0B;IADtC,IAAA,mBAAU,GAAE;qCAE2B,yCAAkB;GAD7C,0BAA0B,CA8CtC"}

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

@@ -0,0 +1,5 @@
+import { DynamicModule } from '@nestjs/common';
+import { FeatureFlagAdminOptions } from './admin-options.interface';
+export declare class FeatureFlagAdminModule {
+    static register(options: FeatureFlagAdminOptions): DynamicModule;
+}

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

@@ -0,0 +1,33 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var FeatureFlagAdminModule_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeatureFlagAdminModule = void 0;
+const common_1 = require("@nestjs/common");
+const feature_flag_admin_controller_1 = require("./feature-flag-admin.controller");
+let FeatureFlagAdminModule = FeatureFlagAdminModule_1 = class FeatureFlagAdminModule {
+    static register(options) {
+        if (!options.guard) {
+            throw new Error('FeatureFlagAdminModule requires a guard. ' +
+                'Pass your auth guard via register({ guard: MyGuard }).');
+        }
+        const path = options.path ?? 'feature-flags';
+        Reflect.defineMetadata('path', path, feature_flag_admin_controller_1.FeatureFlagAdminController);
+        Reflect.defineMetadata('__guards__', [options.guard], feature_flag_admin_controller_1.FeatureFlagAdminController);
+        return {
+            module: FeatureFlagAdminModule_1,
+            controllers: [feature_flag_admin_controller_1.FeatureFlagAdminController],
+            providers: [options.guard],
+        };
+    }
+};
+exports.FeatureFlagAdminModule = FeatureFlagAdminModule;
+exports.FeatureFlagAdminModule = FeatureFlagAdminModule = FeatureFlagAdminModule_1 = __decorate([
+    (0, common_1.Module)({})
+], FeatureFlagAdminModule);
+//# sourceMappingURL=feature-flag-admin.module.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"feature-flag-admin.module.js","sourceRoot":"","sources":["../../src/admin/feature-flag-admin.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAAuD;AACvD,mFAA6E;AAItE,IAAM,sBAAsB,8BAA5B,MAAM,sBAAsB;IACjC,MAAM,CAAC,QAAQ,CAAC,OAAgC;QAC9C,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,2CAA2C;gBAC3C,wDAAwD,CACzD,CAAC;QACJ,CAAC;QAED,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,eAAe,CAAC;QAE7C,OAAO,CAAC,cAAc,CAAC,MAAM,EAAE,IAAI,EAAE,0DAA0B,CAAC,CAAC;QACjE,OAAO,CAAC,cAAc,CAAC,YAAY,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,0DAA0B,CAAC,CAAC;QAElF,OAAO;YACL,MAAM,EAAE,wBAAsB;YAC9B,WAAW,EAAE,CAAC,0DAA0B,CAAC;YACzC,SAAS,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC;SAC3B,CAAC;IACJ,CAAC;CACF,CAAA;AApBY,wDAAsB;iCAAtB,sBAAsB;IADlC,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,sBAAsB,CAoBlC"}

package/dist/cache/memory-cache.adapter.d.ts

@@ -0,0 +1,11 @@
+import { CacheAdapter } from '../interfaces/cache-adapter.interface';
+import { FeatureFlagWithOverrides } from '../interfaces/feature-flag.interface';
+export declare class MemoryCacheAdapter implements CacheAdapter {
+    private cache;
+    private allFlagsCache;
+    get(key: string): Promise<FeatureFlagWithOverrides | null>;
+    set(key: string, data: FeatureFlagWithOverrides, ttlMs: number): Promise<void>;
+    getAll(): Promise<FeatureFlagWithOverrides[] | null>;
+    setAll(data: FeatureFlagWithOverrides[], ttlMs: number): Promise<void>;
+    invalidate(key?: string): Promise<void>;
+}

package/dist/{services/flag-cache.service.js → cache/memory-cache.adapter.js}

@@ -5,23 +5,15 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-var __metadata = (this && this.__metadata) || function (k, v) {
-    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
-};
-var __param = (this && this.__param) || function (paramIndex, decorator) {
-    return function (target, key) { decorator(target, key, paramIndex); }
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FlagCacheService = void 0;
+exports.MemoryCacheAdapter = void 0;
 const common_1 = require("@nestjs/common");
-const feature_flag_constants_1 = require("../feature-flag.constants");
-let FlagCacheService = class FlagCacheService {
-    constructor(options) {
-        this.options = options;
+let MemoryCacheAdapter = class MemoryCacheAdapter {
+    constructor() {
         this.cache = new Map();
         this.allFlagsCache = null;
     }
-    get(key) {
+    async get(key) {
         const entry = this.cache.get(key);
         if (!entry)
             return null;
@@ -31,13 +23,12 @@ let FlagCacheService = class FlagCacheService {
         }
         return entry.data;
     }
-    set(key, data) {
-        const ttl = this.options.cacheTtlMs ?? 30_000;
-        if (ttl === 0)
+    async set(key, data, ttlMs) {
+        if (ttlMs === 0)
             return;
-        this.cache.set(key, { data, expiresAt: Date.now() + ttl });
+        this.cache.set(key, { data, expiresAt: Date.now() + ttlMs });
     }
-    getAll() {
+    async getAll() {
         if (!this.allFlagsCache)
             return null;
         if (Date.now() > this.allFlagsCache.expiresAt) {
@@ -46,27 +37,23 @@ let FlagCacheService = class FlagCacheService {
         }
         return this.allFlagsCache.data;
     }
-    setAll(data) {
-        const ttl = this.options.cacheTtlMs ?? 30_000;
-        if (ttl === 0)
+    async setAll(data, ttlMs) {
+        if (ttlMs === 0)
             return;
-        this.allFlagsCache = { data, expiresAt: Date.now() + ttl };
+        this.allFlagsCache = { data, expiresAt: Date.now() + ttlMs };
     }
-    invalidate(key) {
+    async invalidate(key) {
         if (key) {
             this.cache.delete(key);
-            this.allFlagsCache = null;
         }
         else {
             this.cache.clear();
-            this.allFlagsCache = null;
         }
+        this.allFlagsCache = null;
     }
 };
-exports.FlagCacheService = FlagCacheService;
-exports.FlagCacheService = FlagCacheService = __decorate([
-    (0, common_1.Injectable)(),
-    __param(0, (0, common_1.Inject)(feature_flag_constants_1.FEATURE_FLAG_MODULE_OPTIONS)),
-    __metadata("design:paramtypes", [Object])
-], FlagCacheService);
-//# sourceMappingURL=flag-cache.service.js.map
+exports.MemoryCacheAdapter = MemoryCacheAdapter;
+exports.MemoryCacheAdapter = MemoryCacheAdapter = __decorate([
+    (0, common_1.Injectable)()
+], MemoryCacheAdapter);
+//# sourceMappingURL=memory-cache.adapter.js.map

package/dist/cache/memory-cache.adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory-cache.adapter.js","sourceRoot":"","sources":["../../src/cache/memory-cache.adapter.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4C;AAUrC,IAAM,kBAAkB,GAAxB,MAAM,kBAAkB;IAAxB;QACG,UAAK,GAAG,IAAI,GAAG,EAAgD,CAAC;QAChE,kBAAa,GAAkD,IAAI,CAAC;IAuC9E,CAAC;IArCC,KAAK,CAAC,GAAG,CAAC,GAAW;QACnB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,IAAI,CAAC;QACxB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,KAAK,CAAC,IAAI,CAAC;IACpB,CAAC;IAED,KAAK,CAAC,GAAG,CAAC,GAAW,EAAE,IAA8B,EAAE,KAAa;QAClE,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO;QACxB,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,MAAM;QACV,IAAI,CAAC,IAAI,CAAC,aAAa;YAAE,OAAO,IAAI,CAAC;QACrC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,aAAa,CAAC,SAAS,EAAE,CAAC;YAC9C,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;YAC1B,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,CAAC,aAAa,CAAC,IAAI,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAgC,EAAE,KAAa;QAC1D,IAAI,KAAK,KAAK,CAAC;YAAE,OAAO;QACxB,IAAI,CAAC,aAAa,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;IAC/D,CAAC;IAED,KAAK,CAAC,UAAU,CAAC,GAAY;QAC3B,IAAI,GAAG,EAAE,CAAC;YACR,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACzB,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC;QACrB,CAAC;QACD,IAAI,CAAC,aAAa,GAAG,IAAI,CAAC;IAC5B,CAAC;CACF,CAAA;AAzCY,gDAAkB;6BAAlB,kBAAkB;IAD9B,IAAA,mBAAU,GAAE;GACA,kBAAkB,CAyC9B"}

package/dist/cache/redis-cache.adapter.d.ts

@@ -0,0 +1,26 @@
+import type { Redis } from 'ioredis';
+import { CacheAdapter } from '../interfaces/cache-adapter.interface';
+import { FeatureFlagWithOverrides } from '../interfaces/feature-flag.interface';
+export interface RedisCacheAdapterOptions {
+    client: Redis;
+    subscriber?: Redis;
+    keyPrefix?: string;
+    channel?: string;
+}
+export declare class RedisCacheAdapter implements CacheAdapter {
+    private readonly client;
+    private readonly subscriber;
+    private readonly keyPrefix;
+    private readonly channel;
+    private readonly ownsSubscriber;
+    constructor(options: RedisCacheAdapterOptions);
+    private setupSubscription;
+    get(key: string): Promise<FeatureFlagWithOverrides | null>;
+    set(key: string, data: FeatureFlagWithOverrides, ttlMs: number): Promise<void>;
+    getAll(): Promise<FeatureFlagWithOverrides[] | null>;
+    setAll(data: FeatureFlagWithOverrides[], ttlMs: number): Promise<void>;
+    invalidate(key?: string): Promise<void>;
+    onModuleDestroy(): Promise<void>;
+    private prefixedKey;
+    private flushLocal;
+}

package/dist/cache/redis-cache.adapter.js

@@ -0,0 +1,102 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+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.RedisCacheAdapter = void 0;
+const common_1 = require("@nestjs/common");
+let RedisCacheAdapter = class RedisCacheAdapter {
+    constructor(options) {
+        this.client = options.client;
+        this.keyPrefix = options.keyPrefix ?? 'feature-flag:';
+        this.channel = options.channel ?? 'feature-flag:invalidate';
+        if (options.subscriber) {
+            this.subscriber = options.subscriber;
+            this.ownsSubscriber = false;
+        }
+        else {
+            this.subscriber = this.client.duplicate();
+            this.ownsSubscriber = true;
+        }
+        this.setupSubscription();
+    }
+    setupSubscription() {
+        this.subscriber.subscribe(this.channel);
+        this.subscriber.on('message', (ch, message) => {
+            if (ch !== this.channel)
+                return;
+            if (message === '__all__') {
+                this.flushLocal();
+            }
+            else {
+                this.client.del(this.prefixedKey(message));
+                this.client.del(this.prefixedKey('__all__'));
+            }
+        });
+    }
+    async get(key) {
+        const raw = await this.client.get(this.prefixedKey(key));
+        if (!raw)
+            return null;
+        return JSON.parse(raw);
+    }
+    async set(key, data, ttlMs) {
+        if (ttlMs === 0)
+            return;
+        await this.client.set(this.prefixedKey(key), JSON.stringify(data), 'PX', ttlMs);
+    }
+    async getAll() {
+        const raw = await this.client.get(this.prefixedKey('__all__'));
+        if (!raw)
+            return null;
+        return JSON.parse(raw);
+    }
+    async setAll(data, ttlMs) {
+        if (ttlMs === 0)
+            return;
+        await this.client.set(this.prefixedKey('__all__'), JSON.stringify(data), 'PX', ttlMs);
+    }
+    async invalidate(key) {
+        if (key) {
+            await this.client.del(this.prefixedKey(key));
+            await this.client.del(this.prefixedKey('__all__'));
+            await this.client.publish(this.channel, key);
+        }
+        else {
+            await this.flushLocal();
+            await this.client.publish(this.channel, '__all__');
+        }
+    }
+    async onModuleDestroy() {
+        await this.subscriber.unsubscribe(this.channel);
+        if (this.ownsSubscriber) {
+            await this.subscriber.quit();
+        }
+    }
+    prefixedKey(key) {
+        return `${this.keyPrefix}${key}`;
+    }
+    async flushLocal() {
+        const pattern = `${this.keyPrefix}*`;
+        let cursor = '0';
+        do {
+            const [nextCursor, keys] = await this.client.scan(cursor, 'MATCH', pattern, 'COUNT', 100);
+            cursor = nextCursor;
+            if (keys.length > 0) {
+                await this.client.del(...keys);
+            }
+        } while (cursor !== '0');
+    }
+};
+exports.RedisCacheAdapter = RedisCacheAdapter;
+exports.RedisCacheAdapter = RedisCacheAdapter = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [Object])
+], RedisCacheAdapter);
+//# sourceMappingURL=redis-cache.adapter.js.map

package/dist/cache/redis-cache.adapter.js.map

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

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

@@ -3,3 +3,6 @@ export declare const DEFAULT_CACHE_TTL_MS = 30000;
 export declare const FEATURE_FLAG_KEY = "FEATURE_FLAG_KEY";
 export declare const FEATURE_FLAG_OPTIONS_KEY = "FEATURE_FLAG_OPTIONS_KEY";
 export declare const BYPASS_FEATURE_FLAG_KEY = "BYPASS_FEATURE_FLAG_KEY";
+export declare const CACHE_ADAPTER: unique symbol;
+export declare const FEATURE_FLAG_REPOSITORY: unique symbol;
+export declare const TENANT_CONTEXT_PROVIDER: unique symbol;

package/dist/feature-flag.constants.js

@@ -1,9 +1,12 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.BYPASS_FEATURE_FLAG_KEY = exports.FEATURE_FLAG_OPTIONS_KEY = exports.FEATURE_FLAG_KEY = exports.DEFAULT_CACHE_TTL_MS = exports.FEATURE_FLAG_MODULE_OPTIONS = void 0;
+exports.TENANT_CONTEXT_PROVIDER = exports.FEATURE_FLAG_REPOSITORY = exports.CACHE_ADAPTER = exports.BYPASS_FEATURE_FLAG_KEY = exports.FEATURE_FLAG_OPTIONS_KEY = exports.FEATURE_FLAG_KEY = exports.DEFAULT_CACHE_TTL_MS = exports.FEATURE_FLAG_MODULE_OPTIONS = void 0;
 exports.FEATURE_FLAG_MODULE_OPTIONS = Symbol('FEATURE_FLAG_MODULE_OPTIONS');
 exports.DEFAULT_CACHE_TTL_MS = 30_000;
 exports.FEATURE_FLAG_KEY = 'FEATURE_FLAG_KEY';
 exports.FEATURE_FLAG_OPTIONS_KEY = 'FEATURE_FLAG_OPTIONS_KEY';
 exports.BYPASS_FEATURE_FLAG_KEY = 'BYPASS_FEATURE_FLAG_KEY';
+exports.CACHE_ADAPTER = Symbol('CACHE_ADAPTER');
+exports.FEATURE_FLAG_REPOSITORY = Symbol('FEATURE_FLAG_REPOSITORY');
+exports.TENANT_CONTEXT_PROVIDER = Symbol('TENANT_CONTEXT_PROVIDER');
 //# sourceMappingURL=feature-flag.constants.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"feature-flag.constants.js","sourceRoot":"","sources":["../src/feature-flag.constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,2BAA2B,GAAG,MAAM,CAAC,6BAA6B,CAAC,CAAC;AAEpE,QAAA,oBAAoB,GAAG,MAAM,CAAC;AAE9B,QAAA,gBAAgB,GAAG,kBAAkB,CAAC;AACtC,QAAA,wBAAwB,GAAG,0BAA0B,CAAC;AACtD,QAAA,uBAAuB,GAAG,yBAAyB,CAAC"}
+{"version":3,"file":"feature-flag.constants.js","sourceRoot":"","sources":["../src/feature-flag.constants.ts"],"names":[],"mappings":";;;AAAa,QAAA,2BAA2B,GAAG,MAAM,CAAC,6BAA6B,CAAC,CAAC;AAEpE,QAAA,oBAAoB,GAAG,MAAM,CAAC;AAE9B,QAAA,gBAAgB,GAAG,kBAAkB,CAAC;AACtC,QAAA,wBAAwB,GAAG,0BAA0B,CAAC;AACtD,QAAA,uBAAuB,GAAG,yBAAyB,CAAC;AAEpD,QAAA,aAAa,GAAG,MAAM,CAAC,eAAe,CAAC,CAAC;AACxC,QAAA,uBAAuB,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC;AAC5D,QAAA,uBAAuB,GAAG,MAAM,CAAC,yBAAyB,CAAC,CAAC"}