@statsig/js-client 0.0.1-beta.10

package/src/StatsigClient.ts

@@ -0,0 +1,251 @@
+import type {
+  DataAdapterResult,
+  EvaluationOptions,
+  EvaluationsDataAdapter,
+  FeatureGate,
+  StatsigUser,
+} from '@statsig/client-core';
+import {
+  DEFAULT_EVAL_OPTIONS,
+  DJB2,
+  DynamicConfig,
+  Experiment,
+  Layer,
+  Log,
+  PrecomputedEvaluationsInterface,
+  StatsigClientBase,
+  StatsigEvent,
+  createConfigExposure,
+  createGateExposure,
+  createLayerParameterExposure,
+  makeDynamicConfig,
+  makeFeatureGate,
+  makeLayer,
+  monitorClass,
+  normalizeUser,
+} from '@statsig/client-core';
+
+import EvaluationStore from './EvaluationStore';
+import Network from './Network';
+import { StatsigEvaluationsDataAdapter } from './StatsigEvaluationsDataAdapter';
+import './StatsigMetadataAdditions';
+import type { StatsigOptions } from './StatsigOptions';
+
+export default class StatsigClient
+  extends StatsigClientBase<EvaluationsDataAdapter>
+  implements PrecomputedEvaluationsInterface
+{
+  private _options: StatsigOptions;
+  private _network: Network;
+  private _store: EvaluationStore;
+  private _user: StatsigUser;
+
+  constructor(
+    sdkKey: string,
+    user: StatsigUser,
+    options: StatsigOptions | null = null,
+  ) {
+    const network = new Network(options, (e) => {
+      this._emit(e);
+    });
+
+    super(
+      sdkKey,
+      options?.dataAdapter ?? new StatsigEvaluationsDataAdapter(),
+      network,
+      options,
+    );
+
+    monitorClass(this._errorBoundary, this);
+    monitorClass(this._errorBoundary, network);
+
+    this._options = options ?? {};
+    this._store = new EvaluationStore(sdkKey);
+    this._network = network;
+    this._user = user;
+  }
+
+  initializeSync(): void {
+    this.updateUserSync(this._user);
+  }
+
+  initializeAsync(): Promise<void> {
+    return this.updateUserAsync(this._user);
+  }
+
+  getCurrentUser(): StatsigUser {
+    return JSON.parse(JSON.stringify(this._user)) as StatsigUser;
+  }
+
+  updateUserSync(user: StatsigUser): void {
+    this._resetForUser(user);
+
+    const result = this.dataAdapter.getDataSync(this._user);
+    this._store.setValuesFromDataAdapter(result);
+
+    this._store.finalize();
+    this._setStatus('Ready', result);
+
+    this._runPostUpdate(result ?? null, this._user);
+  }
+
+  async updateUserAsync(user: StatsigUser): Promise<void> {
+    this._resetForUser(user);
+
+    const initiator = this._user;
+
+    let result = this.dataAdapter.getDataSync(initiator);
+    this._setStatus('Loading', result);
+
+    this._store.setValuesFromDataAdapter(result);
+
+    result = await this.dataAdapter.getDataAsync(result, initiator);
+
+    // ensure the user hasn't changed while we were waiting
+    if (initiator === this._user) {
+      this._store.setValuesFromDataAdapter(result);
+    }
+
+    this._store.finalize();
+    this._setStatus('Ready', result);
+  }
+
+  async shutdown(): Promise<void> {
+    await this._logger.shutdown();
+  }
+
+  checkGate(
+    name: string,
+    options: EvaluationOptions = DEFAULT_EVAL_OPTIONS,
+  ): boolean {
+    return this.getFeatureGate(name, options).value;
+  }
+
+  getFeatureGate(
+    name: string,
+    options: EvaluationOptions = DEFAULT_EVAL_OPTIONS,
+  ): FeatureGate {
+    const hash = DJB2(name);
+
+    const { evaluation, details } = this._store.getGate(hash);
+    const gate = makeFeatureGate(name, details, evaluation);
+    const overridden = this._overrideAdapter?.getGateOverride?.(
+      gate,
+      this._user,
+    );
+
+    const result = overridden ?? gate;
+
+    this._enqueueExposure(
+      name,
+      options,
+      createGateExposure(this._user, result, evaluation?.secondary_exposures),
+    );
+
+    this._emit({ event: 'gate_evaluation', gate: result });
+
+    return result;
+  }
+
+  getDynamicConfig(
+    name: string,
+    options: EvaluationOptions = DEFAULT_EVAL_OPTIONS,
+  ): DynamicConfig {
+    const dynamicConfig = this._getConfigImpl('dynamic_config', name, options);
+    this._emit({ event: 'dynamic_config_evaluation', dynamicConfig });
+    return dynamicConfig;
+  }
+
+  getExperiment(
+    name: string,
+    options: EvaluationOptions = DEFAULT_EVAL_OPTIONS,
+  ): Experiment {
+    const experiment = this._getConfigImpl('experiment', name, options);
+    this._emit({ event: 'experiment_evaluation', experiment });
+    return experiment;
+  }
+
+  getLayer(
+    name: string,
+    options: EvaluationOptions = DEFAULT_EVAL_OPTIONS,
+  ): Layer {
+    const hash = DJB2(name);
+
+    const { evaluation, details } = this._store.getLayer(hash);
+    const layer = makeLayer(name, details, evaluation);
+
+    const overridden = this._overrideAdapter?.getLayerOverride?.(
+      layer,
+      this._user,
+    );
+
+    const result = overridden ?? layer;
+    this._emit({ event: 'layer_evaluation', layer: result });
+
+    return {
+      ...result,
+      getValue: (param) => {
+        if (!(param in result._value)) {
+          return null;
+        }
+
+        const exposure = createLayerParameterExposure(
+          this._user,
+          result,
+          param,
+          result.__evaluation,
+        );
+
+        this._enqueueExposure(name, options, exposure);
+
+        return result._value[param] ?? null;
+      },
+    };
+  }
+
+  logEvent(event: StatsigEvent): void {
+    this._logger.enqueue({ ...event, user: this._user, time: Date.now() });
+  }
+
+  private _runPostUpdate(
+    current: DataAdapterResult | null,
+    user: StatsigUser,
+  ): void {
+    this.dataAdapter.getDataAsync(current, user).catch((err) => {
+      Log.error('An error occurred after update.', err);
+    });
+  }
+
+  private _resetForUser(user: StatsigUser) {
+    this._logger.reset();
+    this._store.reset();
+
+    this._user = normalizeUser(user, this._options.environment);
+  }
+
+  private _getConfigImpl(
+    kind: 'experiment' | 'dynamic_config',
+    name: string,
+    options: EvaluationOptions,
+  ): DynamicConfig {
+    const hash = DJB2(name);
+    const { evaluation, details } = this._store.getConfig(hash);
+
+    const config = makeDynamicConfig(name, details, evaluation);
+
+    const overridden =
+      kind === 'experiment'
+        ? this._overrideAdapter?.getExperimentOverride?.(config, this._user)
+        : this._overrideAdapter?.getDynamicConfigOverride?.(config, this._user);
+
+    const result = overridden ?? config;
+
+    this._enqueueExposure(
+      name,
+      options,
+      createConfigExposure(this._user, result, evaluation?.secondary_exposures),
+    );
+
+    return result;
+  }
+}

