refactor: JS SDK v5

.eslintrc.js

@@ -79,14 +79,7 @@ module.exports = {
         message: "'setImmediate' unavailable in JavaScript. Use 'setTimeout(fn, 0)' instead",
       },
     ],
-    'prettier/prettier': [
-      'warn',
-      {
-        singleQuote: true,
-        trailingComma: 'all',
-        printWidth: 100,
-      },
-    ],
+    'prettier/prettier': ['warn'],
     'unused-imports/no-unused-imports': 'error',
   },
   overrides: [

.prettierrc

@@ -0,0 +1,5 @@
+{
+  "singleQuote": true,
+  "trailingComma": "all",
+  "printWidth": 100
+}

docs/configuration-lifecycle.md

@@ -0,0 +1,70 @@
+# Configuration Lifecycle
+
+This document explains how configuration is managed throughout its lifecycle in the Eppo SDK.
+
+## Components Overview
+
+The SDK's configuration management is built around several key components that work together:
+
+- **ConfigurationFeed**: A broadcast channel that serves as the central communication point between components
+- **ConfigurationStore**: Maintains the currently active configuration used for all evaluations
+- **ConfigurationPoller**: Periodically fetches new configurations from the Eppo API
+- **PersistentConfigurationCache**: Persists configuration between application restarts
+
+## Communication Flow
+
+The ConfigurationFeed acts as a central hub through which different components communicate:
+
+![](./configuration-lifecycle.excalidraw.png)
+
+When a new configuration is received (either from network or cache), it's broadcast through the ConfigurationFeed. Components subscribe to this feed to react to configuration changes. Importantly, configurations broadcast on the ConfigurationFeed are not necessarily activated - they may never be activated at all, as they represent only the latest discovered configurations. For components interested in the currently active configuration, the ConfigurationStore provides its own broadcast channel that only emits when configurations become active.
+
+## Initialization Process
+
+During initialization, the client:
+
+1. **Configuration Loading Strategy**:
+   - `stale-while-revalidate`: Uses cached config if within `maxStaleSeconds`, while fetching fresh data
+   - `only-if-cached`: Uses cached config without network requests
+   - `no-cache`: Always fetches fresh configuration
+   - `none`: Uses only initial configuration without loading/fetching
+
+2. **Loading cached configuration**:
+   - If `initialConfiguration` is provided, uses it immediately
+   - Otherwise, tries to load cached configuration
+
+3. **Network Fetching**:
+   - If fetching is needed, attempts to fetch until success or timeout
+   - Applies backoff with jitter between retry attempts (with shorter period than normal polling)
+   - Broadcasts fetched configuration via ConfigurationFeed
+
+4. **Completion**:
+   - Initialization completes when either:
+     - Fresh configuration is fetched (for network strategies)
+     - Cache is loaded (for cache-only strategies)
+     - Timeout is reached (using best available configuration)
+
+## Ongoing Configuration Management
+
+After initialization:
+
+1. **Polling** (if enabled):
+   - ConfigurationPoller periodically fetches new configurations
+   - Uses exponential backoff with jitter for retries on failure
+   - Broadcasts new configurations through ConfigurationFeed
+
+2. **Configuration Activation**:
+   - When ConfigurationStore receives new configurations, it activates them based on strategy:
+     - `always`: Activate immediately
+     - `stale`: Activate if current config exceeds `maxStaleSeconds`
+     - `empty`: Activate if current config is empty
+     - `next-load`: Store for next initialization
+
+3. **Persistent Storage**:
+   - PersistentConfigurationCache listens to ConfigurationFeed
+   - Automatically stores new configurations to persistent storage
+   - Provides cached configurations on initialization
+
+## Evaluation
+
+For all feature flag evaluations, EppoClient always uses the currently active configuration from ConfigurationStore. This ensures consistent behavior even as configurations are updated in the background.

package.json

@@ -16,6 +16,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "default": "./dist/internal.js"
     }
   },
   "scripts": {

src/application-logger.ts

@@ -1,8 +1,9 @@
 import pino from 'pino';
 
+/** @internal */
 export const loggerPrefix = '[Eppo SDK]';
 
-// Create a Pino logger instance
+/** @internal */
 export const logger = pino({
   // eslint-disable-next-line no-restricted-globals
   level: process.env.LOG_LEVEL ?? (process.env.NODE_ENV === 'production' ? 'warn' : 'info'),

src/broadcast.ts

@@ -0,0 +1,32 @@
+export type Listener<T extends unknown[]> = (...args: T) => void;
+
+/**
+ * A broadcast channel for dispatching events to multiple listeners.
+ *
+ * @internal
+ */
+export class BroadcastChannel<T extends unknown[]> {
+  private listeners: Array<Listener<T>> = [];
+
+  public addListener(listener: Listener<T>): () => void {
+    this.listeners.push(listener);
+    return () => this.removeListener(listener);
+  }
+
+  public removeListener(listener: Listener<T>): void {
+    const idx = this.listeners.indexOf(listener);
+    if (idx !== -1) {
+      this.listeners.splice(idx, 1);
+    }
+  }
+
+  public broadcast(...args: T): void {
+    for (const listener of this.listeners) {
+      try {
+        listener(...args);
+      } catch {
+        // ignore
+      }
+    }
+  }
+}

src/client/eppo-client-assignment-details.spec.ts

@@ -3,39 +3,32 @@ import * as fs from 'fs';
 import {
   AssignmentVariationValue,
   IAssignmentTestCase,
-  MOCK_UFC_RESPONSE_FILE,
-  readMockUFCResponse,
+  readMockUfcConfiguration,
 } from '../../test/testHelpers';
-import { MemoryOnlyConfigurationStore } from '../configuration-store/memory.store';
 import { AllocationEvaluationCode } from '../flag-evaluation-details-builder';
-import { Flag, ObfuscatedFlag, Variation, VariationType } from '../interfaces';
+import { Variation, VariationType } from '../interfaces';
 import { OperatorType } from '../rules';
 import { AttributeType } from '../types';
 
 import EppoClient, { IAssignmentDetails } from './eppo-client';
-import { initConfiguration } from './test-utils';
 
 describe('EppoClient get*AssignmentDetails', () => {
   const testStart = Date.now();
 
-  global.fetch = jest.fn(() => {
-    const ufc = readMockUFCResponse(MOCK_UFC_RESPONSE_FILE);
+  let client: EppoClient;
 
-    return Promise.resolve({
-      ok: true,
-      status: 200,
-      json: () => Promise.resolve(ufc),
+  beforeEach(() => {
+    client = new EppoClient({
+      sdkKey: 'dummy',
+      sdkName: 'js-client-sdk-common',
+      sdkVersion: '1.0.0',
+      baseUrl: 'http://127.0.0.1:4000',
+      configuration: { initialConfiguration: readMockUfcConfiguration() },
     });
-  }) as jest.Mock;
-  const storage = new MemoryOnlyConfigurationStore<Flag | ObfuscatedFlag>();
-
-  beforeAll(async () => {
-    await initConfiguration(storage);
+    client.setIsGracefulFailureMode(false);
   });
 
   it('should set the details for a matched rule', () => {
-    const client = new EppoClient({ flagConfigurationStore: storage });
-    client.setIsGracefulFailureMode(false);
     const subjectAttributes = { email: '[email protected]', country: 'US' };
     const result = client.getIntegerAssignmentDetails(
       'integer-flag',
@@ -86,8 +79,6 @@ describe('EppoClient get*AssignmentDetails', () => {
   });
 
   it('should set the details for a matched split', () => {
-    const client = new EppoClient({ flagConfigurationStore: storage });
-    client.setIsGracefulFailureMode(false);
     const subjectAttributes = { email: '[email protected]', country: 'Brazil' };
     const result = client.getIntegerAssignmentDetails(
       'integer-flag',
@@ -129,8 +120,6 @@ describe('EppoClient get*AssignmentDetails', () => {
   });
 
   it('should handle matching a split allocation with a matched rule', () => {
-    const client = new EppoClient({ flagConfigurationStore: storage });
-    client.setIsGracefulFailureMode(false);
     const subjectAttributes = { id: 'alice', email: '[email protected]', country: 'Brazil' };
     const result = client.getStringAssignmentDetails(
       'new-user-onboarding',
@@ -191,8 +180,6 @@ describe('EppoClient get*AssignmentDetails', () => {
   });
 
   it('should handle unrecognized flags', () => {
-    const client = new EppoClient({ flagConfigurationStore: storage });
-    client.setIsGracefulFailureMode(false);
     const result = client.getIntegerAssignmentDetails('asdf', 'alice', {}, 0);
     expect(result).toEqual({
       variation: 0,
@@ -216,7 +203,6 @@ describe('EppoClient get*AssignmentDetails', () => {
   });
 
   it('should handle type mismatches with graceful failure mode enabled', () => {
-    const client = new EppoClient({ flagConfigurationStore: storage });
     client.setIsGracefulFailureMode(true);
     const result = client.getBooleanAssignmentDetails('integer-flag', 'alice', {}, true);
     expect(result).toEqual({
@@ -253,7 +239,6 @@ describe('EppoClient get*AssignmentDetails', () => {
   });
 
   it('should throw an error for type mismatches with graceful failure mode disabled', () => {
-    const client = new EppoClient({ flagConfigurationStore: storage });
     client.setIsGracefulFailureMode(false);
     expect(() => client.getBooleanAssignmentDetails('integer-flag', 'alice', {}, true)).toThrow();
   });
@@ -278,22 +263,6 @@ describe('EppoClient get*AssignmentDetails', () => {
       }
     };
 
-    beforeAll(async () => {
-      global.fetch = jest.fn(() => {
-        return Promise.resolve({
-          ok: true,
-          status: 200,
-          json: () => Promise.resolve(readMockUFCResponse(MOCK_UFC_RESPONSE_FILE)),
-        });
-      }) as jest.Mock;
-
-      await initConfiguration(storage);
-    });
-
-    afterAll(() => {
-      jest.restoreAllMocks();
-    });
-
     describe.each(getTestFilePaths())('for file: %s', (testFilePath: string) => {
       const testCase = parseJSON(testFilePath);
       describe.each(testCase.subjects.map(({ subjectKey }) => subjectKey))(
@@ -303,9 +272,6 @@ describe('EppoClient get*AssignmentDetails', () => {
           // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
           const subject = subjects.find((subject) => subject.subjectKey === subjectKey)!;
 
-          const client = new EppoClient({ flagConfigurationStore: storage });
-          client.setIsGracefulFailureMode(false);
-
           const focusOn = {
             testFilePath: '', // focus on test file paths (don't forget to set back to empty string!)
             subjectKey: '', // focus on subject (don't forget to set back to empty string!)

src/client/eppo-client-experiment-container.spec.ts

@@ -1,23 +1,11 @@
-import { MOCK_UFC_RESPONSE_FILE, readMockUFCResponse } from '../../test/testHelpers';
+import { readMockUfcConfiguration } from '../../test/testHelpers';
 import * as applicationLogger from '../application-logger';
-import { MemoryOnlyConfigurationStore } from '../configuration-store/memory.store';
-import { Flag, ObfuscatedFlag } from '../interfaces';
 
 import EppoClient, { IContainerExperiment } from './eppo-client';
-import { initConfiguration } from './test-utils';
 
 type Container = { name: string };
 
 describe('getExperimentContainerEntry', () => {
-  global.fetch = jest.fn(() => {
-    const ufc = readMockUFCResponse(MOCK_UFC_RESPONSE_FILE);
-    return Promise.resolve({
-      ok: true,
-      status: 200,
-      json: () => Promise.resolve(ufc),
-    });
-  }) as jest.Mock;
-
   const controlContainer: Container = { name: 'Control Container' };
   const treatment1Container: Container = { name: 'Treatment Variation 1 Container' };
   const treatment2Container: Container = { name: 'Treatment Variation 2 Container' };
@@ -29,9 +17,16 @@ describe('getExperimentContainerEntry', () => {
   let loggerWarnSpy: jest.SpyInstance;
 
   beforeEach(async () => {
-    const storage = new MemoryOnlyConfigurationStore<Flag | ObfuscatedFlag>();
-    await initConfiguration(storage);
-    client = new EppoClient({ flagConfigurationStore: storage });
+    client = new EppoClient({
+      configuration: {
+        initializationStrategy: 'none',
+        initialConfiguration: readMockUfcConfiguration(),
+      },
+      sdkKey: 'dummy',
+      sdkName: 'js-client-sdk-common',
+      sdkVersion: '1.0.0',
+      baseUrl: 'http://127.0.0.1:4000',
+    });
     client.setIsGracefulFailureMode(true);
     flagExperiment = {
       flagKey: 'my-key',