feat: create offlinePrecomputedInit

Makefile

@@ -27,14 +27,15 @@ help: Makefile
 testDataDir := test/data/
 tempDir := ${testDataDir}temp/
 gitDataDir := ${tempDir}sdk-test-data/
-branchName := main
+branchName := sameeran/ff-3687-obfuscated-precomputed-json
 githubRepoLink := https://github.com/Eppo-exp/sdk-test-data.git
 .PHONY: test-data
 test-data: 
 	rm -rf $(testDataDir)
 	mkdir -p $(tempDir)
 	git clone -b ${branchName} --depth 1 --single-branch ${githubRepoLink} ${gitDataDir}
 	cp -r ${gitDataDir}ufc ${testDataDir}
+	cp -r ${gitDataDir}configuration-wire ${testDataDir}
 	rm -rf ${tempDir}
 
 ## prepare
@@ -49,4 +50,4 @@ prepare: test-data
 ## test
 .PHONY: test
 test: test test-data
-	yarn test:unit
+	yarn test:unit

js-client-sdk.api.md

@@ -19,6 +19,7 @@ import { IAssignmentLogger } from '@eppo/js-client-sdk-common';
 import { IAsyncStore } from '@eppo/js-client-sdk-common';
 import { IContainerExperiment } from '@eppo/js-client-sdk-common';
 import { ObfuscatedFlag } from '@eppo/js-client-sdk-common';
+import { PrecomputedFlag } from '@eppo/js-client-sdk-common';
 
 // @public
 export function buildStorageKeySuffix(apiKey: string): string;
@@ -149,15 +150,32 @@ export function init(config: IClientConfig): Promise<EppoClient>;
 
 // @public
 export interface IPrecomputedClientConfig extends IBaseRequestConfig {
-    subjectAttributes?: Record<string, AttributeType>;
-    subjectKey: string;
+    // Warning: (ae-forgotten-export) The symbol "IPrecompute" needs to be exported by the entry point index.d.ts
+    //
+    // (undocumented)
+    precompute: IPrecompute;
+}
+
+// @public
+export interface IPrecomputedClientConfigSync {
+    // (undocumented)
+    assignmentLogger?: IAssignmentLogger;
+    // (undocumented)
+    precompute: IPrecompute;
+    // (undocumented)
+    precomputedAssignments: Record<string, PrecomputedFlag>;
+    // (undocumented)
+    throwOnFailedInitialization?: boolean;
 }
 
 export { ObfuscatedFlag }
 
 // @public
 export function offlineInit(config: IClientConfigSync): EppoClient;
 
+// @public
+export function offlinePrecomputedInit(config: IPrecomputedClientConfigSync): EppoPrecomputedClient;
+
 // @public
 export function precomputedInit(config: IPrecomputedClientConfig): Promise<EppoPrecomputedClient>;
 

src/i-client-config.ts

@@ -1,5 +1,4 @@
 import { AttributeType, Flag, IAssignmentLogger, IAsyncStore } from '@eppo/js-client-sdk-common';
-import { EventDispatcherConfig } from '@eppo/js-client-sdk-common/src/events/default-event-dispatcher';
 
 import { ServingStoreUpdateStrategy } from './isolatable-hybrid.store';
 
@@ -64,10 +63,10 @@ interface IBaseRequestConfig {
 }
 
 /**
- * Configuration for Eppo precomputed client initialization
+ * Configuration for precomputed flag assignments
  * @public
  */
