CL Sync API Reference

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

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 for the full SyncStoreConfig reference.

CollectionDefinition<TRecord, TArgs>

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

MutationDefinition<TArgs, TResult>

Identity helper for defining a typed mutation. Returns definition unchanged.See Mutations.

string

Derives a composite scope key string in the format "appId:env:userId:orgId". Omitted optional fields produce an empty segment.

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

string

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

Types

type

type SyncId = stringThe type for record identifiers throughout CL Sync.

interface

interface SyncScope {
  appId: string;
  environment?: string;
  userId?: string;
  orgId?: string;
}

interface

interface SyncRecord {
  _id?: unknown;
  id?: unknown;
  [key: string]: unknown;
}

Base type for all records stored in CL Sync collections.

interface

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

interface

interface SyncStatus {
  hydrated: boolean;
  hydrating: boolean;
  online: boolean;
  pendingMutations: number;
  lastSyncAt?: number;
  lastError?: string;
}

interface

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.

interface

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.

interface

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

interface

interface CollectionState {
  key: string;
  collection: string;
  ids: string[];
  argsHash: string;
  updatedAt: number;
  staleAt?: number;
  error?: string;
}

interface

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

See Migrations.

interface

Provides typed read/write access to records, collection states, outbox items, and metadata during a migration. See Migrations for the full interface.

interface

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

interface

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.
`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 server value, then local value once hydrated, then `undefined`.

See Hooks 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 for detailed usage.

Get Started

Core

React

Integrations

Core (`@claritylabs/cl-sync`)

Functions

Types

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

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

​Core (@claritylabs/cl-sync)

​Functions

​Types

​React (@claritylabs/cl-sync/react)

​Convex (@claritylabs/cl-sync/convex)

Core (`@claritylabs/cl-sync`)

Functions

Types

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

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