@stratasync/client

Client orchestration, outbox management, identity maps, query execution, and undo/redo for Strata Sync.

Installation


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().


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