Prerequisites support

CHANGES.txt

@@ -1,5 +1,6 @@
-2.4.0 (May 20, 2025)
+2.4.0 (May 27, 2025)
  - Added support for targeting rules based on rule-based segments.
+ - Added support for feature flag prerequisites.
 
 2.3.0 (May 16, 2025)
  - Updated the Redis storage to:

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@splitsoftware/splitio-commons",
-  "version": "2.3.0",
+  "version": "2.4.0",
   "description": "Split JavaScript SDK common components",
   "main": "cjs/index.js",
   "module": "esm/index.js",

src/dtos/types.ts

@@ -220,6 +220,10 @@ export interface ISplit {
   changeNumber: number,
   status: 'ACTIVE' | 'ARCHIVED',
   conditions: ISplitCondition[],
+  prerequisites?: {
+    n: string,
+    ts: string[]
+  }[]
   killed: boolean,
   defaultTreatment: string,
   trafficTypeName: string,

src/evaluator/Engine.ts

@@ -1,14 +1,16 @@
-import { get } from '../utils/lang';
+import { get, isString } from '../utils/lang';
 import { parser } from './parser';
 import { keyParser } from '../utils/key';
 import { thenable } from '../utils/promise/thenable';
-import { EXCEPTION, NO_CONDITION_MATCH, SPLIT_ARCHIVED, SPLIT_KILLED } from '../utils/labels';
+import { NO_CONDITION_MATCH, SPLIT_ARCHIVED, SPLIT_KILLED, PREREQUISITES_NOT_MET } from '../utils/labels';
 import { CONTROL } from '../utils/constants';
 import { ISplit, MaybeThenable } from '../dtos/types';
 import SplitIO from '../../types/splitio';
 import { IStorageAsync, IStorageSync } from '../storages/types';
-import { IEvaluation, IEvaluationResult, IEvaluator, ISplitEvaluator } from './types';
+import { IEvaluation, IEvaluationResult, ISplitEvaluator } from './types';
 import { ILogger } from '../logger/types';
+import { ENGINE_DEFAULT } from '../logger/constants';
+import { prerequisitesMatcherContext } from './matchers/prerequisites';
 
 function evaluationResult(result: IEvaluation | undefined, defaultTreatment: string): IEvaluationResult {
   return {
@@ -17,84 +19,55 @@ function evaluationResult(result: IEvaluation | undefined, defaultTreatment: str
   };
 }
 
-export class Engine {
+export function engineParser(log: ILogger, split: ISplit, storage: IStorageSync | IStorageAsync) {
+  const { killed, seed, trafficAllocation, trafficAllocationSeed, status, conditions, prerequisites } = split;
 
-  constructor(private baseInfo: ISplit, private evaluator: IEvaluator) {
+  const defaultTreatment = isString(split.defaultTreatment) ? split.defaultTreatment : CONTROL;
 
-    // in case we don't have a default treatment in the instantiation, use 'control'
-    if (typeof this.baseInfo.defaultTreatment !== 'string') {
-      this.baseInfo.defaultTreatment = CONTROL;
-    }
-  }
+  const evaluator = parser(log, conditions, storage);
+  const prerequisiteMatcher = prerequisitesMatcherContext(prerequisites, storage, log);
+
+  return {
 
-  static parse(log: ILogger, splitFlatStructure: ISplit, storage: IStorageSync | IStorageAsync) {
-    const conditions = splitFlatStructure.conditions;
-    const evaluator = parser(log, conditions, storage);
+    getTreatment(key: SplitIO.SplitKey, attributes: SplitIO.Attributes | undefined, splitEvaluator: ISplitEvaluator): MaybeThenable<IEvaluationResult> {
 
-    return new Engine(splitFlatStructure, evaluator);
-  }
+      const parsedKey = keyParser(key);
 
-  getKey() {
-    return this.baseInfo.name;
-  }
+      function evaluate(prerequisitesMet: boolean) {
+        if (!prerequisitesMet) {
+          log.debug(ENGINE_DEFAULT, ['Prerequisite not met']);
+          return {
+            treatment: defaultTreatment,
+            label: PREREQUISITES_NOT_MET
+          };
+        }
 
-  getTreatment(key: SplitIO.SplitKey, attributes: SplitIO.Attributes | undefined, splitEvaluator: ISplitEvaluator): MaybeThenable<IEvaluationResult> {
-    const {
-      killed,
-      seed,
-      defaultTreatment,
-      trafficAllocation,
-      trafficAllocationSeed
-    } = this.baseInfo;
-    let parsedKey;
-    let treatment;
-    let label;
+        const evaluation = evaluator(parsedKey, seed, trafficAllocation, trafficAllocationSeed, attributes, splitEvaluator) as MaybeThenable<IEvaluation>;
+
+        return thenable(evaluation) ?
+          evaluation.then(result => evaluationResult(result, defaultTreatment)) :
+          evaluationResult(evaluation, defaultTreatment);
+      }
 
-    try {
-      parsedKey = keyParser(key);
-    } catch (err) {
-      return {
+      if (status === 'ARCHIVED') return {
         treatment: CONTROL,
-        label: EXCEPTION
+        label: SPLIT_ARCHIVED
       };
-    }
-
-    if (this.isGarbage()) {
-      treatment = CONTROL;
-      label = SPLIT_ARCHIVED;
-    } else if (killed) {
-      treatment = defaultTreatment;
-      label = SPLIT_KILLED;
-    } else {
-      const evaluation = this.evaluator(
-        parsedKey,
-        seed,
-        trafficAllocation,
-        trafficAllocationSeed,
-        attributes,
-        splitEvaluator
-      ) as MaybeThenable<IEvaluation>;
 
-      // Evaluation could be async, so we should handle that case checking for a
-      // thenable object
-      if (thenable(evaluation)) {
-        return evaluation.then(result => evaluationResult(result, defaultTreatment));
-      } else {
-        return evaluationResult(evaluation, defaultTreatment);
+      if (killed) {
+        log.debug(ENGINE_DEFAULT, ['Flag is killed']);
+        return {
+          treatment: defaultTreatment,
+          label: SPLIT_KILLED
+        };
       }
-    }
 
-    return {
-      treatment,
-      label
-    };
-  }
+      const prerequisitesMet = prerequisiteMatcher({ key, attributes }, splitEvaluator);
 
-  isGarbage() {
-    return this.baseInfo.status === 'ARCHIVED';
-  }
+      return thenable(prerequisitesMet) ?
+        prerequisitesMet.then(evaluate) :
+        evaluate(prerequisitesMet);
+    }
+  };
 
-  getChangeNumber() {
-    return this.baseInfo.changeNumber;
-  }
 }

src/evaluator/index.ts

@@ -1,4 +1,4 @@
-import { Engine } from './Engine';
+import { engineParser } from './Engine';
 import { thenable } from '../utils/promise/thenable';
 import { EXCEPTION, SPLIT_NOT_FOUND } from '../utils/labels';
 import { CONTROL } from '../utils/constants';
@@ -99,9 +99,7 @@ export function evaluateFeaturesByFlagSets(
 ): MaybeThenable<Record<string, IEvaluationResult>> {
   let storedFlagNames: MaybeThenable<Set<string>[]>;
 
-  function evaluate(
-    featureFlagsByFlagSets: Set<string>[],
-  ) {
+  function evaluate(featureFlagsByFlagSets: Set<string>[]) {
     let featureFlags = new Set<string>();
     for (let i = 0; i < flagSets.length; i++) {
       const featureFlagByFlagSet = featureFlagsByFlagSets[i];
@@ -148,20 +146,20 @@ function getEvaluation(
   };
 
   if (splitJSON) {
-    const split = Engine.parse(log, splitJSON, storage);
+    const split = engineParser(log, splitJSON, storage);
     evaluation = split.getTreatment(key, attributes, evaluateFeature);
 
     // If the storage is async and the evaluated flag uses segments or dependencies, evaluation is thenable
     if (thenable(evaluation)) {
       return evaluation.then(result => {
-        result.changeNumber = split.getChangeNumber();
+        result.changeNumber = splitJSON.changeNumber;
         result.config = splitJSON.configurations && splitJSON.configurations[result.treatment] || null;
         result.impressionsDisabled = splitJSON.impressionsDisabled;
 
         return result;
       });
     } else {
-      evaluation.changeNumber = split.getChangeNumber(); // Always sync and optional
+      evaluation.changeNumber = splitJSON.changeNumber;
       evaluation.config = splitJSON.configurations && splitJSON.configurations[evaluation.treatment] || null;
       evaluation.impressionsDisabled = splitJSON.impressionsDisabled;
     }

src/evaluator/matchers/__tests__/prerequisites.spec.ts

@@ -0,0 +1,106 @@
+import { evaluateFeature } from '../../index';
+import { IStorageSync } from '../../../storages/types';
+import { loggerMock } from '../../../logger/__tests__/sdkLogger.mock';
+import { ISplit } from '../../../dtos/types';
+import { ALWAYS_ON_SPLIT, ALWAYS_OFF_SPLIT } from '../../../storages/__tests__/testUtils';
+import { prerequisitesMatcherContext } from '../prerequisites';
+
+const STORED_SPLITS: Record<string, ISplit> = {
+  'always-on': ALWAYS_ON_SPLIT,
+  'always-off': ALWAYS_OFF_SPLIT
+};
+
+const mockStorage = {
+  splits: {
+    getSplit: (name: string) => STORED_SPLITS[name]
+  }
+} as IStorageSync;
+
+test('MATCHER PREREQUISITES / should return true when all prerequisites are met', () => {
+  // A single prerequisite
+  const matcherTrueAlwaysOn = prerequisitesMatcherContext([{
+    n: 'always-on',
+    ts: ['not-existing', 'on', 'other'] // We should match from a list of treatments
+  }], mockStorage, loggerMock);
+  expect(matcherTrueAlwaysOn({ key: 'a-key' }, evaluateFeature)).toBe(true); // Feature flag returns one of the expected treatments, so the matcher returns true
+
+  const matcherFalseAlwaysOn = prerequisitesMatcherContext([{
+    n: 'always-on',
+    ts: ['off', 'v1']
+  }], mockStorage, loggerMock);
+  expect(matcherFalseAlwaysOn({ key: 'a-key' }, evaluateFeature)).toBe(false); // Feature flag returns treatment "on", but we are expecting ["off", "v1"], so the matcher returns false
+
+  const matcherTrueAlwaysOff = prerequisitesMatcherContext([{
+    n: 'always-off',
+    ts: ['not-existing', 'off']
+  }], mockStorage, loggerMock);
+  expect(matcherTrueAlwaysOff({ key: 'a-key' }, evaluateFeature)).toBe(true); // Feature flag returns one of the expected treatments, so the matcher returns true
+
+  const matcherFalseAlwaysOff = prerequisitesMatcherContext([{
+    n: 'always-off',
+    ts: ['v1', 'on']
+  }], mockStorage, loggerMock);
+  expect(matcherFalseAlwaysOff({ key: 'a-key' }, evaluateFeature)).toBe(false); // Feature flag returns treatment "on", but we are expecting ["off", "v1"], so the matcher returns false
+
+  // Multiple prerequisites
+  const matcherTrueMultiplePrerequisites = prerequisitesMatcherContext([
+    {
+      n: 'always-on',
+      ts: ['on']
+    },
+    {
+      n: 'always-off',
+      ts: ['off']
+    }
+  ], mockStorage, loggerMock);
+  expect(matcherTrueMultiplePrerequisites({ key: 'a-key' }, evaluateFeature)).toBe(true); // All prerequisites are met, so the matcher returns true
+
+  const matcherFalseMultiplePrerequisites = prerequisitesMatcherContext([
+    {
+      n: 'always-on',
+      ts: ['on']
+    },
+    {
+      n: 'always-off',
+      ts: ['on']
+    }
+  ], mockStorage, loggerMock);
+  expect(matcherFalseMultiplePrerequisites({ key: 'a-key' }, evaluateFeature)).toBe(false); // One of the prerequisites is not met, so the matcher returns false
+});
+
+test('MATCHER PREREQUISITES / Edge cases', () => {
+  // No prerequisites
+  const matcherTrueNoPrerequisites = prerequisitesMatcherContext(undefined, mockStorage, loggerMock);
+  expect(matcherTrueNoPrerequisites({ key: 'a-key' }, evaluateFeature)).toBe(true);
+
+  const matcherTrueEmptyPrerequisites = prerequisitesMatcherContext([], mockStorage, loggerMock);
+  expect(matcherTrueEmptyPrerequisites({ key: 'a-key' }, evaluateFeature)).toBe(true);
+
+  // Non existent feature flag
+  const matcherParentNotExist = prerequisitesMatcherContext([{
+    n: 'not-existent-feature-flag',
+    ts: ['on', 'off']
+  }], mockStorage, loggerMock);
+  expect(matcherParentNotExist({ key: 'a-key' }, evaluateFeature)).toBe(false); // If the feature flag does not exist, matcher should return false
+
+  // Empty treatments list
+  const matcherNoTreatmentsExpected = prerequisitesMatcherContext([
+    {
+      n: 'always-on',
+      ts: []
+    }], mockStorage, loggerMock);
+  expect(matcherNoTreatmentsExpected({ key: 'a-key' }, evaluateFeature)).toBe(false); // If treatments expectation list is empty, matcher should return false (no treatment will match)
+
+  const matcherExpectedTreatmentWrongTypeMatching = prerequisitesMatcherContext([{
+    n: 'always-on', // @ts-ignore
+    ts: [null, [1, 2], 3, {}, true, 'on']
+
+  }], mockStorage, loggerMock);
+  expect(matcherExpectedTreatmentWrongTypeMatching({ key: 'a-key' }, evaluateFeature)).toBe(true); // If treatments expectation list has elements of the wrong type, those elements are overlooked.
+
+  const matcherExpectedTreatmentWrongTypeNotMatching = prerequisitesMatcherContext([{
+    n: 'always-off', // @ts-ignore
+    ts: [null, [1, 2], 3, {}, true, 'on']
+  }], mockStorage, loggerMock);
+  expect(matcherExpectedTreatmentWrongTypeNotMatching({ key: 'a-key' }, evaluateFeature)).toBe(false); // If treatments expectation list has elements of the wrong type, those elements are overlooked.
+});

src/evaluator/matchers/prerequisites.ts

@@ -0,0 +1,24 @@
+import { ISplit, MaybeThenable } from '../../dtos/types';
+import { IStorageAsync, IStorageSync } from '../../storages/types';
+import { ILogger } from '../../logger/types';
+import { thenable } from '../../utils/promise/thenable';
+import { IDependencyMatcherValue, ISplitEvaluator } from '../types';
+
+export function prerequisitesMatcherContext(prerequisites: ISplit['prerequisites'] = [], storage: IStorageSync | IStorageAsync, log: ILogger) {
+
+  return function prerequisitesMatcher({ key, attributes }: IDependencyMatcherValue, splitEvaluator: ISplitEvaluator): MaybeThenable<boolean> {
+
+    function evaluatePrerequisite(prerequisite: { n: string; ts: string[] }): MaybeThenable<boolean> {
+      const evaluation = splitEvaluator(log, key, prerequisite.n, attributes, storage);
+      return thenable(evaluation) ?
+        evaluation.then(evaluation => prerequisite.ts.indexOf(evaluation.treatment!) !== -1) :
+        prerequisite.ts.indexOf(evaluation.treatment!) !== -1;
+    }
+
+    return prerequisites.reduce<MaybeThenable<boolean>>((prerequisitesMet, prerequisite) => {
+      return thenable(prerequisitesMet) ?
+        prerequisitesMet.then(prerequisitesMet => prerequisitesMet ? evaluatePrerequisite(prerequisite) : false) :
+        prerequisitesMet ? evaluatePrerequisite(prerequisite) : false;
+    }, true);
+  };
+}

src/evaluator/matchers/rbsegment.ts

@@ -39,8 +39,8 @@ export function ruleBasedSegmentMatcherContext(segmentName: string, storage: ISt
         storage.segments.isInSegment(name, matchingKey) :
         type === RULE_BASED_SEGMENT ?
           ruleBasedSegmentMatcherContext(name, storage, log)({ key, attributes }, splitEvaluator) :
-          type === LARGE_SEGMENT && (storage as IStorageSync).largeSegments ?
-            (storage as IStorageSync).largeSegments!.isInSegment(name, matchingKey) :
+          type === LARGE_SEGMENT && storage.largeSegments ?
+            storage.largeSegments.isInSegment(name, matchingKey) :
             false;
     }
 

src/logger/constants.ts

@@ -28,6 +28,7 @@ export const SYNC_TASK_EXECUTE = 37;
 export const SYNC_TASK_STOP = 38;
 export const SETTINGS_SPLITS_FILTER = 39;
 export const ENGINE_MATCHER_RESULT = 40;
+export const ENGINE_DEFAULT = 41;
 
 export const CLIENT_READY_FROM_CACHE = 100;
 export const CLIENT_READY = 101;

src/logger/messages/debug.ts

@@ -12,6 +12,7 @@ export const codesDebug: [number, string][] = codesInfo.concat([
   [c.ENGINE_VALUE, c.LOG_PREFIX_ENGINE_VALUE + 'Extracted attribute `%s`. %s will be used for matching.'],
   [c.ENGINE_SANITIZE, c.LOG_PREFIX_ENGINE + ':sanitize: Attempted to sanitize %s which should be of type %s. Sanitized and processed value => %s'],
   [c.ENGINE_MATCHER_RESULT, c.LOG_PREFIX_ENGINE_MATCHER + '[%s] Result: %s. Rule value: %s. Evaluation value: %s'],
+  [c.ENGINE_DEFAULT, c.LOG_PREFIX_ENGINE + 'Evaluates to default treatment. %s'],
   // SDK
   [c.CLEANUP_REGISTERING, c.LOG_PREFIX_CLEANUP + 'Registering cleanup handler %s'],
   [c.CLEANUP_DEREGISTERING, c.LOG_PREFIX_CLEANUP + 'Deregistering cleanup handler %s'],