Reference

valtio-sync

import { z } from "zod";

Functions

`assertJsonRecord`

Assert that a parsed value is an object-shaped JSON payload.

export function assertJsonRecord(value: unknown, message?: string): asserts value is JsonRecord;

^{🔍 assertJsonRecord on GitHub}

`defineAccount`

Define the singleton account portion of a sync schema.

export function defineAccount<const TFields extends FieldMap>(options: DefinitionOptions<TFields>): AccountDefinition<TFields>;

^{🔍 defineAccount on GitHub}

`defineCollection`

Define a record collection in a sync schema.

export function defineCollection<const TFields extends FieldMap>(options: DefinitionOptions<TFields>): CollectionDefinition<TFields>;

^{🔍 defineCollection on GitHub}

`defineLocalState`

Create a strict Zod object schema for client-only device or session state.

export function defineLocalState<const TFields extends FieldMap>(fields: TFields): SyncResponse.ZodObject<TFields>;

^{🔍 defineLocalState on GitHub}

`getAccountKey`

Return the single account key or throw when the schema does not define exactly one.

export function getAccountKey<TSchema extends SyncSchema>(schema: TSchema): AccountKey<TSchema>;

^{🔍 getAccountKey on GitHub}

`getCollectionDefinition`

Look up a schema definition by wire collection name.

export function getCollectionDefinition(schema: SyncSchema, collection: string): SchemaDefinition | undefined;

^{🔍 getCollectionDefinition on GitHub}

`getCollectionKeys`

Return every collection key from a sync schema.

export function getCollectionKeys<TSchema extends SyncSchema>(schema: TSchema): Array<CollectionKey<TSchema>>;

^{🔍 getCollectionKeys on GitHub}

`getDefaults`

Return default values supplied by fields in a schema definition.

export function getDefaults<TFields extends FieldMap>(definition: SchemaDefinition<TFields>): InferFields<TFields>;

^{🔍 getDefaults on GitHub}

`isJsonRecord`

Return true when a value is an object-shaped JSON record.

export function isJsonRecord(value: unknown): value is JsonRecord;

^{🔍 isJsonRecord on GitHub}

`parseLocalState`

Parse client-only local state and ensure the parsed output is JSON-serializable.

export function parseLocalState<TFields extends FieldMap>(fields: TFields, value: unknown): InferFields<TFields>;

^{🔍 parseLocalState on GitHub}

`parsePatch`

Parse a partial update against known fields and reject unknown patch keys.

export function parsePatch<TFields extends FieldMap>(definition: SchemaDefinition<TFields>, value: unknown): Partial<InferFields<TFields>>;

^{🔍 parsePatch on GitHub}

`parseRecord`

Parse a full synced record and ensure the parsed output is JSON-serializable.

export function parseRecord<TFields extends FieldMap>(definition: SchemaDefinition<TFields>, value: unknown): InferFields<TFields>;

^{🔍 parseRecord on GitHub}

`parseSyncRequest`

Parse and validate an unknown value as a sync request.

export function parseSyncRequest(value: unknown): SyncRequest;

^{🔍 parseSyncRequest on GitHub}

`parseSyncResponse`

Parse and validate an unknown value as a sync response.

export function parseSyncResponse(value: unknown): SyncResponse;

^{🔍 parseSyncResponse on GitHub}

Constants

`collectionChangesSchema`

Zod schema for a server change set for one collection.

export const collectionChangesSchema: SyncResponse.ZodType<CollectionChanges>;

^{🔍 collectionChangesSchema on GitHub}

`jsonRecordSchema`

Zod schema for object-shaped JSON values.

export const jsonRecordSchema: SyncResponse.ZodType<JsonRecord>;

^{🔍 jsonRecordSchema on GitHub}

`jsonValueSchema`

Zod schema for values that can be serialized into valtio-sync records.

export const jsonValueSchema: SyncResponse.ZodType<JsonValue>;

^{🔍 jsonValueSchema on GitHub}

`syncOpSchema`

Zod schema for client mutation operations.

export const syncOpSchema: SyncResponse.ZodType<SyncOp>;

