[FSSDK-11526] parse holdout from datafile into project config (#1074)

* [FSSDK-11526] parse holdout from datafile into project config

also add getHoldoutsForFlag() function

Author: raju-opti

lib/feature_toggle.ts

@@ -0,0 +1,34 @@
+/**
+ * Copyright 2025, Optimizely
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * https://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+/* eslint-disable @typescript-eslint/explicit-module-boundary-types */
+
+/**
+ * This module contains feature flags that control the availability of features under development.
+ * Each flag represents a feature that is not yet ready for production release. These flags
+ * serve multiple purposes in our development workflow:
+ * 
+ * When a new feature is in development, it can be safely merged into the main branch
+ * while remaining disabled in production. This allows continuous integration without
+ * affecting the stability of production releases. The feature code will be automatically
+ * removed in production builds through tree-shaking when the flag is disabled.
+ * 
+ * During development and testing, these flags can be easily mocked to enable/disable
+ * specific features. Once a feature is complete and ready for release, its corresponding
+ * flag and all associated checks can be removed from the codebase.
+ */
+
+export const holdout = () => false;

lib/project_config/project_config.spec.ts

@@ -13,10 +13,10 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-import { describe, it, expect, beforeEach, afterEach, vi, assert, Mock } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi, assert, Mock, beforeAll, afterAll } from 'vitest';
 import { sprintf } from '../utils/fns';
 import { keyBy } from '../utils/fns';
-import projectConfig, { ProjectConfig, Region } from './project_config';
+import projectConfig, { ProjectConfig, getHoldoutsForFlag } from './project_config';
 import { FEATURE_VARIABLE_TYPES, LOG_LEVEL } from '../utils/enums';
 import testDatafile from '../tests/test_data';
 import configValidator from '../utils/config_validator';
