feat: Add support for client-side prerequisite events.

packages/sdk/browser/rollup.config.js

@@ -28,9 +28,9 @@ const terserOpts = {
       regex: /^_/,
       // Do not mangle '_meta', because this is part of our JSON
       // data model.
-      reserved: ['_meta']
+      reserved: ['_meta'],
     },
-  }
+  },
 };
 
 export default [
@@ -53,12 +53,6 @@ export default [
   },
   {
     ...getSharedConfig('cjs', 'dist/index.cjs.js'),
-    plugins: [
-      typescript(),
-      common(),
-      resolve(),
-      terser(terserOpts),
-      json(),
-    ],
+    plugins: [typescript(), common(), resolve(), terser(terserOpts), json()],
   },
 ];

packages/shared/common/src/api/data/LDEvaluationDetail.ts

@@ -28,6 +28,11 @@ export interface LDEvaluationDetail {
    * An object describing the main factor that influenced the flag evaluation value.
    */
   reason: LDEvaluationReason;
+
+  /**
+   * An ordered list of prerequisite flag keys evaluated while determining the flags value.
+   */
+  prerequisites?: string[];
 }
 
 export interface LDEvaluationDetailTyped<TFlag> {
@@ -47,4 +52,9 @@ export interface LDEvaluationDetailTyped<TFlag> {
    * An object describing the main factor that influenced the flag evaluation value.
    */
   reason: LDEvaluationReason;
+
+  /**
+   * An ordered list of prerequisite flag keys evaluated while determining the flags value.
+   */
+  prerequisites?: string[];
 }

packages/shared/sdk-client/__tests__/LDCLientImpl.inspections.test.ts

@@ -187,5 +187,7 @@ it('calls flag-details-changed inspectors when all flag values change', async ()
     'moonshot-demo': { reason: null, value: true, variationIndex: 0 },
     test1: { reason: null, value: 's1', variationIndex: 0 },
     'this-is-a-test': { reason: null, value: true, variationIndex: 0 },
+    'has-prereq-depth-1': { reason: { kind: 'FALLTHROUGH' }, value: true, variationIndex: 0 },
+    'is-prereq': { reason: { kind: 'FALLTHROUGH' }, value: true, variationIndex: 0 },
   });
 });

packages/shared/sdk-client/__tests__/LDClientImpl.events.test.ts

@@ -199,4 +199,45 @@ describe('sdk-client object', () => {
       expect.stringMatching(/was called with a non-numeric/),
     );
   });
+
+  it('sends events for prerequisite flags', async () => {
+    await ldc.identify({ kind: 'user', key: 'bob' });
+    ldc.variation('has-prereq-depth-1', false);
+    ldc.flush();
+
+    // Prerequisite evaluation event should be emitted before the evaluation event for the flag
+    // being evaluated.
+    expect(mockedSendEvent).toHaveBeenNthCalledWith(
+      2,
+      expect.objectContaining({
+        context: expect.anything(),
+        creationDate: expect.any(Number),
+        default: undefined,
+        key: 'is-prereq',
+        kind: 'feature',
+        samplingRatio: 1,
+        trackEvents: true,
+        value: true,
+        variation: 0,
+        version: 1,
+        withReasons: false,
+      }),
+    );
+    expect(mockedSendEvent).toHaveBeenNthCalledWith(
+      3,
+      expect.objectContaining({
+        context: expect.anything(),
+        creationDate: expect.any(Number),
+        default: false,
+        key: 'has-prereq-depth-1',
+        kind: 'feature',
+        samplingRatio: 1,
+        trackEvents: true,
+        value: true,
+        variation: 0,
+        version: 4,
+        withReasons: false,
+      }),
+    );
+  });
 });

packages/shared/sdk-client/__tests__/LDClientImpl.storage.test.ts