^{🔍 syncOpSchema on GitHub}

`syncRequestSchema`

Zod schema for the client-to-server sync request body.

export const syncRequestSchema: SyncResponse.ZodType<SyncRequest>;

^{🔍 syncRequestSchema on GitHub}

`syncResponseSchema`

Zod schema for the server-to-client sync response body.

export const syncResponseSchema: SyncResponse.ZodType<SyncResponse>;

^{🔍 syncResponseSchema on GitHub}

`ACCOUNT_COLLECTION`

Reserved sync collection name used for singleton account state on the wire.

export const ACCOUNT_COLLECTION = "account";

^{🔍 ACCOUNT_COLLECTION on GitHub}

`ACCOUNT_ID`

Reserved sync record id used for singleton account state on the wire.

export const ACCOUNT_ID = "singleton";

^{🔍 ACCOUNT_ID on GitHub}

Types

`AcceptedSyncOp`

Server acknowledgement for a mutation that was applied successfully.

export type AcceptedSyncOp = {
  mutationId: string;
  collection: string;
  id: string;
  serverVersion: number;
  record?: JsonRecord;
};

^{🔍 AcceptedSyncOp on GitHub}

`AccountDefinition`

Singleton account state definition for a sync schema.

export type AccountDefinition<TFields extends FieldMap = FieldMap> = {
  readonly kind: 'account';
  readonly fields: TFields;
  readonly recordSchema: SyncResponse.ZodObject<TFields>; /** @deprecated Use `recordSchema` for the effective synced record schema. */
  readonly schema: SyncResponse.ZodObject<TFields>;
};

^{🔍 AccountDefinition on GitHub}

`AccountKey`

Extract the account key from a sync schema type.

export type AccountKey<TSchema extends SyncSchema> = { [parseSyncResponse in keyof TSchema]: TSchema[parseSyncResponse] extends AccountDefinition ? parseSyncResponse : never }[keyof TSchema];

^{🔍 AccountKey on GitHub}

`CollectionChanges`

Server-provided remote changes for a single collection.

export type CollectionChanges = {
  mode?: CollectionChangesMode;
  upserted: Array<{
    id: string;
    serverVersion: number;
    record: JsonRecord;
  }>;
  deleted: Array<{
    id: string;
    serverVersion: number;
  }>;
};

^{🔍 CollectionChanges on GitHub}

`CollectionChangesMode`

Whether returned changes are incremental or an authoritative collection snapshot.

export type CollectionChangesMode = 'changes' | 'snapshot';

^{🔍 CollectionChangesMode on GitHub}

`CollectionDefinition`

Record collection definition for a sync schema.

export type CollectionDefinition<TFields extends FieldMap = FieldMap> = {
  readonly kind: 'collection';
  readonly fields: TFields;
  readonly recordSchema: SyncResponse.ZodObject<TFields>; /** @deprecated Use `recordSchema` for the effective synced record schema. */
  readonly schema: SyncResponse.ZodObject<TFields>;
};

^{🔍 CollectionDefinition on GitHub}

`CollectionKey`

Extract collection keys from a sync schema type.

export type CollectionKey<TSchema extends SyncSchema> = { [parseSyncResponse in keyof TSchema]: TSchema[parseSyncResponse] extends CollectionDefinition ? parseSyncResponse : never }[keyof TSchema];

^{🔍 CollectionKey on GitHub}

`CreateSyncOp`

Client request to create a record in a synced collection.

export type CreateSyncOp = {
  mutationId: string;
  collection: string;
  type: 'create';
  id: string;
  value: JsonRecord;
  touched: string[];
};

^{🔍 CreateSyncOp on GitHub}

`DefinitionOptions`

Options shared by account and collection definitions.

export type DefinitionOptions<TFields extends FieldMap> = {
  fields: TFields;
  refine?: RecordRefinement<TFields>;
};

^{🔍 DefinitionOptions on GitHub}

`DeleteSyncOp`

Client request to delete an existing synced record.

