Using EvaluationsDataAdapter

The StatsigEvaluationsDataAdapter is the default EvaluationsDataAdapter that a StatsigClient instance uses.

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 you make an additional update call, the very first session for a given user has no cached values. Cached values become 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 client to await the latest values from Statsig.

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 and speed.

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 the adapter fetches data, and where it stores that data, create your own class that conforms to the EvaluationsDataAdapter type.

The EvaluationsDataAdapter type defines the following functions.

attach - The client calls this when you pass the EvaluationsDataAdapter 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. The client calls this during initializeSync and/or updateUserSync. It also calls this during async update operations before calling StatsigDataAdapter.getDataAsync.

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

getDataAsync - Asynchronously get evaluation data for the given user. The client calls this 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 that a Statsig Server SDK's getClientInitializeResponse method returns.

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

setDataLegacy - Manually set evaluations data for the given user.

This method is deprecated. Statsig provides it only to support older versions of Statsig server SDKs.

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