package/src/StatsigEvaluationsDataAdapter.ts

@@ -0,0 +1,36 @@
+import {
+  DataAdapterCore,
+  EvaluationsDataAdapter,
+  StatsigOptionsCommon,
+  StatsigUser,
+} from '@statsig/client-core';
+
+import Network from './Network';
+
+export class StatsigEvaluationsDataAdapter
+  extends DataAdapterCore
+  implements EvaluationsDataAdapter
+{
+  private _network: Network | null = null;
+
+  constructor() {
+    super('EvaluationsDataAdapter', 'evaluations');
+  }
+
+  override attach(sdkKey: string, options: StatsigOptionsCommon | null): void {
+    super.attach(sdkKey, options);
+    this._network = new Network(options ?? {});
+  }
+
+  protected override async _fetchFromNetwork(
+    current: string | null,
+    user?: StatsigUser,
+  ): Promise<string | null> {
+    const result = await this._network?.fetchEvaluations(
+      this._getSdkKey(),
+      current,
+      user,
+    );
+    return result ?? null;
+  }
+}

package/src/StatsigMetadataAdditions.ts

@@ -0,0 +1,7 @@
+import { StatsigMetadataProvider } from '@statsig/client-core';
+
+export const SDK_TYPE = 'javascript-client';
+
+StatsigMetadataProvider.add({
+  sdkType: SDK_TYPE,
+});

package/src/StatsigOptions.ts