@@ -32,11 +32,20 @@ import {
 import { getMockLogger } from '../tests/mock/mock_logger';
 import { VariableType } from '../shared_types';
 import { OptimizelyError } from '../error/optimizly_error';
+import { mock } from 'node:test';
 
 const buildLogMessageFromArgs = (args: any[]) => sprintf(args[1], ...args.splice(2));
 const cloneDeep = (obj: any) => JSON.parse(JSON.stringify(obj));
 const logger = getMockLogger();
 
+const mockHoldoutToggle = vi.hoisted(() => vi.fn());
+
+vi.mock('../feature_toggle', () => {
+  return {
+    holdout: mockHoldoutToggle,
+  };
+});
+
 describe('createProjectConfig', () => {
   let configObj: ProjectConfig;
 
@@ -298,6 +307,191 @@ describe('createProjectConfig - cmab experiments', () => {
   });
 });
 
+const getHoldoutDatafile = () => {
+  const datafile = testDatafile.getTestDecideProjectConfig();
+
+  // Add holdouts to the datafile
+  datafile.holdouts = [
+    {
+      id: 'holdout_id_1',
+      key: 'holdout_1',
+      status: 'Running',
+      includeFlags: [],
+      excludeFlags: [],
+      audienceIds: ['13389130056'],
+      audienceConditions: ['or', '13389130056'],
+      variations: [
+        {
+          id: 'var_id_1',
+          key: 'holdout_variation_1',
+          variables: []
+        }
+      ],
+      trafficAllocation: [
+        {
+          entityId: 'var_id_1',
+          endOfRange: 5000
+        }
+      ]
+    },
+    {
+      id: 'holdout_id_2',
+      key: 'holdout_2',
+      status: 'Running',
+      includeFlags: [],
+      excludeFlags: ['feature_3'],
+      audienceIds: [],
+      audienceConditions: [],
+      variations: [
+        {
+          id: 'var_id_2',
+          key: 'holdout_variation_2',
+          variables: []
+        }
+      ],
+      trafficAllocation: [
+        {
+          entityId: 'var_id_2',
+          endOfRange: 1000
+        }
+      ]
+    },
+    {
+      id: 'holdout_id_3',
+      key: 'holdout_3',
+      status: 'Draft',
+      includeFlags: ['feature_1'],
+      excludeFlags: [],
+      audienceIds: [],
+      audienceConditions: [],
+      variations: [
+        {
+          id: 'var_id_2',
+          key: 'holdout_variation_2',
+          variables: []
+        }
+      ],
+      trafficAllocation: [
+        {
+          entityId: 'var_id_2',
+          endOfRange: 1000
+        }
+      ]
+    }
+  ];
+
+  return datafile;
+}
+
+describe('createProjectConfig - holdouts, feature toggle is on', () => {
+  beforeAll(() => {
+    mockHoldoutToggle.mockReturnValue(true);
+  });
+
+  afterAll(() => {
+    mockHoldoutToggle.mockReset();
+  });
+
+  it('should populate holdouts fields correctly', function() {
+    const datafile = getHoldoutDatafile();
+    
+    mockHoldoutToggle.mockReturnValue(true);
+
+    const configObj = projectConfig.createProjectConfig(JSON.parse(JSON.stringify(datafile)));
+
+    expect(configObj.holdouts).toHaveLength(3);
+    configObj.holdouts.forEach((holdout, i) => {
+      expect(holdout).toEqual(expect.objectContaining(datafile.holdouts[i]));
+      expect(holdout.variationKeyMap).toEqual(
+        keyBy(datafile.holdouts[i].variations, 'key')
+      );
+    });
+
+    expect(configObj.holdoutIdMap).toEqual({
+      holdout_id_1: configObj.holdouts[0],
+      holdout_id_2: configObj.holdouts[1],
+      holdout_id_3: configObj.holdouts[2],
+    });
+
+    expect(configObj.globalHoldouts).toHaveLength(2);
+    expect(configObj.globalHoldouts).toEqual([
+      configObj.holdouts[0], // holdout_1 has empty includeFlags
+      configObj.holdouts[1]  // holdout_2 has empty includeFlags
+    ]);
+
+    expect(configObj.includedHoldouts).toEqual({
+      feature_1: [configObj.holdouts[2]], // holdout_3 includes feature_1
+    });
+
+    expect(configObj.excludedHoldouts).toEqual({
+      feature_3: [configObj.holdouts[1]]  // holdout_2 excludes feature_3
+    });
+
+    expect(configObj.flagHoldoutsMap).toEqual({});
+  });
+
+  it('should handle empty holdouts array', function() {
+    const datafile = testDatafile.getTestProjectConfig();
+
+    const configObj = projectConfig.createProjectConfig(datafile);
+
+    expect(configObj.holdouts).toEqual([]);
+    expect(configObj.holdoutIdMap).toEqual({});
+    expect(configObj.globalHoldouts).toEqual([]);
+    expect(configObj.includedHoldouts).toEqual({});
+    expect(configObj.excludedHoldouts).toEqual({});
+    expect(configObj.flagHoldoutsMap).toEqual({});
+  });
+
+  it('should handle undefined includeFlags and excludeFlags in holdout', function() {
+    const datafile = getHoldoutDatafile();
+    datafile.holdouts[0].includeFlags = undefined;
+    datafile.holdouts[0].excludeFlags = undefined;
+
+    const configObj = projectConfig.createProjectConfig(JSON.parse(JSON.stringify(datafile)));
+
+    expect(configObj.holdouts).toHaveLength(3);
+    expect(configObj.holdouts[0].includeFlags).toEqual([]);
+    expect(configObj.holdouts[0].excludeFlags).toEqual([]);
+  });
+});
+
+describe('getHoldoutsForFlag: feature toggle is on', () => {
+    beforeAll(() => {
+    mockHoldoutToggle.mockReturnValue(true);
+  });
+
+  afterAll(() => {
+    mockHoldoutToggle.mockReset();
+  });
+
+  it('should return all applicable holdouts for a flag', () => {
+    const datafile = getHoldoutDatafile();
+    const configObj = projectConfig.createProjectConfig(JSON.parse(JSON.stringify(datafile)));
+
+    const feature1Holdouts = getHoldoutsForFlag(configObj, 'feature_1');
+    expect(feature1Holdouts).toHaveLength(3);
+    expect(feature1Holdouts).toEqual([
+      configObj.holdouts[0],
+      configObj.holdouts[1],
+      configObj.holdouts[2],
+    ]);
+
+    const feature2Holdouts = getHoldoutsForFlag(configObj, 'feature_2');
+    expect(feature2Holdouts).toHaveLength(2);
+    expect(feature2Holdouts).toEqual([
+      configObj.holdouts[0],
+      configObj.holdouts[1],
+    ]);
+
+    const feature3Holdouts = getHoldoutsForFlag(configObj, 'feature_3');
+    expect(feature3Holdouts).toHaveLength(1);
+    expect(feature3Holdouts).toEqual([
+      configObj.holdouts[0],
+    ]);
+  });
+});
+
 describe('getExperimentId', () => {
   let testData: Record<string, any>;
   let configObj: ProjectConfig;

lib/project_config/project_config.ts

@@ -34,6 +34,7 @@ import {
   VariationVariable,
   Integration,
   FeatureVariableValue,
+  Holdout,
 } from '../shared_types';
 import { OdpConfig, OdpIntegrationConfig } from '../odp/odp_config';
 import { Transformer } from '../utils/type';
@@ -51,6 +52,7 @@ import {
 } from 'error_message';
 import { SKIPPING_JSON_VALIDATION, VALID_DATAFILE } from 'log_message';
 import { OptimizelyError } from '../error/optimizly_error';
+import * as featureToggle from '../feature_toggle';
 
 interface TryCreatingProjectConfigConfig {
   // TODO[OASIS-6649]: Don't use object type
@@ -110,6 +112,12 @@ export interface ProjectConfig {
   integrations: Integration[];
   integrationKeyMap?: { [key: string]: Integration };
   odpIntegrationConfig: OdpIntegrationConfig;
+  holdouts: Holdout[];
+  holdoutIdMap?: { [id: string]: Holdout };
+  globalHoldouts: Holdout[];
+  includedHoldouts: { [key: string]: Holdout[]; } 
+  excludedHoldouts: { [key: string]: Holdout[]; }
+  flagHoldoutsMap: { [key: string]: Holdout[]; }
 }
 
 const EXPERIMENT_RUNNING_STATUS = 'Running';
@@ -335,9 +343,69 @@ export const createProjectConfig = function(datafileObj?: JSON, datafileStr: str
     projectConfig.flagVariationsMap[flagKey] = variations;
   });
 
+  parseHoldoutsConfig(projectConfig);
+
   return projectConfig;
 };
 
+const parseHoldoutsConfig = (projectConfig: ProjectConfig): void => {
+  if (!featureToggle.holdout()) {
+    return;
+  }
+
+  projectConfig.holdouts = projectConfig.holdouts || [];
+  projectConfig.holdoutIdMap = keyBy(projectConfig.holdouts, 'id');
+  projectConfig.globalHoldouts = [];
+  projectConfig.includedHoldouts = {};
+  projectConfig.excludedHoldouts = {};
+  projectConfig.flagHoldoutsMap = {};
+
+  projectConfig.holdouts.forEach((holdout) => {
+    if (!holdout.includeFlags) {
+      holdout.includeFlags = [];
+    }
+
+    if (!holdout.excludeFlags) {
+      holdout.excludeFlags = [];
+    }
+
+    holdout.variationKeyMap = keyBy(holdout.variations, 'key');
+    if (holdout.includeFlags.length === 0) {
+      projectConfig.globalHoldouts.push(holdout);
+
+      holdout.excludeFlags.forEach((flagKey) => {
+        if (!projectConfig.excludedHoldouts[flagKey]) {
+          projectConfig.excludedHoldouts[flagKey] = [];
+        }
+        projectConfig.excludedHoldouts[flagKey].push(holdout);
+      });
+    } else {
+      holdout.includeFlags.forEach((flagKey) => {
+        if (!projectConfig.includedHoldouts[flagKey]) {
+          projectConfig.includedHoldouts[flagKey] = [];
+        }
+        projectConfig.includedHoldouts[flagKey].push(holdout);
+      });
+    }
+  });
+}
+
+export const getHoldoutsForFlag = (projectConfig: ProjectConfig, flagKey: string): Holdout[] => {
+  if (projectConfig.flagHoldoutsMap[flagKey]) {
+    return projectConfig.flagHoldoutsMap[flagKey];
+  }
+
+  const flagHoldouts: Holdout[] = [
+    ...projectConfig.globalHoldouts.filter((holdout) => {
+      return !(projectConfig.excludedHoldouts[flagKey] || []).includes(holdout);
+    }),
+    ...(projectConfig.includedHoldouts[flagKey] || []),
+  ];
+
+  projectConfig.flagHoldoutsMap[flagKey] = flagHoldouts;
+  return flagHoldouts;
+}
+
 /**
  * Extract all audience segments used in this audience's conditions
  * @param  {Audience}     audience  Object representing the audience being parsed

lib/shared_types.ts

@@ -151,17 +151,20 @@ export interface Variation {
   variables?: VariationVariable[];
 }
 
-export interface Experiment {
+export interface ExperimentCore {
   id: string;
   key: string;
   variations: Variation[];
   variationKeyMap: { [key: string]: Variation };
-  groupId?: string;
-  layerId: string;
-  status: string;
   audienceConditions: Array<string | string[]>;
   audienceIds: string[];
   trafficAllocation: TrafficAllocation[];
+}
+
+export interface Experiment extends ExperimentCore {
+  layerId: string;
+  groupId?: string;
+  status: string;
   forcedVariations?: { [key: string]: string };
   isRollout?: boolean;
   cmab?: {
@@ -170,6 +173,14 @@ export interface Experiment {
   };
 }
 
+export type HoldoutStatus = 'Draft' | 'Running' | 'Concluded' | 'Archived';
+
+export interface Holdout extends ExperimentCore {
+  status: HoldoutStatus;
+  includeFlags: string[];
+  excludeFlags: string[];
+}
+
 export enum VariableType {
   BOOLEAN = 'boolean',
   DOUBLE = 'double',