@@ -104,6 +104,8 @@ describe('sdk-client storage', () => {
       'easter-i-tunes-special': false,
       'easter-specials': 'no specials',
       fdsafdsafdsafdsa: true,
+      'has-prereq-depth-1': true,
+      'is-prereq': true,
       'log-level': 'warn',
       'moonshot-demo': true,
       test1: 's1',
@@ -156,6 +158,8 @@ describe('sdk-client storage', () => {
       'easter-i-tunes-special': false,
       'easter-specials': 'no specials',
       fdsafdsafdsafdsa: true,
+      'has-prereq-depth-1': true,
+      'is-prereq': true,
       'log-level': 'warn',
       'moonshot-demo': true,
       test1: 's1',
@@ -218,6 +222,8 @@ describe('sdk-client storage', () => {
       'easter-i-tunes-special': false,
       'easter-specials': 'no specials',
       fdsafdsafdsafdsa: true,
+      'has-prereq-depth-1': true,
+      'is-prereq': true,
       'log-level': 'warn',
       'moonshot-demo': true,
       test1: 's1',
@@ -388,6 +394,8 @@ describe('sdk-client storage', () => {
       'easter-i-tunes-special': false,
       'easter-specials': 'no specials',
       fdsafdsafdsafdsa: true,
+      'has-prereq-depth-1': true,
+      'is-prereq': true,
       'log-level': 'warn',
       'moonshot-demo': true,
       test1: 's1',
@@ -517,6 +525,8 @@ describe('sdk-client storage', () => {
       'easter-i-tunes-special': false,
       'easter-specials': 'no specials',
       fdsafdsafdsafdsa: true,
+      'has-prereq-depth-1': true,
+      'is-prereq': true,
       'log-level': 'warn',
       'moonshot-demo': true,
       test1: 's1',

packages/shared/sdk-client/__tests__/LDClientImpl.test.ts

@@ -103,6 +103,8 @@ describe('sdk-client object', () => {
       'easter-i-tunes-special': false,
       'easter-specials': 'no specials',
       fdsafdsafdsafdsa: true,
+      'has-prereq-depth-1': true,
+      'is-prereq': true,
       'log-level': 'warn',
       'moonshot-demo': true,
       test1: 's1',

packages/shared/sdk-client/__tests__/LDClientImpl.timeout.test.ts

@@ -89,6 +89,8 @@ describe('sdk-client identify timeout', () => {
       'easter-i-tunes-special': false,
       'easter-specials': 'no specials',
       fdsafdsafdsafdsa: true,
+      'has-prereq-depth-1': true,
+      'is-prereq': true,
       'log-level': 'warn',
       'moonshot-demo': true,
       test1: 's1',
@@ -112,6 +114,8 @@ describe('sdk-client identify timeout', () => {
       'easter-i-tunes-special': false,
       'easter-specials': 'no specials',
       fdsafdsafdsafdsa: true,
+      'has-prereq-depth-1': true,
+      'is-prereq': true,
       'log-level': 'warn',
       'moonshot-demo': true,
       test1: 's1',

packages/shared/sdk-client/__tests__/evaluation/mockResponse.json

@@ -54,5 +54,24 @@
     "value": true,
     "variation": 0,
     "trackEvents": false
+  },
+  "is-prereq": {
+    "value": true,
+    "variation": 0,
+    "reason": {
+      "kind": "FALLTHROUGH"
+    },
+    "version": 1,
+    "trackEvents": true
+  },
+  "has-prereq-depth-1": {
+    "value": true,
+    "variation": 0,
+    "prerequisites": ["is-prereq"],
+    "reason": {
+      "kind": "FALLTHROUGH"
+    },
+    "version": 4,
+    "trackEvents": true
   }
 }

packages/shared/sdk-client/src/LDClientImpl.ts

@@ -327,7 +327,7 @@ export default class LDClientImpl implements LDClient {
       return createErrorEvaluationDetail(ErrorKinds.FlagNotFound, defaultValue);
     }
 
-    const { reason, value, variation } = foundItem.flag;
+    const { reason, value, variation, prerequisites } = foundItem.flag;
 
     if (typeChecker) {
       const [matched, type] = typeChecker(value);
@@ -350,11 +350,15 @@ export default class LDClientImpl implements LDClient {
       }
     }
 
-    const successDetail = createSuccessEvaluationDetail(value, variation, reason);
+    const successDetail = createSuccessEvaluationDetail(value, variation, reason, prerequisites);
     if (value === undefined || value === null) {
       this.logger.debug('Result value is null. Providing default value.');
       successDetail.value = defaultValue;
     }
+
+    successDetail.prerequisites?.forEach((prereqKey) => {
+      this.variation(prereqKey, undefined);
+    });
     this._eventProcessor?.sendEvent(
       eventFactory.evalEventClient(
         flagKey,

packages/shared/sdk-client/src/evaluation/evaluationDetail.ts

@@ -17,10 +17,15 @@ export function createSuccessEvaluationDetail(
   value: LDFlagValue,
   variationIndex?: number,
   reason?: LDEvaluationReason,
+  prerequisites?: string[],
 ): LDEvaluationDetail {
-  return {
+  const res: LDEvaluationDetail = {
     value,
     variationIndex: variationIndex ?? null,
     reason: reason ?? null,
   };
+  if (prerequisites) {
+    res.prerequisites = prerequisites;
+  }
+  return res;
 }

packages/shared/sdk-client/src/types/index.ts

@@ -10,6 +10,7 @@ export interface Flag {
   reason?: LDEvaluationReason;
   debugEventsUntilDate?: number;
   deleted?: boolean;
+  prerequisites?: string[];
 }
 
 export interface PatchFlag extends Flag {

packages/shared/sdk-server/__tests__/LDClient.allFlags.test.ts

@@ -268,6 +268,60 @@ describe('given an LDClient with test data', () => {
       done();
     });
   });
+
+  it('includes prerequisites in flag meta', async () => {
+    await td.update(td.flag('is-prereq').valueForAll(true));
+    await td.usePreconfiguredFlag({
+      key: 'has-prereq-depth-1',
+      on: true,
+      prerequisites: [
+        {
+          key: 'is-prereq',
+          variation: 0,
+        },
+      ],
+      fallthrough: {
+        variation: 0,
+      },
+      offVariation: 1,
+      variations: [true, false],
+      clientSideAvailability: {
+        usingMobileKey: true,
+        usingEnvironmentId: true,
+      },
+      clientSide: true,
+      version: 4,
+    });
+
+    const state = await client.allFlagsState(defaultUser, {
+      withReasons: true,
+      detailsOnlyForTrackedFlags: false,
+    });
+    expect(state.valid).toEqual(true);
+    expect(state.allValues()).toEqual({ 'is-prereq': true, 'has-prereq-depth-1': true });
+    expect(state.toJSON()).toEqual({
+      'is-prereq': true,
+      'has-prereq-depth-1': true,
+      $flagsState: {
+        'is-prereq': {
+          variation: 0,
+          reason: {
+            kind: 'FALLTHROUGH',
+          },
+          version: 1,
+        },
+        'has-prereq-depth-1': {
+          variation: 0,
+          prerequisites: ['is-prereq'],
+          reason: {
+            kind: 'FALLTHROUGH',
+          },
+          version: 4,
+        },
+      },
+      $valid: true,
+    });
+  });
 });
 
 describe('given an offline client', () => {

packages/shared/sdk-server/__tests__/LDClient.evaluation.test.ts

@@ -253,6 +253,75 @@ describe('given an LDClient with test data', () => {
     expect(res.reason.kind).toEqual('ERROR');
     expect(res.reason.errorKind).toEqual('WRONG_TYPE');
   });
+
+  it('includes prerequisite information for flags with prerequisites', async () => {
+    await td.update(td.flag('is-prereq').valueForAll(true));
+    await td.usePreconfiguredFlag({
+      key: 'has-prereq-depth-1',
+      on: true,
+      prerequisites: [
+        {
+          key: 'is-prereq',
+          variation: 0,
+        },
+      ],
+      fallthrough: {
+        variation: 0,
+      },
+      offVariation: 1,
+      variations: [true, false],
+      clientSideAvailability: {
+        usingMobileKey: true,
+        usingEnvironmentId: true,
+      },
+      clientSide: true,
+      version: 4,
+    });
+
+    const res = await client.variationDetail('has-prereq-depth-1', defaultUser, false);
+    expect(res.value).toEqual(true);
+    expect(res.reason.kind).toEqual('FALLTHROUGH');
+    expect(res.prerequisites).toEqual(['is-prereq']);
+  });
+
+  it.each([
+    ['boolVariationDetail', true, false],
+    ['numberVariationDetail', 42, 3.14],
+    ['stringVariationDetail', 'value', 'default'],
+    ['jsonVariationDetail', { value: 'value' }, { value: 'default' }],
+  ])(
+    'includes prerequisite information for typed evals',
+    async (method: string, value: any, def: any) => {
+      await td.update(td.flag('is-prereq').valueForAll(true));
+      await td.usePreconfiguredFlag({
+        key: 'has-prereq-depth-1',
+        on: true,
+        prerequisites: [
+          {
+            key: 'is-prereq',
+            variation: 0,
+          },
+        ],
+        fallthrough: {
+          variation: 0,
+        },
+        offVariation: 1,
+        variations: [value, def],
+        clientSideAvailability: {
+          usingMobileKey: true,
+          usingEnvironmentId: true,
+        },
+        clientSide: true,
+        version: 4,
+      });
+
+      // @ts-ignore Typescript cannot infer the matching method types.
+      const res = await client[method]('has-prereq-depth-1', defaultUser, def);
+      expect(res.value).toEqual(value);
+      expect(res.reason.kind).toEqual('FALLTHROUGH');
+      expect(res.prerequisites).toEqual(['is-prereq']);
+    },
+  );
 });
 
 describe('given an offline client', () => {