# Using EvaluationsDataAdapter

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

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

## 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:

```typescript
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` without a network call. This is useful if you run a Statsig Server SDK on your backend and want to avoid unnecessary network calls (refer to [statsig-node](https://docs.statsig.com/server/nodejsServerSDK#bootstrap)'s `getClientInitializeResponse`).

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.

```typescript
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();
```

[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)

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:

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

### Prefetching

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

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

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.

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

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

***

`getDataAsync` - Asynchronously get evaluation data for the given user. The client calls this during initializeAsync and/or updateUserAsync.

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

***

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

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

***

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

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

{% callout type="note" %}
You can use `setDataLegacy` if your Server SDK is outdated.
{% /callout %}

{% 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**. Statsig provides it only to support older versions of Statsig server SDKs.

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