@@ -0,0 +1,25 @@
+import {
+  EvaluationsDataAdapter,
+  Flatten,
+  StatsigOptionsCommon,
+} from '@statsig/client-core';
+
+export type StatsigOptions = Flatten<
+  StatsigOptionsCommon & {
+    /**
+     * An implementor of {@link EvaluationsDataAdapter}, used to customize the initialization/update flow.
+     *
+     * default: `StatsigEvaluationsDataAdapter`
+     *
+     * @see {@link https://docs.statsig.com/client/javascript-sdk/using-evaluations-data-adapter}
+     */
+    dataAdapter?: EvaluationsDataAdapter;
+
+    /**
+     * The URL used to fetch the latest evaluations for a given user. Takes precedence over {@link StatsigOptionsCommon.api}.
+     *
+     * default: `https://api.statsig.com/v1/initialize`
+     */
+    initializeUrl?: string;
+  }
+>;

package/src/__tests__/CacheEviction.test.ts

@@ -0,0 +1,55 @@
+import fetchMock from 'jest-fetch-mock';
+
+import { DataAdapterCachePrefix } from '@statsig/client-core';
+
+import { StatsigEvaluationsDataAdapter } from '../StatsigEvaluationsDataAdapter';
+import { MockLocalStorage } from './MockLocalStorage';
+import InitializeResponse from './initialize.json';
+
+describe('Cache Eviction', () => {
+  let storageMock: MockLocalStorage;
+  let adapter: StatsigEvaluationsDataAdapter;
+
+  beforeAll(async () => {
+    storageMock = MockLocalStorage.enabledMockStorage();
+    storageMock.clear();
+
+    fetchMock.enableMocks();
+    fetchMock.mockResponse(JSON.stringify(InitializeResponse));
+
+    adapter = new StatsigEvaluationsDataAdapter();
+    adapter.attach('client-key', null);
+
+    for (let i = 0; i < 20; i++) {
+      // eslint-disable-next-line no-await-in-loop
+      await adapter.getDataAsync(null, { userID: `user-${i}` });
+    }
+  });
+
+  afterAll(() => {
+    MockLocalStorage.disableMockStorage();
+  });
+
+  it('should only have 10 entries in _inMemoryCache', () => {
+    const entries = Object.entries((adapter as any)._inMemoryCache);
+    expect(entries.length).toBe(10);
+  });
+
+  it('should only have 10 user cache entries', () => {
+    const entries = Object.entries(storageMock.data).filter((e) =>
+      e[0].startsWith(DataAdapterCachePrefix),
+    );
+    expect(entries.length).toBe(10);
+  });
+
+  it('only writes the expected keys', () => {
+    const keys = Object.keys(storageMock.data).map((k) =>
+      k.split('.').slice(0, 2).join('.'),
+    );
+    expect(Array.from(new Set(keys))).toEqual([
+      'statsig.stable_id',
+      'statsig.last_modified_time',
+      DataAdapterCachePrefix,
+    ]);
+  });
+});

package/src/__tests__/ClientErrrorBoundary.test.ts

@@ -0,0 +1,29 @@
+import fetchMock from 'jest-fetch-mock';
+
+import { LogLevel } from '@statsig/client-core';
+
+import StatsigClient from '../StatsigClient';
+import InitializeResponse from './initialize.json';
+
+describe('Client Error Boundary', () => {
+  let client: StatsigClient;
+
+  beforeAll(async () => {
+    client = new StatsigClient(
+      'client-key',
+      { userID: '' },
+      {
+        logLevel: LogLevel.None,
+      },
+    );
+
+    fetchMock.enableMocks();
+    fetchMock.mockResponse(JSON.stringify(InitializeResponse));
+    client.initializeSync();
+  });
+
+  it('catches errors', () => {
+    (client as any)._logger = 1;
+    expect(() => client.checkGate('test_public')).not.toThrow();
+  });
+});

package/src/__tests__/EvaluationCallbacks.test.ts

