> ## Documentation Index
> Fetch the complete documentation index at: https://stratasync.blode.md/llms.txt
> Use this file to discover all available pages before exploring further.

# @stratasync/client

## Installation

```bash
npm install @stratasync/client
```

`@stratasync/client` depends on `@stratasync/core` and `@stratasync/y-doc` as workspace dependencies.

## Quick start

Wire up storage, transport, and reactivity, then call `start()`.

```ts
import { createSyncClient } from "@stratasync/client";
import { createIndexedDbStorage } from "@stratasync/storage-idb";
import { createGraphQLTransport } from "@stratasync/transport-graphql";
import { createMobXReactivity } from "@stratasync/mobx";

const client = createSyncClient({
  storage: createIndexedDbStorage(),
  transport: createGraphQLTransport({
    endpoint: "https://api.example.com/graphql",
    syncEndpoint: "https://api.example.com/sync",
    wsEndpoint: "wss://api.example.com/sync/ws",
    auth: { getAccessToken: async () => "your-token" },
  }),
  reactivity: createMobXReactivity(),
  optimistic: true,
  batchMutations: true,
});

await client.start();

const task = await client.create("Task", {
  title: "My task",
  status: "todo",
});

await client.stop();
```

## Architecture role

Sits between core primitives and framework bindings. Framework-agnostic: no React, Next.js, or browser API dependencies beyond injected adapters.

```
sync-core, sync-y-doc
  ^-- sync-client
        ^-- sync-react
              ^-- sync-next
```

The React hooks in `@stratasync/react` are thin wrappers around `SyncClient`. See [React](/packages/react) for details.

## SyncClient interface

`createSyncClient` returns a `SyncClient` with five categories of methods:

### Lifecycle

Control the sync engine and connection state.

| Property / Method   | Type              | Description                        |
| ------------------- | ----------------- | ---------------------------------- |
| `state`             | `SyncClientState` | Current sync state.                |
| `connectionState`   | `ConnectionState` | Current connection state.          |
| `lastSyncId`        | `number`          | Last sync ID received from server. |
| `lastError`         | `Error \| null`   | Last error (if any).               |
| `clientId`          | `string`          | Client instance identifier.        |
| `start()`           | `Promise<void>`   | Start the sync lifecycle.          |
| `stop()`            | `Promise<void>`   | Stop the sync lifecycle.           |
| `syncNow()`         | `Promise<void>`   | Force an immediate sync.           |
| `clearAll()`        | `Promise<void>`   | Clear all local data.              |
| `getPendingCount()` | `Promise<number>` | Pending transaction count.         |

### Reading

Fetch models from local storage or the identity map.

| Method                          | Type                      | Description               |
| ------------------------------- | ------------------------- | ------------------------- |
| `get(modelName, id)`            | `Promise<T \| null>`      | Get a model by ID.        |
| `getCached(modelName, id)`      | `T \| null`               | Get from identity map.    |
| `ensureModel(modelName, id)`    | `Promise<T \| null>`      | Load if not cached.       |
| `getAll(modelName, options?)`   | `Promise<T[]>`            | Get all models of a type. |
| `query(modelName, options?)`    | `Promise<QueryResult<T>>` | Query with filters.       |
| `getIdentityMap(modelName)`     | `Map<string, T>`          | Raw identity map access.  |
| `isModelMissing(modelName, id)` | `boolean`                 | Check if model not found. |

### Writing

All writes go through the outbox for offline-first persistence.

| Method                           | Type            | Description          |
| -------------------------------- | --------------- | -------------------- |
| `create(modelName, data)`        | `Promise<T>`    | Create a new model.  |
| `update(modelName, id, changes)` | `Promise<T>`    | Update a model.      |
| `delete(modelName, id)`          | `Promise<void>` | Delete a model.      |
| `archive(modelName, id)`         | `Promise<void>` | Soft-delete a model. |
| `unarchive(modelName, id)`       | `Promise<void>` | Restore a model.     |

### Undo/Redo

See [Undo and redo](/packages/client/undo-redo) for details.

| Method      | Type            | Description                 |
| ----------- | --------------- | --------------------------- |
| `canUndo()` | `boolean`       | Whether undo is available.  |
| `canRedo()` | `boolean`       | Whether redo is available.  |
| `undo()`    | `Promise<void>` | Undo last operation.        |
| `redo()`    | `Promise<void>` | Redo last undone operation. |

### Events

See [Event system](/packages/client/events) for the full reference.

| Method                              | Type         | Description                               |
| ----------------------------------- | ------------ | ----------------------------------------- |
| `onEvent(callback)`                 | `() => void` | Subscribe to events. Returns unsubscribe. |
| `onStateChange(callback)`           | `() => void` | Subscribe to state changes.               |
| `onConnectionStateChange(callback)` | `() => void` | Subscribe to connection changes.          |

The `yjs` property (`{ documentManager, presenceManager } | undefined`) provides access to Yjs managers when configured.

## Advanced exports

For custom orchestration, testing, or direct identity map manipulation. Most apps don't need these.

| Export                | Description                                                              |
| --------------------- | ------------------------------------------------------------------------ |
| `IdentityMap`         | In-memory cache that deduplicates model instances by ID.                 |
| `IdentityMapRegistry` | Manages multiple `IdentityMap` instances, one per model type.            |
| `OutboxManager`       | Manages the pending transaction outbox for offline-first persistence.    |
| `SyncOrchestrator`    | Coordinates the full sync lifecycle (bootstrap, deltas, reconnection).   |
| `executeQuery`        | Runs a query against the identity map with filter operators and sorting. |