@nestarc/feature-flag 0.3.0 → 0.5.0

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 & {

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

@@ -23,6 +23,8 @@ export interface FeatureFlagGuardOptions {
     statusCode?: number;
     /** Response body when flag is OFF */
     fallback?: Record<string, unknown>;
+    /** Invocation-level default when the guard cannot find or evaluate the flag. Default: false */
+    defaultValue?: boolean;
 }
 export interface FeatureFlagWithOverrides {
     id: string;
@@ -48,3 +50,10 @@ export interface FlagOverride {
 export interface RemoveOverrideInput {
     attributes: TargetingAttributes;
 }
+export interface FlagMutationMetadata {
+    actorId?: string;
+    actorType?: string;
+    reason?: string;
+    requestId?: string;
+    correlationId?: string;
+}

package/dist/interfaces/flag-registry.interface.d.ts

@@ -0,0 +1,17 @@
+import { BucketBy } from './evaluation-details.interface';
+export type FeatureFlagType = 'release' | 'experiment' | 'ops' | 'permission';
+export interface FeatureFlagLifecycleMetadata {
+    type?: FeatureFlagType;
+    owner?: string;
+    tags?: readonly string[];
+    expiresAt?: string | Date;
+    staleAt?: string | Date;
+}
+export interface FlagDefinition extends FeatureFlagLifecycleMetadata {
+    defaultValue: boolean;
+    description?: string;
+    bucketBy?: BucketBy;
+    trackExposure?: boolean;
+}
+export type FlagRegistry = Record<string, FlagDefinition>;
+export type FlagKey<TFlags extends FlagRegistry> = Extract<keyof TFlags, string>;

package/dist/interfaces/flag-registry.interface.js

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

package/dist/interfaces/flag-registry.interface.js.map

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

package/dist/openfeature.d.ts

@@ -0,0 +1,26 @@
+import { FeatureFlagService } from './services/feature-flag.service';
+export interface OpenFeatureBooleanProviderOptions {
+    name?: string;
+}
+export interface OpenFeatureEvaluationContext {
+    targetingKey?: unknown;
+    userId?: unknown;
+    tenantId?: unknown;
+    environment?: unknown;
+    [key: string]: unknown;
+}
+export interface OpenFeatureBooleanResolutionDetails {
+    value: boolean;
+    reason: string;
+    variant?: string;
+    errorCode?: string;
+    errorMessage?: string;
+    flagMetadata: Record<string, unknown>;
+}
+export interface OpenFeatureBooleanProvider {
+    metadata: {
+        name: string;
+    };
+    resolveBooleanEvaluation(flagKey: string, defaultValue: boolean, context: OpenFeatureEvaluationContext): Promise<OpenFeatureBooleanResolutionDetails>;
+}
+export declare function createOpenFeatureBooleanProvider(service: FeatureFlagService, options?: OpenFeatureBooleanProviderOptions): OpenFeatureBooleanProvider;

package/dist/openfeature.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createOpenFeatureBooleanProvider = createOpenFeatureBooleanProvider;
+const targeting_attributes_1 = require("./utils/targeting-attributes");
+function createOpenFeatureBooleanProvider(service, options = {}) {
+    return {
+        metadata: {
+            name: options.name ?? '@nestarc/feature-flag',
+        },
+        resolveBooleanEvaluation: async (flagKey, defaultValue, context) => {
+            try {
+                const details = await service.evaluateBoolean(flagKey, toEvaluationContext(context), { defaultValue });
+                return toOpenFeatureResolution(details);
+            }
+            catch (error) {
+                return {
+                    value: defaultValue,
+                    reason: 'ERROR',
+                    errorCode: error instanceof Error ? error.constructor.name : 'Error',
+                    errorMessage: error instanceof Error ? error.message : String(error),
+                    flagMetadata: {
+                        source: 'default',
+                        localReason: 'ERROR',
+                        defaultUsed: true,
+                    },
+                };
+            }
+        },
+    };
+}
+function toEvaluationContext(context) {
+    const attributes = {};
+    for (const [key, value] of Object.entries(context)) {
+        if (isKnownContextKey(key)) {
+            continue;
+        }
+        if ((0, targeting_attributes_1.isTargetingAttributeValue)(value)) {
+            attributes[key] = value;
+        }
+    }
+    return {
+        targetingKey: readString(context.targetingKey),
+        userId: readString(context.userId),
+        tenantId: readString(context.tenantId),
+        environment: readString(context.environment) ?? undefined,
+        attributes,
+    };
+}
+function toOpenFeatureResolution(details) {
+    return {
+        value: details.value,
+        reason: mapOpenFeatureReason(details.reason),
+        errorCode: details.errorCode,
+        errorMessage: details.errorMessage,
+        flagMetadata: {
+            source: details.source,
+            localReason: details.reason,
+            defaultUsed: details.defaultUsed,
+            matchedOverrideId: details.matchedOverrideId,
+            bucket: details.bucket,
+            targetingKey: details.targetingKey,
+            evaluationTimeMs: details.evaluationTimeMs,
+        },
+    };
+}
+function mapOpenFeatureReason(reason) {
+    switch (reason) {
+        case 'OVERRIDE_MATCH':
+            return 'TARGETING_MATCH';
+        case 'PERCENTAGE_MATCH':
+        case 'PERCENTAGE_MISS':
+            return 'SPLIT';
+        case 'FLAG_NOT_FOUND':
+        case 'PERCENTAGE_NO_TARGETING_KEY':
+            return 'DEFAULT';
+        case 'ERROR':
+            return 'ERROR';
+        case 'ARCHIVED':
+            return 'DISABLED';
+        case 'GLOBAL':
+            return 'STATIC';
+    }
+}
+function isKnownContextKey(key) {
+    return (key === 'targetingKey' ||
+        key === 'userId' ||
+        key === 'tenantId' ||
+        key === 'environment');
+}
+function readString(value) {
+    if (value === null) {
+        return null;
+    }
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+//# sourceMappingURL=openfeature.js.map

package/dist/openfeature.js.map

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

package/dist/services/feature-flag.service.d.ts

@@ -1,11 +1,12 @@
 import { FeatureFlagModuleOptions } from '../interfaces/feature-flag-options.interface';
-import { CreateFeatureFlagInput, UpdateFeatureFlagInput, SetOverrideInput, RemoveOverrideInput, FeatureFlagWithOverrides } from '../interfaces/feature-flag.interface';
+import { CreateFeatureFlagInput, UpdateFeatureFlagInput, SetOverrideInput, RemoveOverrideInput, FeatureFlagWithOverrides, FlagMutationMetadata } from '../interfaces/feature-flag.interface';
 import { EvaluationContext } from '../interfaces/evaluation-context.interface';
 import { CacheAdapter } from '../interfaces/cache-adapter.interface';
 import { FeatureFlagRepository } from '../interfaces/feature-flag-repository.interface';
 import { FlagEvaluatorService } from './flag-evaluator.service';
 import { FlagContextResolver } from './flag-context-resolver';
 import { FlagEventPublisher } from './flag-event-publisher';
+import { BooleanEvaluationDetails, EvaluateBooleanOptions } from '../interfaces/evaluation-details.interface';
 export declare class FeatureFlagService {
     private readonly options;
     private readonly repository;
@@ -15,16 +16,17 @@ export declare class FeatureFlagService {
     private readonly eventPublisher;
     constructor(options: FeatureFlagModuleOptions, repository: FeatureFlagRepository, cacheAdapter: CacheAdapter, evaluator: FlagEvaluatorService, contextResolver: FlagContextResolver, eventPublisher: FlagEventPublisher);
     private get cacheTtlMs();
-    isEnabled(flagKey: string, explicitContext?: EvaluationContext): Promise<boolean>;
+    isEnabled(flagKey: string, explicitContext?: EvaluationContext, evaluationOptions?: EvaluateBooleanOptions): Promise<boolean>;
+    evaluateBoolean(flagKey: string, explicitContext?: EvaluationContext, evaluationOptions?: EvaluateBooleanOptions): Promise<BooleanEvaluationDetails>;
     evaluateAll(explicitContext?: EvaluationContext): Promise<Record<string, boolean>>;
-    create(input: CreateFeatureFlagInput): Promise<FeatureFlagWithOverrides>;
-    update(key: string, input: UpdateFeatureFlagInput): Promise<FeatureFlagWithOverrides>;
-    archive(key: string): Promise<FeatureFlagWithOverrides>;
-    setOverride(key: string, input: SetOverrideInput): Promise<void>;
+    create(input: CreateFeatureFlagInput, metadata?: FlagMutationMetadata): Promise<FeatureFlagWithOverrides>;
+    update(key: string, input: UpdateFeatureFlagInput, metadata?: FlagMutationMetadata): Promise<FeatureFlagWithOverrides>;
+    archive(key: string, metadata?: FlagMutationMetadata): Promise<FeatureFlagWithOverrides>;
+    setOverride(key: string, input: SetOverrideInput, metadata?: FlagMutationMetadata): Promise<void>;
     findAll(): Promise<FeatureFlagWithOverrides[]>;
     invalidateCache(): Promise<void>;
     findByKey(key: string): Promise<FeatureFlagWithOverrides>;
-    removeOverride(key: string, input: RemoveOverrideInput): Promise<void>;
+    removeOverride(key: string, input: RemoveOverrideInput, metadata?: FlagMutationMetadata): Promise<void>;
     private normalizeOverrideAttributes;
     /**
      * Best-effort cache invalidation for mutation paths.
@@ -34,4 +36,9 @@ export declare class FeatureFlagService {
     private safeInvalidateCache;
     private resolveFlag;
     private resolveAllFlags;
+    private defaultDetails;
+    private resolveDefaultValue;
+    private shouldTrackExposure;
+    private emitEvaluation;
+    private emitExposure;
 }

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

@@ -33,23 +33,38 @@ let FeatureFlagService = class FeatureFlagService {
     get cacheTtlMs() {
         return this.options.cacheTtlMs ?? 30_000;
     }
-    async isEnabled(flagKey, explicitContext) {
-        const flag = await this.resolveFlag(flagKey);
-        if (!flag) {
-            return this.options.defaultOnMissing ?? false;
-        }
-        const context = this.contextResolver.resolve(explicitContext);
+    async isEnabled(flagKey, explicitContext, evaluationOptions = {}) {
+        return (await this.evaluateBoolean(flagKey, explicitContext, evaluationOptions)).value;
+    }
+    async evaluateBoolean(flagKey, explicitContext, evaluationOptions = {}) {
         const startTime = Date.now();
-        const { result, source } = this.evaluator.evaluate(flag, context);
-        const evaluationTimeMs = Date.now() - startTime;
-        this.eventPublisher.emit(feature_flag_events_1.FeatureFlagEvents.EVALUATED, {
-            flagKey,
-            result,
-            context,
-            source,
-            evaluationTimeMs,
-        });
-        return result;
+        let context = {};
+        try {
+            context = this.contextResolver.resolve(explicitContext);
+            const flag = await this.resolveFlag(flagKey);
+            const registryDefinition = this.options.flags?.[flagKey];
+            const details = flag
+                ? {
+                    ...this.evaluator.evaluate(flag, context, {
+                        bucketBy: registryDefinition?.bucketBy,
+                    }),
+                    evaluationTimeMs: Date.now() - startTime,
+                }
+                : this.defaultDetails(flagKey, 'FLAG_NOT_FOUND', startTime, evaluationOptions);
+            this.emitEvaluation(details, context, evaluationOptions);
+            if (this.shouldTrackExposure(flagKey, flag, evaluationOptions)) {
+                this.emitExposure(details, context, evaluationOptions);
+            }
+            return details;
+        }
+        catch (error) {
+            const details = this.defaultDetails(flagKey, 'ERROR', startTime, evaluationOptions, error);
+            this.emitEvaluation(details, context, evaluationOptions);
+            if (this.shouldTrackExposure(flagKey, null, evaluationOptions)) {
+                this.emitExposure(details, context, evaluationOptions);
+            }
+            return details;
+        }
     }
     async evaluateAll(explicitContext) {
         const flags = await this.resolveAllFlags();
@@ -60,25 +75,37 @@ let FeatureFlagService = class FeatureFlagService {
         }
         return result;
     }
-    async create(input) {
+    async create(input, metadata = {}) {
         const flag = await this.repository.createFlag(input);
         await this.safeInvalidateCache();
-        this.eventPublisher.emit(feature_flag_events_1.FeatureFlagEvents.CREATED, { flagKey: input.key, action: 'created' });
+        this.eventPublisher.emit(feature_flag_events_1.FeatureFlagEvents.CREATED, {
+            flagKey: input.key,
+            action: 'created',
+            ...metadata,
+        });
         return flag;
     }
-    async update(key, input) {
+    async update(key, input, metadata = {}) {
         const flag = await this.repository.updateFlag(key, input);
         await this.safeInvalidateCache(key);
-        this.eventPublisher.emit(feature_flag_events_1.FeatureFlagEvents.UPDATED, { flagKey: key, action: 'updated' });
+        this.eventPublisher.emit(feature_flag_events_1.FeatureFlagEvents.UPDATED, {
+            flagKey: key,
+            action: 'updated',
+            ...metadata,
+        });
         return flag;
     }
-    async archive(key) {
+    async archive(key, metadata = {}) {
         const flag = await this.repository.archiveFlag(key);
         await this.safeInvalidateCache(key);
-        this.eventPublisher.emit(feature_flag_events_1.FeatureFlagEvents.ARCHIVED, { flagKey: key, action: 'archived' });
+        this.eventPublisher.emit(feature_flag_events_1.FeatureFlagEvents.ARCHIVED, {
+            flagKey: key,
+            action: 'archived',
+            ...metadata,
+        });
         return flag;
     }
-    async setOverride(key, input) {
+    async setOverride(key, input, metadata = {}) {
         const attributes = this.normalizeOverrideAttributes(input.attributes);
         const priority = input.priority ?? 0;
         const flagId = await this.repository.findFlagIdByKey(key);
@@ -103,6 +130,7 @@ let FeatureFlagService = class FeatureFlagService {
             enabled: input.enabled,
             priority,
             action: 'set',
+            ...metadata,
         });
     }
     async findAll() {
@@ -119,7 +147,7 @@ let FeatureFlagService = class FeatureFlagService {
         }
         return flag;
     }
-    async removeOverride(key, input) {
+    async removeOverride(key, input, metadata = {}) {
         const attributes = this.normalizeOverrideAttributes(input.attributes);
         const flagId = await this.repository.findFlagIdByKey(key);
         if (!flagId) {
@@ -135,6 +163,7 @@ let FeatureFlagService = class FeatureFlagService {
             flagKey: key,
             attributes,
             action: 'removed',
+            ...metadata,
         });
     }
     normalizeOverrideAttributes(input) {
@@ -179,6 +208,52 @@ let FeatureFlagService = class FeatureFlagService {
         await this.cacheAdapter.setAll(flags, this.cacheTtlMs);
         return flags;
     }
+    defaultDetails(flagKey, reason, startTime, evaluationOptions, error) {
+        const defaultValue = this.resolveDefaultValue(flagKey, evaluationOptions);
+        const details = {
+            flagKey,
+            value: defaultValue,
+            result: defaultValue,
+            source: 'default',
+            reason,
+            defaultUsed: true,
+            evaluationTimeMs: Date.now() - startTime,
+        };
+        if (error) {
+            details.errorCode = error instanceof Error ? error.constructor.name : 'Error';
+            details.errorMessage = error instanceof Error ? error.message : String(error);
+        }
+        return details;
+    }
+    resolveDefaultValue(flagKey, evaluationOptions) {
+        return (evaluationOptions.defaultValue ??
+            this.options.flags?.[flagKey]?.defaultValue ??
+            this.options.defaultOnMissing ??
+            false);
+    }
+    shouldTrackExposure(flagKey, flag, evaluationOptions) {
+        return (evaluationOptions.trackExposure ??
+            this.options.flags?.[flagKey]?.trackExposure ??
+            readBooleanMetadata(flag?.metadata, 'trackExposure') ??
+            false);
+    }
+    emitEvaluation(details, context, evaluationOptions) {
+        const event = {
+            ...details,
+            evaluationTimeMs: details.evaluationTimeMs ?? 0,
+        };
+        if (evaluationOptions.includeContextInEvent ?? true) {
+            event.context = context;
+        }
+        this.eventPublisher.emit(feature_flag_events_1.FeatureFlagEvents.EVALUATED, event);
+    }
+    emitExposure(details, context, evaluationOptions) {
+        const event = { ...details };
+        if (evaluationOptions.includeContextInEvent === true) {
+            event.context = context;
+        }
+        this.eventPublisher.emit(feature_flag_events_1.FeatureFlagEvents.EXPOSED, event);
+    }
 };
 exports.FeatureFlagService = FeatureFlagService;
 exports.FeatureFlagService = FeatureFlagService = __decorate([
@@ -190,4 +265,8 @@ exports.FeatureFlagService = FeatureFlagService = __decorate([
         flag_context_resolver_1.FlagContextResolver,
         flag_event_publisher_1.FlagEventPublisher])
 ], FeatureFlagService);
+function readBooleanMetadata(metadata, key) {
+    const value = metadata?.[key];
+    return typeof value === 'boolean' ? value : undefined;
+}
 //# sourceMappingURL=feature-flag.service.js.map

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

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

package/dist/services/flag-evaluator.service.d.ts

@@ -1,13 +1,12 @@
 import { FeatureFlagWithOverrides } from '../interfaces/feature-flag.interface';
 import { EvaluationContext } from '../interfaces/evaluation-context.interface';
-import { FlagEvaluatedEvent } from '../events/feature-flag.events';
-type EvaluationSource = FlagEvaluatedEvent['source'];
-export interface EvaluationResult {
-    result: boolean;
-    source: EvaluationSource;
-}
+import { BooleanEvaluationDetails, FlagEvaluatorOptions } from '../interfaces/evaluation-details.interface';
+export type EvaluationResult = BooleanEvaluationDetails;
 export declare class FlagEvaluatorService {
-    evaluate(flag: FeatureFlagWithOverrides, context: EvaluationContext): EvaluationResult;
+    evaluate(flag: FeatureFlagWithOverrides, context: EvaluationContext, options?: FlagEvaluatorOptions): EvaluationResult;
     private findMatchingOverride;
+    private resolveTargetingKey;
+    private getMetadataBucketBy;
+    private readBucketValue;
+    private result;
 }
-export {};

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

@@ -11,26 +11,29 @@ 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) {
+    evaluate(flag, context, options = {}) {
         if (flag.archivedAt) {
-            return { result: false, source: 'global' };
+            return this.result(flag.key, false, 'global', 'ARCHIVED');
         }
         const override = this.findMatchingOverride(flag.overrides, context);
         if (override) {
-            return { result: override.enabled, source: 'override' };
+            return this.result(flag.key, override.enabled, 'override', 'OVERRIDE_MATCH', {
+                matchedOverrideId: override.id,
+            });
         }
         if (flag.percentage > 0) {
             if (flag.percentage === 100) {
-                return { result: true, source: 'percentage' };
+                return this.result(flag.key, true, 'percentage', 'PERCENTAGE_MATCH');
             }
-            const hashKey = context.userId ?? context.tenantId ?? '';
-            if (!hashKey) {
-                return { result: flag.enabled, source: 'global' };
+            const targetingKey = this.resolveTargetingKey(flag, context, options.bucketBy);
+            if (!targetingKey) {
+                return this.result(flag.key, flag.enabled, 'global', 'PERCENTAGE_NO_TARGETING_KEY');
             }
-            const bucket = (0, hash_1.murmurhash3)(flag.key + hashKey) % 100;
-            return { result: bucket < flag.percentage, source: 'percentage' };
+            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 { result: flag.enabled, source: 'global' };
+        return this.result(flag.key, flag.enabled, 'global', 'GLOBAL');
     }
     findMatchingOverride(overrides, context) {
         const contextAttributes = context.attributes ?? {};
@@ -38,11 +41,60 @@ let FlagEvaluatorService = class FlagEvaluatorService {
             .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;
+            }
+        }
+        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) {