@@ -0,0 +1,118 @@
+import fetchMock from 'jest-fetch-mock';
+import { anyFunction, anyNumber, anyObject } from 'statsig-test-helpers';
+
+import { StatsigClientEventData } from '@statsig/client-core';
+
+import StatsigClient from '../StatsigClient';
+import InitializeResponse from './initialize.json';
+
+describe('Client Evaluations Callback', () => {
+  const user = { userID: 'a-user' };
+  let client: StatsigClient;
+  let events: StatsigClientEventData[] = [];
+
+  beforeEach(async () => {
+    events = [];
+    client = new StatsigClient('client-key', user);
+
+    InitializeResponse['time'] = 123456;
+
+    fetchMock.enableMocks();
+    fetchMock.mockResponse(JSON.stringify(InitializeResponse));
+
+    await client.initializeAsync();
+
+    client.on('*', (data) => {
+      if (data.event.endsWith('_evaluation')) {
+        events.push(data);
+      }
+    });
+  });
+
+  it('fires the gate_evaluation event', () => {
+    client.checkGate('a_gate');
+    expect(events).toEqual([
+      {
+        event: 'gate_evaluation',
+        gate: {
+          name: 'a_gate',
+          ruleID: '2QWhVkWdUEXR6Q3KYgV73O',
+          details: {
+            lcut: 123456,
+            reason: 'Network:Recognized',
+            receivedAt: anyNumber(),
+          },
+          value: true,
+          __evaluation: anyObject(),
+        },
+      },
+    ]);
+  });
+
+  it('fires the dynamic_config_evaluation event', () => {
+    client.getDynamicConfig('a_dynamic_config');
+    expect(events).toEqual([
+      {
+        event: 'dynamic_config_evaluation',
+        dynamicConfig: {
+          name: 'a_dynamic_config',
+          ruleID: 'default',
+          details: {
+            lcut: 123456,
+            reason: 'Network:Recognized',
+            receivedAt: anyNumber(),
+          },
+          value: {
+            blue: '#00FF00',
+            green: '#0000FF',
+            red: '#FF0000',
+          },
+          __evaluation: anyObject(),
+        },
+      },
+    ]);
+  });
+
+  it('fires the experiment_evaluation event', () => {
+    client.getExperiment('an_experiment');
+    expect(events).toEqual([
+      {
+        event: 'experiment_evaluation',
+        experiment: {
+          name: 'an_experiment',
+          ruleID: '49CGlTB7z97PEdqJapQplA',
+          details: {
+            lcut: 123456,
+            reason: 'Network:Recognized',
+            receivedAt: anyNumber(),
+          },
+          value: {
+            a_string: 'Experiment Test Value',
+          },
+          __evaluation: anyObject(),
+        },
+      },
+    ]);
+  });
+
+  it('fires the layer_evaluation event', () => {
+    client.getLayer('a_layer');
+    expect(events).toEqual([
+      {
+        event: 'layer_evaluation',
+        layer: {
+          name: 'a_layer',
+          ruleID: '49CGlTB7z97PEdqJapQplA',
+          details: {
+            lcut: 123456,
+            reason: 'Network:Recognized',
+            receivedAt: anyNumber(),
+          },
+          getValue: anyFunction(),
+          _value: anyObject(),
+          __evaluation: anyObject(),
+        },
+      },
+    ]);
+  });
+});

package/src/__tests__/EvaluationsDataAdapter.test.ts

