# Using SpecsDataAdapter

> For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

The `StatsigSpecsDataAdapter` is the default `SpecsDataAdapter` that a `StatsigOnDeviceEvalClient` instance uses.

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

## How StatsigSpecsDataAdapter works

### Synchronous behavior (cache)

When calling `StatsigOnDeviceEvalClient.initializeSync`, the `StatsigSpecsDataAdapter` loads values from cache and provides them to the client. The client also calls refresh in the background through `StatsigSpecsDataAdapter.getDataAsync`, causing values to lag until the next `initializeSync` call.

In practice, the very first session has no cached values. Cached values become available starting from the second session.

### Asynchronous behavior (network)

When calling `StatsigOnDeviceEvalClient.initializeAsync`, the `StatsigSpecsDataAdapter` loads values from cache and provides them to the client. The client then blocks on a call to `StatsigSpecsDataAdapter.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 on-device client instance:

```typescript
const client = new StatsigOnDeviceEvalClient('client-key');
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/on-device-eval-client/sample-on-device-get-data-adapter.tsx)

### Bootstrapping

Bootstrapping allows you to provide the required data without a network call. This is useful when you want to avoid network calls during startup.

If you build a mobile app and 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 { StatsigOnDeviceEvalClient } from '@statsig/js-on-device-eval-client';

const client = new StatsigOnDeviceEvalClient('client-key');

// Bootstrap with specs data from local file or bundle
const specsData = /* data from local file */;
await client.dataAdapter.setData(specsData);

await client.initializeAsync();
```

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

> **Note:**
>
> You can get a copy of your current specs data by visiting: `https://api.statsigcdn.com/v1/download_config_specs/client-{YOUR_SDK_KEY}.json`

### 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 `SpecsDataAdapter` type.

The `SpecsDataAdapter` type defines the following functions.

- `attach` - The client calls this when you pass the `SpecsDataAdapter` into a `StatsigOnDeviceEvalClient` through `StatsigOptions`. This lets the `SpecsDataAdapter` use the same SDK Key and `StatsigOptions` as the `StatsigOnDeviceEvalClient` instance.

  - ```typescript
    attach: (sdkKey: string, options: StatsigOptionsCommon | null) => void
    ```
- `getDataSync` - Synchronously get evaluation data for the given user. The client calls this during initializeSync. It also calls this during async update operations before calling StatsigDataAdapter.getDataAsync.

  - ```typescript
    getDataSync: () => DataAdapterResult | null;
    ```
- `getDataAsync` - Asynchronously get evaluation data for the given user. The client calls this during initializeAsync.

  - ```typescript
    getDataAsync: (current: DataAdapterResult | null) => Promise<DataAdapterResult | null>;
    ```
- `prefetchData` - Manually trigger a fetch for new specs data.

  - ```typescript
    prefetchData: () => Promise<void>;
    ```
- `setData` - Manually set specs data.

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