-export interface IPrecomputedClientConfig extends IBaseRequestConfig {
+export interface IPrecompute {
   /**
    * Subject key to use for precomputed flag assignments.
    */
@@ -79,6 +78,14 @@ export interface IPrecomputedClientConfig extends IBaseRequestConfig {
   subjectAttributes?: Record<string, AttributeType>;
 }
 
+/**
+ * Configuration for Eppo precomputed client initialization
+ * @public
+ */
+export interface IPrecomputedClientConfig extends IBaseRequestConfig {
+  precompute: IPrecompute;
+}
+
 /**
  * Configuration for regular client initialization
  * @public

src/index.spec.ts

@@ -18,9 +18,11 @@ import * as td from 'testdouble';
 import {
   getTestAssignments,
   IAssignmentTestCase,
+  MOCK_PRECOMPUTED_RESPONSE_FILE,
   MOCK_UFC_RESPONSE_FILE,
   OBFUSCATED_MOCK_UFC_RESPONSE_FILE,
   readAssignmentTestData,
+  readMockPrecomputedResponse,
   readMockUfcResponse,
   validateTestAssignments,
 } from '../test/testHelpers';
@@ -36,6 +38,7 @@ import {
   IAssignmentLogger,
   init,
   offlineInit,
+  offlinePrecomputedInit,
   precomputedInit,
 } from './index';
 
@@ -1066,59 +1069,14 @@ describe('EppoPrecomputedJSClient E2E test', () => {
 
   beforeAll(async () => {
     global.fetch = jest.fn(() => {
+      const precomputedConfigurationWire = readMockPrecomputedResponse(
+        MOCK_PRECOMPUTED_RESPONSE_FILE,
+      );
+      const precomputedResponse = JSON.parse(precomputedConfigurationWire).precomputed.response;
       return Promise.resolve({
         ok: true,
         status: 200,
-        json: () =>
-          Promise.resolve({
-            createdAt: '2024-11-18T14:23:39.456Z',
-            format: 'PRECOMPUTED',
-            environment: {
-              name: 'Test',
-            },
-            flags: {
-              'string-flag': {
-                allocationKey: 'allocation-123',
-                variationKey: 'variation-123',
-                variationType: 'STRING',
-                variationValue: 'red',
-                extraLogging: {},
-                doLog: true,
-              },
-              'boolean-flag': {
-                allocationKey: 'allocation-124',
-                variationKey: 'variation-124',
-                variationType: 'BOOLEAN',
-                variationValue: true,
-                extraLogging: {},
-                doLog: true,
-              },
-              'numeric-flag': {
-                allocationKey: 'allocation-126',
-                variationKey: 'variation-126',
-                variationType: 'NUMERIC',
-                variationValue: 3.14,
-                extraLogging: {},
-                doLog: true,
-              },
-              'integer-flag': {
-                allocationKey: 'allocation-125',
-                variationKey: 'variation-125',
-                variationType: 'INTEGER',
-                variationValue: 42,
-                extraLogging: {},
-                doLog: true,
-              },
-              'json-flag': {
-                allocationKey: 'allocation-127',
-                variationKey: 'variation-127',
-                variationType: 'JSON',
-                variationValue: '{"key": "value", "number": 123}',
-                extraLogging: {},
-                doLog: true,
-              },
-            },
-          }),
+        json: () => Promise.resolve(precomputedResponse),
       });
     }) as jest.Mock;
 
@@ -1128,8 +1086,10 @@ describe('EppoPrecomputedJSClient E2E test', () => {
       apiKey: 'dummy',
       baseUrl: 'http://127.0.0.1:4000',
       assignmentLogger: mockLogger,
-      subjectKey: 'test-subject',
-      subjectAttributes: { attr1: 'value1' },
+      precompute: {
+        subjectKey: 'test-subject',
+        subjectAttributes: { attr1: 'value1' },
+      },
     });
   });
 
@@ -1179,6 +1139,50 @@ describe('EppoPrecomputedJSClient E2E test', () => {
   });
 });
 
+describe('offlinePrecomputedInit', () => {
+  let mockLogger: IAssignmentLogger;
+  let precomputedConfigurationWire: string;
+
+  beforeAll(() => {
+    precomputedConfigurationWire = readMockPrecomputedResponse(MOCK_PRECOMPUTED_RESPONSE_FILE);
+  });
+
+  beforeEach(() => {
+    mockLogger = td.object<IAssignmentLogger>();
+    // Reset the static instance before each test
+    jest.isolateModules(() => {
+      // eslint-disable-next-line @typescript-eslint/no-var-requires
+      require('./index');
+    });
+  });
+
+  it('initializes with precomputed assignments', () => {
+    const client = offlinePrecomputedInit({
+      precomputedConfigurationWire,
+      assignmentLogger: mockLogger,
+    });
+
+    expect(client.getStringAssignment('string-flag', 'default')).toBe('red');
+    expect(td.explain(mockLogger.logAssignment).callCount).toBe(1);
+    expect(td.explain(mockLogger.logAssignment).calls[0]?.args[0]).toMatchObject({
+      subject: 'test-subject-key',
+      featureFlag: 'string-flag',
+      allocation: 'allocation-123',
+      variation: 'variation-123',
+      subjectAttributes: {
+        device: 'iPhone',
+        country: 'USA',
+      },
+    });
+  });
+
+  it('initializes without an assignment logger', () => {
+    const client = offlinePrecomputedInit({ precomputedConfigurationWire });
+
+    expect(client.getStringAssignment('string-flag', 'default')).toBe('red');
+  });
+});
+
 describe('EppoClient config', () => {
   it('should initialize event dispatcher with default values', async () => {
     global.fetch = jest.fn(() => {

src/index.ts

@@ -17,8 +17,10 @@
   ObfuscatedFlag,
   BoundedEventQueue,
   validation,
+  PrecomputedFlag,
   Event,
 } from '@eppo/js-client-sdk-common';
+import { Environment, FormatEnum } from '@eppo/js-client-sdk-common/dist/interfaces';
 
 import { assignmentCacheFactory } from './cache/assignment-cache-factory';
 import HybridAssignmentCache from './cache/hybrid-assignment-cache';
@@ -32,7 +34,7 @@
 } from './configuration-factory';
 import BrowserNetworkStatusListener from './events/browser-network-status-listener';
 import LocalStorageBackedNamedEventQueue from './events/local-storage-backed-named-event-queue';
-import { IClientConfig, IPrecomputedClientConfig } from './i-client-config';
+import { IClientConfig, IPrecompute, IPrecomputedClientConfig } from './i-client-config';
 import { sdkName, sdkVersion } from './sdk-data';
 
 /**
@@ -465,7 +467,7 @@
       // both failed, make the "fatal" error the fetch one
       initializationError = initFromFetchError;
     }
   } catch (error: any) {
     initializationError = error;
   }
 
@@ -558,13 +560,12 @@
   config: IPrecomputedClientConfig,
 ): Promise<EppoPrecomputedClient> {
   validation.validateNotBlank(config.apiKey, 'API key required');
-  validation.validateNotBlank(config.subjectKey, 'Subject key required');
+  validation.validateNotBlank(config.precompute.subjectKey, 'Subject key required');
 
   const instance = EppoPrecomputedJSClient.instance;
   const {
     apiKey,
-    subjectKey,
-    subjectAttributes = {},
+    precompute: { subjectKey, subjectAttributes = {} },
     baseUrl,
     requestTimeoutMs,
     numInitialRequestRetries,
@@ -584,10 +585,7 @@
     sdkName,
     sdkVersion,
     baseUrl,
-    precompute: {
-      subjectKey,
-      subjectAttributes,
-    },
+    precompute: { subjectKey, subjectAttributes },
     requestTimeoutMs,
     numInitialRequestRetries,
     numPollRequestRetries,
@@ -605,6 +603,92 @@
   return EppoPrecomputedJSClient.instance;
 }
 
+/**
+ * Initializes the Eppo precomputed client with configuration parameters.
+ *
+ * The purpose is for use-cases where the precomputed assignments are available from an external process
+ * that can bootstrap the SDK.
+ *
+ * This method should be called once on application startup.
+ *
+ * @param config - client configuration
+ * @returns a singleton precomputed client instance
+ * @public
+ */
+export interface IPrecomputedClientConfigSync {
+  precomputedConfigurationWire: string;
+  assignmentLogger?: IAssignmentLogger;
+  throwOnFailedInitialization?: boolean;
+}
+
+export interface IConfigurationWire {
+  version: number;
+  precomputed: {
+    subjectKey: string;
+    subjectAttributes: Record<string, AttributeType>;
+    fetchedAt: string;
+    response: {
+      createdAt: string;
+      format: FormatEnum;
+      obfuscated: boolean;
+      environment: Environment;
+      flags: Record<string, PrecomputedFlag>;
+    };
+  };
+}
+
+/**
+ * Initializes the Eppo precomputed client with configuration parameters.
+ *
+ * The purpose is for use-cases where the precomputed assignments are available from an external process
+ * that can bootstrap the SDK.
+ *
+ * This method should be called once on application startup.
+ *
+ * @param config - precomputed client configuration
+ * @returns a singleton precomputed client instance
+ * @public
+ */
+export function offlinePrecomputedInit(
+  config: IPrecomputedClientConfigSync,
+): EppoPrecomputedClient {
+  const throwOnFailedInitialization = config.throwOnFailedInitialization ?? true;
+
+  const configurationWire: IConfigurationWire = JSON.parse(config.precomputedConfigurationWire);
+  const { subjectKey, subjectAttributes, response } = configurationWire.precomputed;
+  const parsedResponse = response; // TODO: use a JSON.parse when the obfuscated version is usable
+
+  try {
+    const memoryOnlyPrecomputedStore = precomputedFlagsStorageFactory();
+    memoryOnlyPrecomputedStore
+      .setEntries(parsedResponse.flags)
+      .catch((err) =>
+        applicationLogger.warn('Error setting precomputed assignments for memory-only store', err),
+      );
+
+    EppoPrecomputedJSClient.instance.setSubjectAndPrecomputedFlagStore(
+      subjectKey,
+      subjectAttributes,
+      memoryOnlyPrecomputedStore,
+    );
+
+    if (config.assignmentLogger) {
+      EppoPrecomputedJSClient.instance.setAssignmentLogger(config.assignmentLogger);
+    }
+  } catch (error) {
+    applicationLogger.warn(
+      'Eppo SDK encountered an error initializing precomputed client, assignment calls will return the default value and not be logged',
+    );
+    if (throwOnFailedInitialization) {
+      throw error;
+    }
+  }
+
+  EppoPrecomputedJSClient.instance.setIsObfuscated(parsedResponse.obfuscated);
+  EppoPrecomputedJSClient.initialized = true;
+  return EppoPrecomputedJSClient.instance;
+}
+
 /**
  * Used to access a singleton SDK precomputed client instance.
  * Use the method after calling precomputedInit() to initialize the client.