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

# CL Sync API Reference

> Complete API reference for all exports across @claritylabs/cl-sync, @claritylabs/cl-sync/react, and @claritylabs/cl-sync/convex.

This page is a concise index of every public export in `@claritylabs/cl-sync`. Follow the links to each feature page for detailed explanations and usage examples.

***

## Core (`@claritylabs/cl-sync`)

### Functions

**createSyncStore(config)** `SyncStore`

Creates and returns a new `SyncStore` instance. Does not call `hydrate()` automatically — you must call `store.hydrate()` (or let `SyncProvider` do it) before reading data.

See [Store](https://claritylabs.inc/docs/cl-sync/store.md) for the full `SyncStoreConfig` reference.

**defineCollection\<TRecord, TArgs>(definition)** `CollectionDefinition\<TRecord, TArgs\>`

Identity helper for defining a typed collection. Returns `definition` unchanged. Exists for TypeScript inference.

See [Collections](https://claritylabs.inc/docs/cl-sync/collections.md).

**defineMutation\<TArgs, TResult>(definition)** `MutationDefinition\<TArgs, TResult\>`

Identity helper for defining a typed mutation. Returns `definition` unchanged.

See [Mutations](https://claritylabs.inc/docs/cl-sync/mutations.md).

**createScopeKey(scope)** `string`

Derives a composite scope key string in the format `"appId:env:userId:orgId"`. Omitted `environment`, `userId`, and `orgId` default to `default`, `anonymous`, and `none`.

```typescript theme={"system"}
createScopeKey({ appId: "app", environment: "prod", userId: "u-1", orgId: "o-1" });
// → "app:prod:u-1:o-1"
```

**stableHash(value)** `string`

Produces a deterministic JSON hash of `value` with object keys sorted. Used internally for `argsHash` in collection states.

***

### Types

**SyncId** `type`

`type SyncId = string`

The type for record identifiers throughout CL Sync.

**SyncScope** `interface`

```typescript theme={"system"}
interface SyncScope {
  appId: string;
  environment?: string;
  userId?: string;
  orgId?: string;
}
```

**SyncRecord** `interface`

```typescript theme={"system"}
interface SyncRecord {
  _id?: unknown;
  id?: unknown;
  [key: string]: unknown;
}
```

Base type for all records stored in CL Sync collections.

**SyncStoreConfig** `interface`

```typescript theme={"system"}
interface SyncStoreConfig {
  scope: SyncScope;
  schemaVersion?: number;
  schema?: SyncSchemaMetadata;
  migrations?: readonly SyncMigration[];
  mutations?: readonly MutationDefinition<any, any>[];
  now?: () => number;
  persistence?: "indexeddb" | "memory";
}
```

**SyncStatus** `interface`

```typescript theme={"system"}
interface SyncStatus {
  hydrated: boolean;
  hydrating: boolean;
  online: boolean;
  pendingMutations: number;
  lastSyncAt?: number;
  lastError?: string;
}
```

**CollectionDefinition\<TRecord, TArgs>** `interface`

```typescript theme={"system"}
interface CollectionDefinition<TRecord, TArgs = unknown> {
  name: string;
  getId?: (record: TRecord) => SyncId;
  persist?: boolean;
  staleMs?: number;
  redactBeforePersist?: (record: TRecord) => TRecord | null;
  sort?: (a: TRecord, b: TRecord) => number;
  deriveKey?: (args: TArgs) => string;
}
```

See [Collections](https://claritylabs.inc/docs/cl-sync/collections.md).

**MutationDefinition\<TArgs, TResult>** `interface`

```typescript theme={"system"}
interface MutationDefinition<TArgs, TResult> {
  name: string;
  reducer?: (store: SyncStore, args: TArgs, clientMutationId: string) => void;
  flush?: (args: TArgs, clientMutationId: string) => Promise<TResult>;
  onAck?: (store: SyncStore, args: TArgs, result: TResult, clientMutationId: string) => void;
  onReject?: (store: SyncStore, args: TArgs, error: unknown, clientMutationId: string) => void;
}
```

See [Mutations](https://claritylabs.inc/docs/cl-sync/mutations.md).

**OutboxItem\<TArgs>** `interface`

```typescript theme={"system"}
interface OutboxItem<TArgs> {
  id: string;
  mutation: string;
  args: TArgs;
  scopeKey: string;
  status: "pending" | "flushing" | "failed";
  createdAt: number;
  updatedAt: number;
  attempts: number;
  lastError?: string;
}
```

**CollectionState** `interface`

```typescript theme={"system"}
interface CollectionState {
  key: string;
  collection: string;
  ids: string[];
  argsHash: string;
  updatedAt: number;
  staleAt?: number;
  error?: string;
}
```

**SyncMigration** `interface`

```typescript theme={"system"}
interface SyncMigration {
  version: number;
  name?: string;
  migrate: (context: SyncMigrationContext) => void | Promise<void>;
}
```

See [Migrations](https://claritylabs.inc/docs/cl-sync/migrations.md).

**SyncMigrationContext** `interface`

Provides typed read/write access to records, collection states, outbox items, and metadata during a migration. See [Migrations](https://claritylabs.inc/docs/cl-sync/migrations.md) for the full interface.

**FlushPendingMutationsOptions** `interface`

```typescript theme={"system"}
interface FlushPendingMutationsOptions {
  mutations?: readonly MutationDefinition<any, any>[];
  includeFailed?: boolean;
  predicate?: (item: OutboxItem) => boolean;
}
```

**FlushPendingMutationsResult** `interface`

```typescript theme={"system"}
interface FlushPendingMutationsResult {
  flushed: string[];
  failed: Array<{ id: string; mutation: string; error: unknown }>;
  skipped: Array<{ id: string; mutation: string; reason: "missing_definition" | "flushing" | "filtered" }>;
  pending: number;
}
```

***

## React (`@claritylabs/cl-sync/react`)

| Export | Signature | Description |
| - | - | - |
| `SyncProvider` | `(props: SyncProviderProps) => JSX.Element` | Context provider. Hydrates the store on mount. See [Provider](https://claritylabs.inc/docs/cl-sync/react/provider.md). |
| `useSyncStore()` | `() => SyncStore` | Returns the `SyncStore` from context. |
| `useSyncSelector<T>(selector)` | `(selector: (store: SyncStore) => T) => T` | Subscribes to derived state. Re-renders on reference change. |
| `useSyncStatus()` | `() => SyncStatus` | Reactive `SyncStatus`. |
| `useSyncCollection(definition, args?)` | `<TRecord, TArgs>(definition, args?) => TRecord[] \| undefined` | Reactive record array for a collection slice. |
| `useSyncRecord(collection, id?)` | `<TRecord>(collection: string, id?: string) => TRecord \| undefined` | Reactive single record. |
| `useSyncMutation(definition)` | `<TArgs, TResult>(definition) => (args, clientMutationId?) => Promise<TResult \| undefined>` | Stable mutation callback. |
| `useHydratedValue(localValue, serverValue)` | `<T>(local: T \| undefined, server: T \| undefined) => T \| undefined` | Returns the supplied server value; otherwise returns local data after hydration, or `undefined` before hydration. |

See [Hooks](https://claritylabs.inc/docs/cl-sync/react/hooks.md) for detailed usage of each hook.

***

## Convex (`@claritylabs/cl-sync/convex`)

| Export | Signature | Description |
| - | - | - |
| `defineConvexCollection(definition)` | `(definition: ConvexCollectionDefinition) => ConvexCollectionDefinition` | Identity helper with Convex-typed `query` and `mapSnapshot` fields. |
| `defineConvexMutation(client, definition)` | `(client: ConvexReactClient, definition) => MutationDefinition` | Wraps a Convex mutation reference as a `MutationDefinition.flush` implementation. |
| `subscribeConvexCollection(store, client, definition, args, onError?)` | Returns `() => void` | Subscribes to a Convex query and syncs snapshots to the store in real time. |
| `ConvexCollectionDefinition<TQuery, TRecord>` | type | `CollectionDefinition<TRecord>` extended with `query` and optional `mapSnapshot`. |
| `ConvexMutationDefinition<TMutation, TArgs, TResult>` | type | `MutationDefinition<TArgs, TResult>` extended with `mutation` and optional `mapArgs`. |

See [Convex Adapter](https://claritylabs.inc/docs/cl-sync/convex-adapter.md) for detailed usage.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.