# Offline API

Every export of kitr/offline, with its signature.

Every export of `kitr/offline`, `kitr/offline/react`, `kitr/offline/provider`, read from the published type definitions. The [guide](/packages/offline) shows them in use.

## kitr/offline

### bindOnlineManager

```ts
function bindOnlineManager(platform: {
  isOnline(): boolean;
  onOnline(l: (online: boolean) => void): () => void;
}): void;
```

Let TanStack Query's online state follow the platform driver (native shells report it better than `navigator.onLine`).

### createOffline

```ts
function createOffline(client: QueryClient, config?: OfflineConfig, app?: KitrApp): Offline;
```

Build the offline service for a QueryClient: it saves successful queries and paused mutations
to storage on a throttle (and when the page is hidden), and can restore them into the client.

### useOffline

```ts
function useOffline(app: KitrApp): Offline;
```

The `offline` service from an app's container, for code outside React. Bound on the client only.

### defineConfig

```ts
const defineConfig: <const C extends OfflineConfig>(config: C) => C;
```

Type-checks `config/offline.ts`. Returns the object unchanged.

### Offline

```ts
interface Offline {
  /** Load a stored snapshot into the client, if fresh. Resolves with whether one was found. */
  restore(): Promise<boolean>;
  /** Write the current cache now (the provider does it on a throttle). */
  persist(): void;
  /** Forget the snapshot. */
  clear(): void;
  /** Mutations waiting for the network. */
  pendingMutations(): number;
  /** Whether TanStack Query's `onlineManager` currently says online. */
  isOnline(): boolean;
  /** Called after a restore, after each throttled save, and when online state changes. Returns an unsubscribe function. */
  subscribe(listener: () => void): () => void;
  /** True once `restore()` loaded a snapshot into the client. */
  readonly restored: boolean;
}
```

The `offline` service: restores and saves the query cache snapshot and reports network state.

### OfflineConfig

```ts
interface OfflineConfig {
  /** Storage key for the cache snapshot. Default `kitr:query-cache`. */
  key?: string;
  /** Milliseconds a snapshot stays usable. Default 24 hours. */
  maxAge?: number;
  /** Persist only queries whose key passes; default: every successful query. */
  include?: (queryKey: QueryKey) => boolean;
  /** Milliseconds to wait after a change before writing. Default 1000. */
  throttle?: number;
  /** Where the snapshot lives. Default: the app's local storage driver (native on desktop/mobile). */
  storage?: StorageDriver;
  /** A string that invalidates old snapshots when the data shape changes (app version). */
  buster?: string;
}
```

Options for `config/offline.ts`: how long, where and what of the query cache is kept on the device.

## kitr/offline/react

### useOffline

```ts
function useOffline(): {
  online: boolean;
  pending: number;
  restored: boolean;
  clear: () => void;
  persist: () => void;
};
```

`{ online, pending, restored }`: whether the network is up, how many mutations wait for it,
and whether the cache came from a stored snapshot. Hydration-safe: the server says online.

## kitr/offline/provider

### offlineProvider

```ts
const offlineProvider: import("@kitr/core").KitrProvider;
```

Persists the query cache and paused mutations, restores them before the first render and
replays the mutations when the network returns (TanStack Query resumes paused mutations on
its own once `onlineManager` says online). Put it after the query provider in kitrrc.ts.

<!-- GENERATED by scripts/api-docs.mjs from the type definitions. Do not edit. -->