Using EvaluationsDataAdapter

The StatsigEvaluationsDataAdapter is the default EvaluationsDataAdapter used by a StatsigClient instance.

How StatsigEvaluationsDataAdapter works

Synchronous behavior (cache)

When calling StatsigClient.initializeSync, the StatsigEvaluationsDataAdapter loads values from cache and provides them to the client. The client also calls refresh in the background through StatsigEvaluationsDataAdapter.getDataAsync, causing values to lag until the next initializeSync or updateUserSync call. To prevent this background refresh, pass disableBackgroundCacheRefresh in the options when calling initializeSync.

In practice, unless an additional update call is made, the very first session for a given user has no cached values. Cached values are available starting from the second session.

Asynchronous behavior (network)

When calling StatsigClient.initializeAsync, the StatsigEvaluationsDataAdapter loads values from cache and provides them to the client. The client then blocks on a call to StatsigEvaluationsDataAdapter.getDataAsync, allowing the latest values from Statsig to be awaited.

If you want the latest values but don't want to await the asynchronous call, call initializeAsync and .catch the promise. This can cause values to change mid-session as newer values arrive from the network.

Advanced Usage

Getting the Data Adapter

You can access the data adapter from your Statsig client instance:

const client = new StatsigClient('client-key', { userID: 'user-123' });
await client.initializeAsync();

const dataAdapter = client.dataAdapter;

Bootstrapping

This approach is also useful for mobile apps where you want to bundle values with your application. Load the values from a local file at startup and provide them to the data adapter.

import { StatsigClient } from '@statsig/js-client';

const client = new StatsigClient('client-key', { userID: 'user-123' });

// Bootstrap with data from server
const bootstrapData = /* data from server or local file */;
await client.dataAdapter.setData(bootstrapData);

await client.initializeSync();

When bootstrapping from a server SDK, update how the server SDK generates values. The new js-client SDK uses a djb2 hash instead of sha256 for hashing gate/experiment names. By default, all server SDKs generate sha256 hashes in the getClientInitializeResponse method. Set the hash algorithm parameter to "djb2" to bootstrap the new client SDK. This change also reduces the overall payload size, which benefits package size, speed, and payload size.

For example, if you bootstrap from a nodejs app:

statsig.getClientInitializeResponse(
  user,
  '[client-key]',
  {
    hash: 'djb2',
  },
);

Prefetching

You can manually trigger a prefetch for a user before calling updateUser:

const client = new StatsigClient('client-key', { userID: 'user-123' });
await client.initializeAsync();

// Prefetch data for a different user
const newUser = { userID: 'user-456' };
await client.dataAdapter.prefetchData(newUser);

// Update to the new user (will use prefetched data)
await client.updateUserAsync(newUser);

Custom Implementation

To customize when and how data is fetched, and where it is stored, create your own class that conforms to the EvaluationsDataAdapter type.

The EvaluationsDataAdapter type defines the following functions.

attach - Called when the EvaluationsDataAdapter is passed into a StatsigClient through StatsigOptions. This lets the EvaluationsDataAdapter use the same SDK Key and StatsigOptions as the StatsigClient instance.

attach: (
  sdkKey: string, 
  options: StatsigOptionsCommon | null
) => void

getDataSync - Synchronously get evaluation data for the given user. Called during initializeSync and/or updateUserSync. Also called during async update operations before StatsigDataAdapter.getDataAsync is called.

getDataSync: (user: StatsigUser) => DataAdapterResult | null;

getDataAsync - Asynchronously get evaluation data for the given user. Called during initializeAsync and/or updateUserAsync.

getDataAsync: (
  current: DataAdapterResult | null, 
  user: StatsigUser
) => Promise<DataAdapterResult | null>;

prefetchData - Manually trigger a fetch for new evaluations data for the given user.

prefetchData: (user: StatsigUser) => Promise<void>;

setData - Manually set evaluations data from a JSON string received from a Statsig Server SDK's getClientInitializeResponse method.

setData: (data: string) => Promise<void>;

setDataLegacy - Manually set evaluations data for the given user.

This method is deprecated and is provided only to support older versions of Statsig server SDKs.

setDataLegacy: (data: string, user: StatsigUser) => void;