@nestarc/feature-flag 0.2.0 → 0.4.0

package/dist/services/flag-evaluator.service.js

@@ -9,55 +9,109 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FlagEvaluatorService = void 0;
 const common_1 = require("@nestjs/common");
 const hash_1 = require("../utils/hash");
+const targeting_attributes_1 = require("../utils/targeting-attributes");
 let FlagEvaluatorService = class FlagEvaluatorService {
-    evaluate(flag, context) {
-        // 1. Archived → always false
+    evaluate(flag, context, options = {}) {
         if (flag.archivedAt) {
-            return { result: false, source: 'global' };
-        }
-        // 2. User override (most specific)
-        if (context.userId) {
-            const userOverride = flag.overrides.find((o) => o.userId === context.userId &&
-                (o.tenantId === null || o.tenantId === context.tenantId) &&
-                (o.environment === null || o.environment === context.environment));
-            if (userOverride) {
-                return { result: userOverride.enabled, source: 'user_override' };
-            }
+            return this.result(flag.key, false, 'global', 'ARCHIVED');
         }
-        // 3. Tenant override
-        if (context.tenantId) {
-            const tenantOverride = flag.overrides.find((o) => o.tenantId === context.tenantId &&
-                o.userId === null &&
-                (o.environment === null || o.environment === context.environment));
-            if (tenantOverride) {
-                return { result: tenantOverride.enabled, source: 'tenant_override' };
-            }
+        const override = this.findMatchingOverride(flag.overrides, context);
+        if (override) {
+            return this.result(flag.key, override.enabled, 'override', 'OVERRIDE_MATCH', {
+                matchedOverrideId: override.id,
+            });
         }
-        // 4. Environment override
-        if (context.environment) {
-            const envOverride = flag.overrides.find((o) => o.environment === context.environment && o.tenantId === null && o.userId === null);
-            if (envOverride) {
-                return { result: envOverride.enabled, source: 'env_override' };
-            }
-        }
-        // 5. Percentage rollout
         if (flag.percentage > 0) {
             if (flag.percentage === 100) {
-                return { result: true, source: 'percentage' };
+                return this.result(flag.key, true, 'percentage', 'PERCENTAGE_MATCH');
+            }
+            const targetingKey = this.resolveTargetingKey(flag, context, options.bucketBy);
+            if (!targetingKey) {
+                return this.result(flag.key, flag.enabled, 'global', 'PERCENTAGE_NO_TARGETING_KEY');
             }
-            const hashKey = context.userId ?? context.tenantId ?? '';
-            if (!hashKey) {
-                return { result: flag.enabled, source: 'global' };
+            const bucket = (0, hash_1.murmurhash3)(flag.key + targetingKey) % 100;
+            const enabled = bucket < flag.percentage;
+            return this.result(flag.key, enabled, 'percentage', enabled ? 'PERCENTAGE_MATCH' : 'PERCENTAGE_MISS', { bucket, targetingKey });
+        }
+        return this.result(flag.key, flag.enabled, 'global', 'GLOBAL');
+    }
+    findMatchingOverride(overrides, context) {
+        const contextAttributes = context.attributes ?? {};
+        return (overrides
+            .filter((override) => (0, targeting_attributes_1.matchesTargetingAttributes)(override.attributes, contextAttributes))
+            .sort(compareOverrides)[0] ?? null);
+    }
+    resolveTargetingKey(flag, context, bucketBy) {
+        if (context.targetingKey) {
+            return context.targetingKey;
+        }
+        const configuredBucketBy = bucketBy ?? this.getMetadataBucketBy(flag.metadata);
+        if (configuredBucketBy) {
+            const configuredValue = this.readBucketValue(context, configuredBucketBy);
+            if (configuredValue) {
+                return configuredValue;
             }
-            const bucket = (0, hash_1.murmurhash3)(flag.key + hashKey) % 100;
-            return { result: bucket < flag.percentage, source: 'percentage' };
         }
-        // 6. Global default
-        return { result: flag.enabled, source: 'global' };
+        return context.userId ?? context.tenantId ?? '';
+    }
+    getMetadataBucketBy(metadata) {
+        const bucketBy = metadata.bucketBy;
+        return typeof bucketBy === 'string' && bucketBy.length > 0 ? bucketBy : undefined;
+    }
+    readBucketValue(context, bucketBy) {
+        if (bucketBy === 'userId') {
+            return context.userId ?? '';
+        }
+        if (bucketBy === 'tenantId') {
+            return context.tenantId ?? '';
+        }
+        if (bucketBy === 'environment') {
+            return context.environment ?? '';
+        }
+        if (bucketBy === 'targetingKey') {
+            return context.targetingKey ?? '';
+        }
+        return stringifyBucketValue(context.attributes?.[bucketBy]);
+    }
+    result(flagKey, value, source, reason, details = {}) {
+        return {
+            flagKey,
+            value,
+            result: value,
+            source,
+            reason,
+            defaultUsed: false,
+            ...details,
+        };
     }
 };
 exports.FlagEvaluatorService = FlagEvaluatorService;
 exports.FlagEvaluatorService = FlagEvaluatorService = __decorate([
     (0, common_1.Injectable)()
 ], FlagEvaluatorService);
+function stringifyBucketValue(value) {
+    if (value === undefined || value === null) {
+        return '';
+    }
+    return String(value);
+}
+function compareOverrides(a, b) {
+    const specificityDelta = Object.keys(b.attributes).length - Object.keys(a.attributes).length;
+    if (specificityDelta !== 0) {
+        return specificityDelta;
+    }
+    const priorityDelta = b.priority - a.priority;
+    if (priorityDelta !== 0) {
+        return priorityDelta;
+    }
+    const createdAtDelta = getOverrideCreatedAtTime(a) - getOverrideCreatedAtTime(b);
+    if (createdAtDelta !== 0) {
+        return createdAtDelta;
+    }
+    return a.id.localeCompare(b.id);
+}
+function getOverrideCreatedAtTime(override) {
+    const createdAt = override.createdAt;
+    return createdAt instanceof Date ? createdAt.getTime() : new Date(createdAt).getTime();
+}
 //# sourceMappingURL=flag-evaluator.service.js.map

package/dist/services/flag-evaluator.service.js.map

@@ -1 +1 @@
-{"version":3,"file":"flag-evaluator.service.js","sourceRoot":"","sources":["../../src/services/flag-evaluator.service.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"flag-evaluator.service.js","sourceRoot":"","sources":["../../src/services/flag-evaluator.service.ts"],"names":[],"mappings":";;;;;;;;;AAAA,2CAA4C;AAO5C,wCAA4C;AAC5C,wEAA2E;AAWpE,IAAM,oBAAoB,GAA1B,MAAM,oBAAoB;IAC/B,QAAQ,CACN,IAA8B,EAC9B,OAA0B,EAC1B,UAAgC,EAAE;QAElC,IAAI,IAAI,CAAC,UAAU,EAAE,CAAC;YACpB,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;QAC5D,CAAC;QAED,MAAM,QAAQ,GAAG,IAAI,CAAC,oBAAoB,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;QACpE,IAAI,QAAQ,EAAE,CAAC;YACb,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE;gBAC3E,iBAAiB,EAAE,QAAQ,CAAC,EAAE;aAC/B,CAAC,CAAC;QACL,CAAC;QAED,IAAI,IAAI,CAAC,UAAU,GAAG,CAAC,EAAE,CAAC;YACxB,IAAI,IAAI,CAAC,UAAU,KAAK,GAAG,EAAE,CAAC;gBAC5B,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,EAAE,YAAY,EAAE,kBAAkB,CAAC,CAAC;YACvE,CAAC;YAED,MAAM,YAAY,GAAG,IAAI,CAAC,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;YAC/E,IAAI,CAAC,YAAY,EAAE,CAAC;gBAClB,OAAO,IAAI,CAAC,MAAM,CAChB,IAAI,CAAC,GAAG,EACR,IAAI,CAAC,OAAO,EACZ,QAAQ,EACR,6BAA6B,CAC9B,CAAC;YACJ,CAAC;YAED,MAAM,MAAM,GAAG,IAAA,kBAAW,EAAC,IAAI,CAAC,GAAG,GAAG,YAAY,CAAC,GAAG,GAAG,CAAC;YAC1D,MAAM,OAAO,GAAG,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC;YACzC,OAAO,IAAI,CAAC,MAAM,CAChB,IAAI,CAAC,GAAG,EACR,OAAO,EACP,YAAY,EACZ,OAAO,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,iBAAiB,EAChD,EAAE,MAAM,EAAE,YAAY,EAAE,CACzB,CAAC;QACJ,CAAC;QAED,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IACjE,CAAC;IAEO,oBAAoB,CAC1B,SAAyB,EACzB,OAA0B;QAE1B,MAAM,iBAAiB,GAAG,OAAO,CAAC,UAAU,IAAI,EAAE,CAAC;QAEnD,OAAO,CACL,SAAS;aACN,MAAM,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAA,iDAA0B,EAAC,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC,CAAC;aACxF,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CACrC,CAAC;IACJ,CAAC;IAEO,mBAAmB,CACzB,IAA8B,EAC9B,OAA0B,EAC1B,QAAmB;QAEnB,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;YACzB,OAAO,OAAO,CAAC,YAAY,CAAC;QAC9B,CAAC;QAED,MAAM,kBAAkB,GAAG,QAAQ,IAAI,IAAI,CAAC,mBAAmB,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAC/E,IAAI,kBAAkB,EAAE,CAAC;YACvB,MAAM,eAAe,GAAG,IAAI,CAAC,eAAe,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC;YAC1E,IAAI,eAAe,EAAE,CAAC;gBACpB,OAAO,eAAe,CAAC;YACzB,CAAC;QACH,CAAC;QAED,OAAO,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;IAClD,CAAC;IAEO,mBAAmB,CAAC,QAAiC;QAC3D,MAAM,QAAQ,GAAG,QAAQ,CAAC,QAAQ,CAAC;QACnC,OAAO,OAAO,QAAQ,KAAK,QAAQ,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IACpF,CAAC;IAEO,eAAe,CAAC,OAA0B,EAAE,QAAkB;QACpE,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;YAC1B,OAAO,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;QAC9B,CAAC;QACD,IAAI,QAAQ,KAAK,UAAU,EAAE,CAAC;YAC5B,OAAO,OAAO,CAAC,QAAQ,IAAI,EAAE,CAAC;QAChC,CAAC;QACD,IAAI,QAAQ,KAAK,aAAa,EAAE,CAAC;YAC/B,OAAO,OAAO,CAAC,WAAW,IAAI,EAAE,CAAC;QACnC,CAAC;QACD,IAAI,QAAQ,KAAK,cAAc,EAAE,CAAC;YAChC,OAAO,OAAO,CAAC,YAAY,IAAI,EAAE,CAAC;QACpC,CAAC;QAED,OAAO,oBAAoB,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAC9D,CAAC;IAEO,MAAM,CACZ,OAAe,EACf,KAAc,EACd,MAAwB,EACxB,MAAkC,EAClC,UAAqC,EAAE;QAEvC,OAAO;YACL,OAAO;YACP,KAAK;YACL,MAAM,EAAE,KAAK;YACb,MAAM;YACN,MAAM;YACN,WAAW,EAAE,KAAK;YAClB,GAAG,OAAO;SACX,CAAC;IACJ,CAAC;CACF,CAAA;AAtHY,oDAAoB;+BAApB,oBAAoB;IADhC,IAAA,mBAAU,GAAE;GACA,oBAAoB,CAsHhC;AAED,SAAS,oBAAoB,CAAC,KAA0C;IACtE,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;QAC1C,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,SAAS,gBAAgB,CAAC,CAAe,EAAE,CAAe;IACxD,MAAM,gBAAgB,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,MAAM,CAAC;IAC7F,IAAI,gBAAgB,KAAK,CAAC,EAAE,CAAC;QAC3B,OAAO,gBAAgB,CAAC;IAC1B,CAAC;IAED,MAAM,aAAa,GAAG,CAAC,CAAC,QAAQ,GAAG,CAAC,CAAC,QAAQ,CAAC;IAC9C,IAAI,aAAa,KAAK,CAAC,EAAE,CAAC;QACxB,OAAO,aAAa,CAAC;IACvB,CAAC;IAED,MAAM,cAAc,GAAG,wBAAwB,CAAC,CAAC,CAAC,GAAG,wBAAwB,CAAC,CAAC,CAAC,CAAC;IACjF,IAAI,cAAc,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,cAAc,CAAC;IACxB,CAAC;IAED,OAAO,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AAClC,CAAC;AAED,SAAS,wBAAwB,CAAC,QAAsB;IACtD,MAAM,SAAS,GAAG,QAAQ,CAAC,SAA0B,CAAC;IACtD,OAAO,SAAS,YAAY,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC,OAAO,EAAE,CAAC;AACzF,CAAC"}

package/dist/testing/index.d.ts

@@ -1 +1 @@
-export { TestFeatureFlagModule } from './test-feature-flag.module';
+export { TestFeatureFlagController, TestFeatureFlagModule, TestFeatureFlagRegistryOptions, } from './test-feature-flag.module';

package/dist/testing/index.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TestFeatureFlagModule = void 0;
+exports.TestFeatureFlagModule = exports.TestFeatureFlagController = void 0;
 var test_feature_flag_module_1 = require("./test-feature-flag.module");
+Object.defineProperty(exports, "TestFeatureFlagController", { enumerable: true, get: function () { return test_feature_flag_module_1.TestFeatureFlagController; } });
 Object.defineProperty(exports, "TestFeatureFlagModule", { enumerable: true, get: function () { return test_feature_flag_module_1.TestFeatureFlagModule; } });
 //# sourceMappingURL=index.js.map

package/dist/testing/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";;;AAAA,uEAAmE;AAA1D,iIAAA,qBAAqB,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":";;;AAAA,uEAIoC;AAHlC,qIAAA,yBAAyB,OAAA;AACzB,iIAAA,qBAAqB,OAAA"}

package/dist/testing/test-feature-flag.module.d.ts

@@ -1,4 +1,25 @@
 import { DynamicModule } from '@nestjs/common';
+import { FeatureFlagWithOverrides } from '../interfaces/feature-flag.interface';
+import { BooleanEvaluationDetails, EvaluateBooleanOptions } from '../interfaces/evaluation-details.interface';
+import { FlagKey, FlagRegistry } from '../interfaces/flag-registry.interface';
 export declare class TestFeatureFlagModule {
     static register(flags?: Record<string, boolean>): DynamicModule;
+    static registerRegistry<TFlags extends FlagRegistry>(flags: TFlags, options?: TestFeatureFlagRegistryOptions<TFlags>): DynamicModule;
+    private static createModule;
+}
+export interface TestFeatureFlagRegistryOptions<TFlags extends FlagRegistry> {
+    overrides?: Partial<Record<FlagKey<TFlags>, boolean>>;
+}
+export declare class TestFeatureFlagController<TFlags extends FlagRegistry = FlagRegistry> {
+    private readonly defaults;
+    private values;
+    constructor(defaults: Record<string, boolean>, overrides?: Partial<Record<FlagKey<TFlags>, boolean>>);
+    set<K extends FlagKey<TFlags>>(key: K, value: boolean): void;
+    reset(): void;
+    isEnabled(key: string, options?: EvaluateBooleanOptions): boolean;
+    evaluateAll(): Record<string, boolean>;
+    getDetails(key: string, options?: EvaluateBooleanOptions): BooleanEvaluationDetails;
+    findFlag(key: string): FeatureFlagWithOverrides;
+    findAll(): FeatureFlagWithOverrides[];
+    private getValue;
 }

package/dist/testing/test-feature-flag.module.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 var TestFeatureFlagModule_1;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.TestFeatureFlagModule = void 0;
+exports.TestFeatureFlagController = exports.TestFeatureFlagModule = void 0;
 const common_1 = require("@nestjs/common");
 const feature_flag_service_1 = require("../services/feature-flag.service");
 function makeStubFlag(partial = {}) {
@@ -26,32 +26,29 @@ function makeStubFlag(partial = {}) {
 }
 let TestFeatureFlagModule = TestFeatureFlagModule_1 = class TestFeatureFlagModule {
     static register(flags) {
+        const controller = new TestFeatureFlagController(flags ?? {});
+        return this.createModule(controller);
+    }
+    static registerRegistry(flags, options = {}) {
+        const defaults = Object.fromEntries(Object.entries(flags).map(([key, definition]) => [key, definition.defaultValue]));
+        const controller = new TestFeatureFlagController(defaults, options.overrides);
+        return this.createModule(controller);
+    }
+    static createModule(controller) {
         return {
             module: TestFeatureFlagModule_1,
             global: true,
             providers: [
+                {
+                    provide: TestFeatureFlagController,
+                    useValue: controller,
+                },
                 {
                     provide: feature_flag_service_1.FeatureFlagService,
-                    useValue: {
-                        isEnabled: async (key) => flags?.[key] ?? false,
-                        evaluateAll: async () => flags ?? {},
-                        create: async (input) => makeStubFlag({ key: input.key, enabled: input.enabled ?? false }),
-                        update: async (key, input) => makeStubFlag({ key, ...input }),
-                        archive: async (key) => makeStubFlag({ key, archivedAt: new Date() }),
-                        setOverride: async () => { },
-                        removeOverride: async () => { },
-                        findAll: async () => Object.entries(flags ?? {}).map(([key, enabled]) => makeStubFlag({ key, enabled })),
-                        findByKey: async (key) => {
-                            if (flags && key in flags) {
-                                return makeStubFlag({ key, enabled: flags[key] });
-                            }
-                            throw new common_1.NotFoundException(`Feature flag "${key}" not found`);
-                        },
-                        invalidateCache: async () => { },
-                    },
+                    useValue: createFeatureFlagServiceStub(controller),
                 },
             ],
-            exports: [feature_flag_service_1.FeatureFlagService],
+            exports: [feature_flag_service_1.FeatureFlagService, TestFeatureFlagController],
         };
     }
 };
@@ -59,4 +56,66 @@ exports.TestFeatureFlagModule = TestFeatureFlagModule;
 exports.TestFeatureFlagModule = TestFeatureFlagModule = TestFeatureFlagModule_1 = __decorate([
     (0, common_1.Module)({})
 ], TestFeatureFlagModule);
+class TestFeatureFlagController {
+    constructor(defaults, overrides = {}) {
+        this.defaults = { ...defaults };
+        this.values = { ...defaults, ...overrides };
+    }
+    set(key, value) {
+        this.values[key] = value;
+    }
+    reset() {
+        this.values = { ...this.defaults };
+    }
+    isEnabled(key, options = {}) {
+        return this.getValue(key, options);
+    }
+    evaluateAll() {
+        return { ...this.values };
+    }
+    getDetails(key, options = {}) {
+        const hasValue = Object.prototype.hasOwnProperty.call(this.values, key);
+        const value = this.getValue(key, options);
+        return {
+            flagKey: key,
+            value,
+            result: value,
+            source: hasValue ? 'default' : 'default',
+            reason: hasValue ? 'GLOBAL' : 'FLAG_NOT_FOUND',
+            defaultUsed: !hasValue,
+            evaluationTimeMs: 0,
+        };
+    }
+    findFlag(key) {
+        if (!Object.prototype.hasOwnProperty.call(this.values, key)) {
+            throw new common_1.NotFoundException(`Feature flag "${key}" not found`);
+        }
+        return makeStubFlag({ key, enabled: this.values[key] });
+    }
+    findAll() {
+        return Object.entries(this.values).map(([key, enabled]) => makeStubFlag({ key, enabled }));
+    }
+    getValue(key, options) {
+        if (Object.prototype.hasOwnProperty.call(this.values, key)) {
+            return this.values[key];
+        }
+        return options.defaultValue ?? false;
+    }
+}
+exports.TestFeatureFlagController = TestFeatureFlagController;
+function createFeatureFlagServiceStub(controller) {
+    return {
+        isEnabled: async (key, _context, options = {}) => controller.isEnabled(key, options),
+        evaluateBoolean: async (key, _context, options = {}) => controller.getDetails(key, options),
+        evaluateAll: async () => controller.evaluateAll(),
+        create: async (input) => makeStubFlag({ key: input.key, enabled: input.enabled ?? false }),
+        update: async (key, input) => makeStubFlag({ key, ...input }),
+        archive: async (key) => makeStubFlag({ key, archivedAt: new Date() }),
+        setOverride: async () => { },
+        removeOverride: async () => { },
+        findAll: async () => controller.findAll(),
+        findByKey: async (key) => controller.findFlag(key),
+        invalidateCache: async () => { },
+    };
+}
 //# sourceMappingURL=test-feature-flag.module.js.map

package/dist/testing/test-feature-flag.module.js.map

@@ -1 +1 @@
-{"version":3,"file":"test-feature-flag.module.js","sourceRoot":"","sources":["../../src/testing/test-feature-flag.module.ts"],"names":[],"mappings":";;;;;;;;;;AAAA,2CAA0E;AAC1E,2EAAsE;AAMtE,SAAS,YAAY,CACnB,UAA6C,EAAE;IAE/C,OAAO;QACL,EAAE,EAAE,OAAO,CAAC,EAAE,IAAI,SAAS;QAC3B,GAAG,EAAE,OAAO,CAAC,GAAG,IAAI,MAAM;QAC1B,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,OAAO,EAAE,OAAO,CAAC,OAAO,IAAI,KAAK;QACjC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,CAAC;QACnC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,EAAE;QAChC,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;QACtC,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,IAAI,CAAC,YAAY,CAAC;QACtD,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,IAAI,IAAI,CAAC,YAAY,CAAC;QACtD,SAAS,EAAE,OAAO,CAAC,SAAS,IAAI,EAAE;KACnC,CAAC;AACJ,CAAC;AAGM,IAAM,qBAAqB,6BAA3B,MAAM,qBAAqB;IAChC,MAAM,CAAC,QAAQ,CAAC,KAA+B;QAC7C,OAAO;YACL,MAAM,EAAE,uBAAqB;YAC7B,MAAM,EAAE,IAAI;YACZ,SAAS,EAAE;gBACT;oBACE,OAAO,EAAE,yCAAkB;oBAC3B,QAAQ,EAAE;wBACR,SAAS,EAAE,KAAK,EAAE,GAAW,EAAE,EAAE,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,IAAI,KAAK;wBACvD,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK,IAAI,EAAE;wBACpC,MAAM,EAAE,KAAK,EAAE,KAA6B,EAAE,EAAE,CAC9C,YAAY,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,KAAK,EAAE,CAAC;wBACnE,MAAM,EAAE,KAAK,EAAE,GAAW,EAAE,KAAwC,EAAE,EAAE,CACtE,YAAY,CAAC,EAAE,GAAG,EAAE,GAAG,KAAK,EAAE,CAAC;wBACjC,OAAO,EAAE,KAAK,EAAE,GAAW,EAAE,EAAE,CAC7B,YAAY,CAAC,EAAE,GAAG,EAAE,UAAU,EAAE,IAAI,IAAI,EAAE,EAAE,CAAC;wBAC/C,WAAW,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;wBAC3B,cAAc,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;wBAC9B,OAAO,EAAE,KAAK,IAAI,EAAE,CAClB,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,OAAO,CAAC,EAAE,EAAE,CACjD,YAAY,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,CAAC,CAC/B;wBACH,SAAS,EAAE,KAAK,EAAE,GAAW,EAAE,EAAE;4BAC/B,IAAI,KAAK,IAAI,GAAG,IAAI,KAAK,EAAE,CAAC;gCAC1B,OAAO,YAAY,CAAC,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;4BACpD,CAAC;4BACD,MAAM,IAAI,0BAAiB,CAAC,iBAAiB,GAAG,aAAa,CAAC,CAAC;wBACjE,CAAC;wBACD,eAAe,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;qBAChC;iBACF;aACF;YACD,OAAO,EAAE,CAAC,yCAAkB,CAAC;SAC9B,CAAC;IACJ,CAAC;CACF,CAAA;AApCY,sDAAqB;gCAArB,qBAAqB;IADjC,IAAA,eAAM,EAAC,EAAE,CAAC;GACE,qBAAqB,CAoCjC"}
+{"version":3,"file":"test-feature-flag.module.js","sourceRoot":"","sources":["../../src/testing/test-feature-flag.module.ts"],"names":[],"mappings":"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"}

package/dist/utils/targeting-attributes.d.ts

@@ -0,0 +1,9 @@
+import { TargetingAttributes, TargetingAttributeValue } from '../interfaces/feature-flag.interface';
+interface AttributeValidationOptions {
+    allowEmpty: boolean;
+}
+export declare function isTargetingAttributeValue(value: unknown): value is TargetingAttributeValue;
+export declare function isTargetingAttributes(value: unknown, options?: AttributeValidationOptions): value is TargetingAttributes;
+export declare function normalizeTargetingAttributes(value: unknown, options?: AttributeValidationOptions): TargetingAttributes;
+export declare function matchesTargetingAttributes(overrideAttributes: TargetingAttributes, contextAttributes: TargetingAttributes): boolean;
+export {};

package/dist/utils/targeting-attributes.js

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTargetingAttributeValue = isTargetingAttributeValue;
+exports.isTargetingAttributes = isTargetingAttributes;
+exports.normalizeTargetingAttributes = normalizeTargetingAttributes;
+exports.matchesTargetingAttributes = matchesTargetingAttributes;
+const INVALID_ATTRIBUTES_MESSAGE = 'attributes must be a non-empty object with string, number, boolean, or null values';
+function isTargetingAttributeValue(value) {
+    return (value === null ||
+        typeof value === 'string' ||
+        (typeof value === 'number' && Number.isFinite(value)) ||
+        typeof value === 'boolean');
+}
+function isTargetingAttributes(value, options = { allowEmpty: false }) {
+    if (!isPlainObject(value)) {
+        return false;
+    }
+    const entries = Object.entries(value);
+    if (!options.allowEmpty && entries.length === 0) {
+        return false;
+    }
+    return entries.every(([, attributeValue]) => isTargetingAttributeValue(attributeValue));
+}
+function normalizeTargetingAttributes(value, options = { allowEmpty: false }) {
+    if (!isTargetingAttributes(value, options)) {
+        throw new Error(INVALID_ATTRIBUTES_MESSAGE);
+    }
+    return { ...value };
+}
+function matchesTargetingAttributes(overrideAttributes, contextAttributes) {
+    const entries = Object.entries(overrideAttributes);
+    if (entries.length === 0) {
+        return false;
+    }
+    return entries.every(([key, value]) => contextAttributes[key] === value);
+}
+function isPlainObject(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+//# sourceMappingURL=targeting-attributes.js.map

package/dist/utils/targeting-attributes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"targeting-attributes.js","sourceRoot":"","sources":["../../src/utils/targeting-attributes.ts"],"names":[],"mappings":";;AAYA,8DAOC;AAED,sDAcC;AAED,oEASC;AAED,gEAUC;AAjDD,MAAM,0BAA0B,GAC9B,oFAAoF,CAAC;AAEvF,SAAgB,yBAAyB,CAAC,KAAc;IACtD,OAAO,CACL,KAAK,KAAK,IAAI;QACd,OAAO,KAAK,KAAK,QAAQ;QACzB,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;QACrD,OAAO,KAAK,KAAK,SAAS,CAC3B,CAAC;AACJ,CAAC;AAED,SAAgB,qBAAqB,CACnC,KAAc,EACd,UAAsC,EAAE,UAAU,EAAE,KAAK,EAAE;IAE3D,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;IACtC,IAAI,CAAC,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAChD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,cAAc,CAAC,EAAE,EAAE,CAAC,yBAAyB,CAAC,cAAc,CAAC,CAAC,CAAC;AAC1F,CAAC;AAED,SAAgB,4BAA4B,CAC1C,KAAc,EACd,UAAsC,EAAE,UAAU,EAAE,KAAK,EAAE;IAE3D,IAAI,CAAC,qBAAqB,CAAC,KAAK,EAAE,OAAO,CAAC,EAAE,CAAC;QAC3C,MAAM,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAC;IAC9C,CAAC;IAED,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC;AACtB,CAAC;AAED,SAAgB,0BAA0B,CACxC,kBAAuC,EACvC,iBAAsC;IAEtC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACnD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC;IACf,CAAC;IAED,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE,CAAC,iBAAiB,CAAC,GAAG,CAAC,KAAK,KAAK,CAAC,CAAC;AAC3E,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACxE,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC/C,OAAO,SAAS,KAAK,MAAM,CAAC,SAAS,IAAI,SAAS,KAAK,IAAI,CAAC;AAC9D,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nestarc/feature-flag",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "DB-backed feature flags for NestJS + Prisma + PostgreSQL with tenant-aware overrides",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -12,6 +12,10 @@
     "./testing": {
       "types": "./dist/testing/index.d.ts",
       "default": "./dist/testing/index.js"
+    },
+    "./openfeature": {
+      "types": "./dist/openfeature.d.ts",
+      "default": "./dist/openfeature.js"
     }
   },
   "files": [
@@ -35,7 +39,7 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/nestarc/nestjs-feature-flag"
+    "url": "git+https://github.com/nestarc/nestjs-feature-flag.git"
   },
   "keywords": [
     "nestjs",
@@ -55,7 +59,10 @@
   "peerDependencies": {
     "@nestjs/common": "^10.0.0 || ^11.0.0",
     "@nestjs/core": "^10.0.0 || ^11.0.0",
+    "@openfeature/server-sdk": "^1.0.0",
     "@prisma/client": "^5.0.0 || ^6.0.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.14.0 || ^0.15.0",
     "ioredis": "^5.0.0",
     "reflect-metadata": "^0.1.13 || ^0.2.0",
     "rxjs": "^7.0.0"
@@ -67,10 +74,17 @@
     "@nestjs/event-emitter": {
       "optional": true
     },
+    "@openfeature/server-sdk": {
+      "optional": true
+    },
     "ioredis": {
       "optional": true
     }
   },
+  "overrides": {
+    "js-yaml": "4.2.0",
+    "multer": "2.2.0"
+  },
   "devDependencies": {
     "@eslint/js": "^9.0.0",
     "@nestjs/common": "^11.0.0",
@@ -83,6 +97,8 @@
     "@types/ioredis-mock": "^8.2.7",
     "@types/jest": "^29.5.0",
     "@types/supertest": "^7.2.0",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
     "dotenv-cli": "^11.0.0",
     "eslint": "^9.0.0",
     "ioredis": "^5.10.1",

package/prisma/migrations/20260512000000_attribute_targeting/migration.sql

@@ -0,0 +1,59 @@
+ALTER TABLE "feature_flag_overrides"
+  ADD COLUMN "attributes" JSONB NOT NULL DEFAULT '{}',
+  ADD COLUMN "priority" INTEGER NOT NULL DEFAULT 0;
+
+ALTER TABLE "feature_flag_overrides"
+  ALTER COLUMN "updated_at" SET DEFAULT CURRENT_TIMESTAMP;
+
+UPDATE "feature_flag_overrides"
+SET "attributes" = jsonb_strip_nulls(
+  jsonb_build_object(
+    'tenantId', "tenant_id",
+    'userId', "user_id",
+    'environment', "environment"
+  )
+);
+
+-- v0.3.0 rejects empty targeting attributes. Legacy all-null/global overrides
+-- become empty objects during backfill and are intentionally removed by this
+-- breaking migration.
+DELETE FROM "feature_flag_overrides"
+WHERE "attributes" = '{}'::jsonb;
+
+WITH ranked_overrides AS (
+  SELECT
+    "id",
+    row_number() OVER (
+      PARTITION BY "flag_id", "attributes"
+      ORDER BY "updated_at" DESC, "created_at" DESC, "id" DESC
+    ) AS row_number
+  FROM "feature_flag_overrides"
+)
+DELETE FROM "feature_flag_overrides" target
+USING ranked_overrides ranked
+WHERE target."id" = ranked."id"
+  AND ranked.row_number > 1;
+
+DROP INDEX IF EXISTS "uq_override_000";
+DROP INDEX IF EXISTS "uq_override_001";
+DROP INDEX IF EXISTS "uq_override_010";
+DROP INDEX IF EXISTS "uq_override_011";
+DROP INDEX IF EXISTS "uq_override_100";
+DROP INDEX IF EXISTS "uq_override_101";
+DROP INDEX IF EXISTS "uq_override_110";
+DROP INDEX IF EXISTS "uq_override_111";
+
+ALTER TABLE "feature_flag_overrides"
+  DROP COLUMN "tenant_id",
+  DROP COLUMN "user_id",
+  DROP COLUMN "environment";
+
+ALTER TABLE "feature_flag_overrides"
+  ALTER COLUMN "attributes" DROP DEFAULT;
+
+CREATE UNIQUE INDEX "uq_feature_flag_override_attributes"
+  ON "feature_flag_overrides"("flag_id", "attributes");
+
+ALTER TABLE "feature_flag_overrides"
+  ADD CONSTRAINT "chk_feature_flag_override_attributes_non_empty"
+  CHECK (jsonb_typeof("attributes") = 'object' AND "attributes" <> '{}'::jsonb);

package/prisma/schema.prisma

@@ -24,18 +24,16 @@ model FeatureFlag {
 }
 
 model FeatureFlagOverride {
-  id          String   @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
-  flagId      String   @map("flag_id") @db.Uuid
-  tenantId    String?  @map("tenant_id")
-  userId      String?  @map("user_id")
-  environment String?
-  enabled     Boolean
-  createdAt   DateTime @default(now()) @map("created_at") @db.Timestamptz()
-  updatedAt   DateTime @updatedAt @map("updated_at") @db.Timestamptz()
+  id         String   @id @default(dbgenerated("gen_random_uuid()")) @db.Uuid
+  flagId     String   @map("flag_id") @db.Uuid
+  attributes Json
+  priority   Int      @default(0)
+  enabled    Boolean
+  createdAt  DateTime @default(now()) @map("created_at") @db.Timestamptz()
+  updatedAt  DateTime @updatedAt @map("updated_at") @db.Timestamptz()
 
   flag FeatureFlag @relation(fields: [flagId], references: [id], onDelete: Cascade)
 
-  // Unique indexes defined in raw SQL migration (0001) to handle NULL equality correctly
   @@index([flagId], map: "idx_override_flag_id")
   @@map("feature_flag_overrides")
 }