export type DeleteSyncOp = {
  mutationId: string;
  collection: string;
  type: 'delete';
  id: string;
  baseServerVersion: number | null;
};

^{🔍 DeleteSyncOp on GitHub}

`FieldMap`

Named field map used to define account, collection, device, or session state.

export type FieldMap = Record<string, FieldSchema>;

^{🔍 FieldMap on GitHub}

`FieldSchema`

Zod field schema accepted by valtio-sync schema definitions.

export type FieldSchema = SyncResponse.ZodType<unknown>;

^{🔍 FieldSchema on GitHub}

`InferFields`

Infer the parsed output object from a field map.

export type InferFields<TFields extends FieldMap> = { -readonly [parseSyncResponse in keyof TFields]: SyncResponse.output<TFields[parseSyncResponse]> };

^{🔍 InferFields on GitHub}

`JsonRecord`

Object-shaped JSON payload used for account data, collection records, and patches.

export type JsonRecord = Record<string, JsonValue>;

^{🔍 JsonRecord on GitHub}

`JsonValue`

JSON value shape accepted by sync payloads and persisted records.

export type JsonValue = string | number | boolean | null | JsonValue[] | {
  [key: string]: JsonValue;
};

^{🔍 JsonValue on GitHub}

`RecordRefinement`

Record-level validation callback for invariants involving multiple fields.

export type RecordRefinement<TFields extends FieldMap> = Parameters<SyncResponse.ZodObject<TFields>['superRefine']>[0];

^{🔍 RecordRefinement on GitHub}

`RejectedSyncOp`

Server acknowledgement for a mutation that was refused.

export type RejectedSyncOp = {
  mutationId: string;
  collection: string;
  id: string;
  reason: SyncRejectionReason;
  message?: string;
  serverRecord?: JsonRecord;
  serverVersion?: number;
};

^{🔍 RejectedSyncOp on GitHub}

`SchemaDefinition`

Any schema definition accepted in a valtio-sync schema map.

export type SchemaDefinition<TFields extends FieldMap = FieldMap> = AccountDefinition<TFields> | CollectionDefinition<TFields>;

^{🔍 SchemaDefinition on GitHub}

`SchemaKind`

Discriminator for account and collection schema definitions.

export type SchemaKind = 'account' | 'collection';

^{🔍 SchemaKind on GitHub}

`SyncError`

Last sync error tracked by the client for status and record metadata.

export type SyncError = {
  reason: SyncRejectionReason | 'network' | 'auth';
  message?: string;
};

^{🔍 SyncError on GitHub}

`SyncOp`

Any mutation operation sent by a client during sync.

export type SyncOp = CreateSyncOp | UpdateSyncOp | DeleteSyncOp;

^{🔍 SyncOp on GitHub}

`SyncRejectionReason`

Server-side reason codes a mutation handler can return for a rejected sync op.

export type SyncRejectionReason = 'validation' | 'forbidden' | 'conflict' | 'not_found' | 'server_error';

^{🔍 SyncRejectionReason on GitHub}

`SyncRequest`

HTTP request body sent by the client sync loop to the server endpoint.

export type SyncRequest = {
  clientId: string;
  schemaVersion: number;
  lastServerSeq: number | null;
  ops: SyncOp[];
};

^{🔍 SyncRequest on GitHub}

`SyncResponse`

HTTP response body returned by the server sync endpoint.

export type SyncResponse = {
  serverSeq: number;
  accepted: AcceptedSyncOp[];
  rejected: RejectedSyncOp[];
  changes: Record<string, CollectionChanges>;
};

^{🔍 SyncResponse on GitHub}

`SyncSchema`

Complete sync schema keyed by user-defined account and collection names.

export type SyncSchema = Record<string, SchemaDefinition>;

^{🔍 SyncSchema on GitHub}

`UpdateSyncOp`

Client request to patch selected fields of an existing synced record.

export type UpdateSyncOp = {
  mutationId: string;
  collection: string;
  type: 'update';
  id: string;
  patch: JsonRecord;
  touched: string[];
  baseServerVersion: number | null;
};

^{🔍 UpdateSyncOp on GitHub}