@@ -0,0 +1,131 @@
+import fetchMock from 'jest-fetch-mock';
+
+import { DataAdapterResult, Log } from '@statsig/client-core';
+
+import { StatsigEvaluationsDataAdapter } from '../StatsigEvaluationsDataAdapter';
+import { MockLocalStorage } from './MockLocalStorage';
+import InitializeResponse from './initialize.json';
+
+const InitializeResponseString = JSON.stringify(InitializeResponse);
+
+describe('Evaluations Data Adapter', () => {
+  const sdkKey = 'client-key';
+  const user = { userID: 'a-user' };
+
+  let storageMock: MockLocalStorage;
+  let adapter: StatsigEvaluationsDataAdapter;
+
+  beforeAll(() => {
+    storageMock = MockLocalStorage.enabledMockStorage();
+    storageMock.clear();
+
+    fetchMock.enableMocks();
+  });
+
+  afterAll(() => {
+    jest.clearAllMocks();
+    MockLocalStorage.disableMockStorage();
+  });
+
+  describe('attach', () => {
+    it('logs an error when called before attach', () => {
+      Log.error = jest.fn();
+
+      new StatsigEvaluationsDataAdapter().getDataSync(user);
+
+      expect(Log.error).toHaveBeenCalled();
+    });
+  });
+
+  describe('getDataSync', () => {
+    beforeAll(async () => {
+      fetchMock.mockResponse(InitializeResponseString);
+
+      adapter = new StatsigEvaluationsDataAdapter();
+      adapter.attach(sdkKey, null);
+    });
+
+    it('returns null when nothing is found', () => {
+      const result = adapter.getDataSync(user);
+      expect(result).toBeNull();
+    });
+
+    it('returns bootstrapped values', () => {
+      adapter.setData(InitializeResponseString, user);
+
+      const result = adapter.getDataSync(user);
+
+      expect(result?.source).toBe('Bootstrap');
+      expect(result?.data).toBe(InitializeResponseString);
+    });
+
+    it('returns prefetched values', async () => {
+      await adapter.prefetchData(user);
+
+      const result = adapter.getDataSync(user);
+
+      expect(result?.source).toBe('Prefetch');
+      expect(result?.data).toBe(InitializeResponseString);
+    });
+  });
+
+  describe('getDataAsync', () => {
+    let result: DataAdapterResult | null;
+
+    beforeEach(async () => {
+      fetchMock.mock.calls = [];
+      fetchMock.mockResponse(InitializeResponseString);
+
+      adapter = new StatsigEvaluationsDataAdapter();
+      adapter.attach(sdkKey, null);
+      result = await adapter.getDataAsync(null, user);
+    });
+
+    it('returns the network result on success', () => {
+      expect(result?.source).toBe('Network');
+      expect(result?.data).toBe(InitializeResponseString);
+    });
+
+    it('saves the network value for later getDataSync calls', () => {
+      const syncResult = adapter.getDataSync(user);
+      expect(syncResult?.source).toBe('Network');
+      expect(syncResult?.data).toBe(InitializeResponseString);
+    });
+
+    it('is cached for later sessions', () => {
+      const nextAdapter = new StatsigEvaluationsDataAdapter();
+      nextAdapter.attach(sdkKey, null);
+
+      const syncResult = nextAdapter.getDataSync(user);
+      expect(syncResult?.source).toBe('Cache');
+      expect(syncResult?.data).toBe(InitializeResponseString);
+    });
+
+    it('returns NetworkNotModifed on 204', async () => {
+      fetchMock.mockResponse('', { status: 204 });
+
+      const notModifiedResult = await adapter.getDataAsync(null, user);
+
+      expect(notModifiedResult?.source).toBe('NetworkNotModified');
+      expect(notModifiedResult?.data).toBe(InitializeResponseString);
+    });
+
+    it('returns null on network failure', async () => {
+      fetchMock.mockReject();
+
+      const errorResult = await adapter.getDataAsync(null, user);
+
+      expect(errorResult).toBeNull();
+    });
+
+    it('hits error boundary', async () => {
+      (adapter as any).getDataSync = () => {
+        throw new Error('Test');
+      };
+      await adapter.prefetchData({ userID: 'a' });
+      expect(fetchMock.mock.calls[1][0]).toBe(
+        'https://statsigapi.net/v1/sdk_exception',
+      );
+    });
+  });
+});

package/src/__tests__/InitStrategyAwaited.test.ts

@@ -0,0 +1,48 @@
+import fetchMock from 'jest-fetch-mock';
+
+import StatsigClient from '../StatsigClient';
+import { MockLocalStorage } from './MockLocalStorage';
+import InitializeResponse from './initialize.json';
+
+describe('Init Strategy - Awaited', () => {
+  const sdkKey = 'client-key';
+  const user = { userID: 'a-user' };
+
+  let client: StatsigClient;
+  let storageMock: MockLocalStorage;
+
+  beforeAll(async () => {
+    storageMock = MockLocalStorage.enabledMockStorage();
+    storageMock.clear();
+
+    fetchMock.enableMocks();
+    fetchMock.mockResponse(JSON.stringify(InitializeResponse));
+
+    client = new StatsigClient(sdkKey, user);
+    await client.initializeAsync();
+  });
+
+  afterAll(() => {
+    MockLocalStorage.disableMockStorage();
+  });
+
+  it('is ready after initialize', () => {
+    expect(client.loadingStatus).toBe('Ready');
+  });
+
+  it('reports source as "Network"', () => {
+    const gate = client.getFeatureGate('a_gate');
+    expect(gate.details.reason).toBe('Network:Recognized');
+  });
+
+  it('calls /initialize from network', () => {
+    expect(fetchMock.mock.calls).toHaveLength(1);
+    expect(fetchMock.mock.calls[0][0]).toContain(
+      'https://api.statsig.com/v1/initialize',
+    );
+  });
+
+  it('writes nothing to storage', () => {
+    expect(storageMock.data).toMatchObject({});
+  });
+});