feat: added-reasons-to-flag-object

Author: Zaimwa9

flagsmith-engine/features/types.ts

@@ -1,4 +1,5 @@
 export enum TARGETING_REASONS {
     DEFAULT = 'DEFAULT',
-    TARGETING_MATCH = 'TARGETING_MATCH'
+    TARGETING_MATCH = 'TARGETING_MATCH',
+    SPLIT = 'SPLIT'
 }

flagsmith-engine/index.ts

@@ -108,28 +108,34 @@ export function evaluateFeatures(
         const segmentOverride = segmentOverrides[feature.feature_key];
         const finalFeature = segmentOverride ? segmentOverride.feature : feature;
         const hasOverride = !!segmentOverride;
-        const reason = getTargetingMatchReason(segmentOverride);
+
+        const { value: evaluatedValue, reason: evaluatedReason } = hasOverride
+            ? { value: finalFeature.value, reason: undefined }
+            : evaluateFeatureValue(finalFeature, context.identity?.key);
 
         flags.push({
             feature_key: finalFeature.feature_key,
             name: finalFeature.name,
             enabled: finalFeature.enabled,
-            value: hasOverride
-                ? finalFeature.value
-                : evaluateFeatureValue(finalFeature, context.identity?.key),
-            reason
+            value: evaluatedValue,
+            reason:
+                evaluatedReason ??
+                getTargetingMatchReason({ type: 'SEGMENT', override: segmentOverride })
         });
     }
 
     return flags;
 }
 
-function evaluateFeatureValue(feature: FeatureContext, identityKey?: string): any {
+function evaluateFeatureValue(
+    feature: FeatureContext,
+    identityKey?: string
+): { value: any; reason?: string } {
     if (!!feature.variants && feature.variants.length > 0 && !!identityKey) {
         return getMultivariateFeatureValue(feature, identityKey);
     }
 
-    return feature.value;
+    return { value: feature.value, reason: undefined };
 }
 
 /**
@@ -142,19 +148,25 @@ function evaluateFeatureValue(feature: FeatureContext, identityKey?: string): an
  * @param identityKey - The identity key used for deterministic variant selection
  * @returns The variant value if the identity falls within a variant's range, otherwise the default feature value
  */
-function getMultivariateFeatureValue(feature: FeatureContext, identityKey?: string): any {
+function getMultivariateFeatureValue(
+    feature: FeatureContext,
+    identityKey?: string
+): { value: any; reason?: string } {
     const percentageValue = getHashedPercentageForObjIds([feature.key, identityKey]);
 
     let startPercentage = 0;
     for (const variant of feature?.variants || []) {
         const limit = startPercentage + variant.weight;
 
         if (startPercentage <= percentageValue && percentageValue < limit) {
-            return variant.value;
+            return {
+                value: variant.value,
+                reason: getTargetingMatchReason({ type: 'SPLIT', weight: variant.weight })
+            };
         }
         startPercentage = limit;
     }
-    return feature.value;
+    return { value: feature.value, reason: undefined };
 }
 
 export function shouldApplyOverride(
@@ -174,8 +186,28 @@ export function isHigherPriority(
     return (priorityA ?? Infinity) < (priorityB ?? Infinity);
 }
 
-const getTargetingMatchReason = (segmentOverride: SegmentOverride) => {
-    return segmentOverride
-        ? `${TARGETING_REASONS.TARGETING_MATCH}; segment=${segmentOverride.segmentName}`
-        : TARGETING_REASONS.DEFAULT;
+export type TargetingMatchReason =
+    | {
+          type: 'SEGMENT';
+          override: SegmentOverride;
+      }
+    | {
+          type: 'SPLIT';
+          weight: number;
+      };
+
+const getTargetingMatchReason = (matchObject: TargetingMatchReason) => {
+    const { type } = matchObject;
+
+    if (type === 'SEGMENT') {
+        return matchObject.override
+            ? `${TARGETING_REASONS.TARGETING_MATCH}; segment=${matchObject.override.segmentName}`
+            : TARGETING_REASONS.DEFAULT;
+    }
+
+    if (type === 'SPLIT') {
+        return `${TARGETING_REASONS.SPLIT}; weight=${matchObject.weight}`;
+    }
+
+    return TARGETING_REASONS.DEFAULT;
 };

sdk/models.ts

@@ -50,6 +50,10 @@ export class Flag extends BaseFlag {
      * The programmatic name for this feature, unique per Flagsmith project.
      */
     featureName: string;
+    /**
+     * The reason for this feature, unique per Flagsmith project.
+     */
+    reason?: string;
 
     constructor(params: {
         value: FlagValue;
@@ -62,6 +66,7 @@ export class Flag extends BaseFlag {
         super(params.value, params.enabled, !!params.isDefault);
         this.featureId = params.featureId;
         this.featureName = params.featureName;
+        this.reason = params.reason;
     }
 
     static fromFeatureStateModel(
@@ -81,7 +86,8 @@ export class Flag extends BaseFlag {
             enabled: flagResult.enabled,
             value: flagResult.value ?? null,
             featureId: Number(flagResult.feature_key),
-            featureName: flagResult.name
+            featureName: flagResult.name,
+            reason: flagResult.reason
         });
     }
 
@@ -90,7 +96,8 @@ export class Flag extends BaseFlag {
             enabled: flagData['enabled'],
             value: flagData['feature_state_value'] ?? flagData['value'],
             featureId: flagData['feature']['id'],
-            featureName: flagData['feature']['name']
+            featureName: flagData['feature']['name'],
+            reason: flagData['feature']['reason']
         });
     }
 }

tests/engine/e2e/engine.test.ts

@@ -57,6 +57,7 @@ describe('Engine Integration Tests', () => {
             for (let i = 0; i < sortedEngineFlags.length; i++) {
                 expect(sortedEngineFlags[i].value).toBe(sortedAPIFlags[i].value);
                 expect(sortedEngineFlags[i].enabled).toBe(sortedAPIFlags[i].enabled);
+                expect(sortedEngineFlags[i].reason).toBe(sortedAPIFlags[i].reason);
             }
         });
     });

tests/engine/unit/segments/segments_model.test.ts

@@ -107,7 +107,6 @@ const conditionMatchCases: [string, string | number | boolean | null, string, bo
 test('test_segment_condition_matches_trait_value', () => {
     for (const testCase of conditionMatchCases) {
         const [operator, traitValue, conditionValue, expectedResult] = testCase;
-        console.log(operator, traitValue, conditionValue, expectedResult);
         expect(
             new SegmentConditionModel(operator, conditionValue, 'foo').matchesTraitValue(traitValue)
         ).toBe(expectedResult);