> ## Documentation Index
> Fetch the complete documentation index at: https://statsig-4b2ff144-serverless-cloudflare.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Using EvaluationsDataAdapter

> Learn how to use and customize the StatsigEvaluationsDataAdapter for caching and fetching evaluation data.

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

It handles fetching and caching values from Statsig's servers. If required, you can create your own custom `EvaluationsDataAdapter`
and provide it to the Statsig client via [StatsigOptions.dataAdapter](/client/javascript-sdk#statsig-options).

## Overview

### Synchronous Behavior (Cache)

When calling `StatsigClient.initializeSync`, the `StatsigEvaluationsDataAdapter` will load values
from Cache and provide them to the client. The client will also call refresh in the background via
`StatsigEvaluationsDataAdapter.getDataAsync`, leading to values lagging until the next time `initializeSync` or `updateUserSync` is called. If you do not want this background refresh to happen, you can pass in `disableBackgroundCacheRefresh` in the options when calling `initializeSync`.

In practice (Unless an additional update call is made), this means that for the very first session of a given user, there will be no values, and not until the next session will the cache have values.

### Asynchronous Behavior (Network)

When calling `StatsigClient.initializeAsync`, the `StatsigEvaluationsDataAdapter` will load values
from Cache and provide them to the client. The client will then block on a call to `StatsigEvaluationsDataAdapter.getDataAsync`,
allowing the ability to await the latest values from Statsig.

If you want the latest values, but do not want to await the asynchronous call, you may call `initializeAsync` and simply `.catch` the promise. Note that
this could lead to values changing 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:

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

const dataAdapter = client.dataAdapter;
```

[View full example on GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/precomputed-client/sample-precomp-get-data-adapter.tsx)

### Bootstrapping

Bootstrapping allows you to provide data for a given `StatsigUser`. This can be useful if you are are running a
Statsig Server SDK on your backend and do not wish to make unnecessary network calls (See [statsig-node](/server/nodejsServerSDK#bootstrap)'s getClientInitializeResponse).

This approach can also be useful if you are building a mobile app and want to bundle values with your application. Then you can load the values from a local file at startup and provide them to the data adapter.

```typescript theme={null}
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.initializeAsync();
```

[View full example on GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/precomputed-client/sample-precomp-bootstrap.tsx)

If you are using a server SDK to bootstrap your js/react app, you will need to make some updates to how your server SDK generates values.  One of the optimizations we made with this new js-client SDK was to remove the `sha256` library for hashing gate/experiment names.  Instead, we use a `djb2` hash.  By default, all server SDKs generate `sha256` hashes of gate/experiment names in the `getClientInitializeResponse` method.  You will need to set the hash algorithm parameter to that method call to `"djb2"` instead in order to bootstrap this new client SDK.  One of the benefits to this hashing algorithm is it will make the entire payload smaller as well, so its a net win on package size, speed, and payload size for the SDK.

For example, if you are bootstrapping from a nodejs app, you will need to do:

```js theme={null}
statsig.getClientInitializeResponse(
  user,
  '[client-key]',
  {
    hash: 'djb2',
  },
);
```

### Prefetching

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

```typescript theme={null}
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);
```

[View full example on GitHub](https://github.com/statsig-io/js-client-monorepo/blob/main/samples/react/src/samples/precomputed-client/sample-precomp-prefetch.tsx)

### Custom Implementation

If you would like to customize when and how data is fetched, as well as where it is stored, you can create your own class the conforms to the `EvaluationsDataAdapter` type.

The `EvaluationsDataAdapter` type outlines the following functions:

`attach` - Called when the `EvaluationsDataAdapter` is passed into a `StatsigClient` via `StatsigOptions`. This allows the `EvaluationsDataAdapter` to use
the same SDK Key and `StatsigOptions` as the `StatsigClient` instance.

```typescript theme={null}
attach: (
  sdkKey: string, 
  options: StatsigOptionsCommon | null
) => void
```

***

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

```typescript theme={null}
getDataSync: (user: StatsigUser) => DataAdapterResult | null;
```

***

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

```typescript theme={null}
getDataAsync: (
  current: DataAdapterResult | null, 
  user: StatsigUser
) => Promise<DataAdapterResult | null>;
```

***

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

```typescript theme={null}
prefetchData: (user: StatsigUser) => Promise<void>;
```

***

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

```typescript theme={null}
setData: (data: string) => Promise<void>;
```

<Note>
  You can use `setDataLegacy` if your Server SDK is outdated.
</Note>

<Accordion title="setData is supported by the following Statsig Server SDKs">
  * node-js-server-sdk\@5.20.0
  * java-server-sdk\@1.18.0
  * ruby-sdk\@1.34.0
  * dotnet-sdk\@1.25.0
  * php-sdk\@3.2.0
</Accordion>

***

`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.

```typescript theme={null}
setDataLegacy: (data: string, user: StatsigUser) => void;
```