@tldraw/sync-core 4.2.1 → 4.2.2

package/dist-cjs/index.d.ts

@@ -1,15 +1,21 @@
 import { Atom } from '@tldraw/state';
 import { AtomMap } from '@tldraw/store';
+import { DebouncedFunc } from 'lodash';
 import { Emitter } from 'nanoevents';
 import { RecordsDiff } from '@tldraw/store';
 import { RecordType } from '@tldraw/store';
-import { Result } from '@tldraw/utils';
 import { SerializedSchema } from '@tldraw/store';
+import { SerializedSchemaV2 } from '@tldraw/store';
 import { Signal } from '@tldraw/state';
 import { Store } from '@tldraw/store';
 import { StoreSchema } from '@tldraw/store';
+import { StoreSnapshot } from '@tldraw/store';
+import { SynchronousStorage } from '@tldraw/store';
+import { TLDocument } from '@tldraw/tlschema';
+import { TLPage } from '@tldraw/tlschema';
 import { TLRecord } from '@tldraw/tlschema';
 import { TLStoreSnapshot } from '@tldraw/tlschema';
+import { TLStoreSnapshot as TLStoreSnapshot_2 } from 'tldraw';
 import { UnknownRecord } from '@tldraw/store';
 
 /* Excluded from this release type: AppendOp */
@@ -20,16 +26,103 @@ import { UnknownRecord } from '@tldraw/store';
 
 /* Excluded from this release type: ClientWebSocketAdapter */
 
+/**
+ * Default initial snapshot for a new room.
+ * @public
+ */
+export declare const DEFAULT_INITIAL_SNAPSHOT: {
+    documentClock: number;
+    documents: ({
+        lastChangedClock: number;
+        state: TLDocument;
+    } | {
+        lastChangedClock: number;
+        state: TLPage;
+    })[];
+    schema: SerializedSchemaV2;
+    tombstoneHistoryStartsAtClock: number;
+};
+
 /* Excluded from this release type: DeleteOp */
 
 /* Excluded from this release type: diffRecord */
 
-/* Excluded from this release type: DocumentState */
+/**
+ * A wrapper around Cloudflare Durable Object's SqlStorage that implements TLSyncSqliteWrapper.
+ *
+ * Use this wrapper with SQLiteSyncStorage to persist tldraw sync state using
+ * Cloudflare Durable Object's built-in SQLite storage. This provides automatic
+ * persistence that survives Durable Object hibernation and restarts.
+ *
+ * @example
+ * ```ts
+ * import { SQLiteSyncStorage, DurableObjectSqliteSyncWrapper } from '@tldraw/sync-core'
+ *
+ * // In your Durable Object class:
+ * class MyDurableObject extends DurableObject {
+ *   private storage: SQLiteSyncStorage
+ *
+ *   constructor(ctx: DurableObjectState, env: Env) {
+ *     super(ctx, env)
+ *     const sql = new DurableObjectSqliteSyncWrapper(ctx.storage)
+ *     this.storage = new SQLiteSyncStorage({ sql })
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With table prefix to avoid conflicts with other tables
+ * const sql = new DurableObjectSqliteSyncWrapper(this.ctx.storage, { tablePrefix: 'tldraw_' })
+ * // Creates tables: tldraw_documents, tldraw_tombstones, tldraw_metadata
+ * ```
+ *
+ * @public
+ */
+export declare class DurableObjectSqliteSyncWrapper implements TLSyncSqliteWrapper {
+    private storage;
+    config?: TLSyncSqliteWrapperConfig | undefined;
+    constructor(storage: {
+        sql: {
+            exec(sql: string, ...bindings: unknown[]): Iterable<any> & {
+                toArray(): any[];
+            };
+        };
+        transactionSync(callback: () => any): any;
+    }, config?: TLSyncSqliteWrapperConfig | undefined);
+    exec(sql: string): void;
+    prepare<TResult extends TLSqliteRow | void = void, TParams extends TLSqliteInputValue[] = []>(sql: string): TLSyncSqliteStatement<TResult, TParams>;
+    transaction<T>(callback: () => T): T;
+}
 
 /* Excluded from this release type: getNetworkDiff */
 
 /* Excluded from this release type: getTlsyncProtocolVersion */
 
+/**
+ * In-memory implementation of TLSyncStorage using AtomMap for documents and tombstones,
+ * and atoms for clock values. This is the default storage implementation used by TLSyncRoom.
+ *
+ * @public
+ */
+export declare class InMemorySyncStorage<R extends UnknownRecord> implements TLSyncStorage<R> {
+    /* Excluded from this release type: documents */
+    /* Excluded from this release type: tombstones */
+    /* Excluded from this release type: schema */
+    /* Excluded from this release type: documentClock */
+    /* Excluded from this release type: tombstoneHistoryStartsAtClock */
+    private notifier;
+    onChange(callback: (arg: TLSyncStorageOnChangeCallbackProps) => unknown): () => void;
+    constructor({ snapshot, onChange, }?: {
+        onChange?(arg: TLSyncStorageOnChangeCallbackProps): unknown;
+        snapshot?: RoomSnapshot;
+    });
+    transaction<T>(callback: TLSyncStorageTransactionCallback<R, T>, opts?: TLSyncStorageTransactionOptions): TLSyncStorageTransactionResult<T, R>;
+    getClock(): number;
+    /* Excluded from this release type: pruneTombstones */
+    getSnapshot(): RoomSnapshot;
+}
+
 /**
  * Assembles chunked JSON messages back into complete objects.
  * Handles both regular JSON messages and chunked messages created by the chunk() function.
@@ -66,8 +159,8 @@ export declare class JsonChunkAssembler {
      *
      * @param msg - The message to process, either JSON or chunk format
      * @returns Result object with data/stringified on success, error object on failure, or null for incomplete chunks
-     *  - `\{ data: object, stringified: string \}` - Successfully parsed complete message
-     *  - `\{ error: Error \}` - Parse error or invalid chunk sequence
+     * 	- `\{ data: object, stringified: string \}` - Successfully parsed complete message
+     * 	- `\{ error: Error \}` - Parse error or invalid chunk sequence
      * 	- `null` - Chunk received but more chunks expected
      *
      * @example
@@ -94,8 +187,68 @@ export declare class JsonChunkAssembler {
     } | null;
 }
 
+/**
+ * Loads a snapshot into storage during a transaction.
+ * Migrates the snapshot to the current schema and loads it into storage.
+ *
+ * @public
+ * @param txn - The transaction to load the snapshot into
+ * @param schema - The current schema
+ * @param snapshot - The snapshot to load
+ */
+export declare function loadSnapshotIntoStorage<R extends UnknownRecord>(txn: TLSyncStorageTransaction<R>, schema: StoreSchema<R, any>, snapshot: RoomSnapshot | TLStoreSnapshot_2): void;
+
+/* Excluded from this release type: MinimalDocStore */
+
 /* Excluded from this release type: NetworkDiff */
 
+/**
+ * A wrapper around synchronous SQLite databases that implements TLSyncSqliteWrapper.
+ * Works with both `node:sqlite` DatabaseSync (Node.js 22.5+) and `better-sqlite3` Database.
+ *
+ * Use this wrapper with SQLiteSyncStorage to persist tldraw sync state to a SQLite database
+ * in Node.js environments.
+ *
+ * @example
+ * ```ts
+ * // With node:sqlite (Node.js 22.5+)
+ * import { DatabaseSync } from 'node:sqlite'
+ * import { SQLiteSyncStorage, NodeSqliteWrapper } from '@tldraw/sync-core'
+ *
+ * const db = new DatabaseSync(':memory:')
+ * const sql = new NodeSqliteWrapper(db)
+ * const storage = new SQLiteSyncStorage({ sql })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With better-sqlite3
+ * import Database from 'better-sqlite3'
+ * import { SQLiteSyncStorage, NodeSqliteWrapper } from '@tldraw/sync-core'
+ *
+ * const db = new Database(':memory:')
+ * const sql = new NodeSqliteWrapper(db)
+ * const storage = new SQLiteSyncStorage({ sql })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With table prefix to avoid conflicts with other tables
+ * const sql = new NodeSqliteWrapper(db, { tablePrefix: 'tldraw_' })
+ * // Creates tables: tldraw_documents, tldraw_tombstones, tldraw_metadata
+ * ```
+ *
+ * @public
+ */
+export declare class NodeSqliteWrapper implements TLSyncSqliteWrapper {
+    private db;
+    config?: TLSyncSqliteWrapperConfig | undefined;
+    constructor(db: SyncSqliteDatabase, config?: TLSyncSqliteWrapperConfig | undefined);
+    exec(sql: string): void;
+    prepare<TResult extends TLSqliteRow | void = void, TParams extends TLSqliteInputValue[] = TLSqliteInputValue[]>(sql: string): TLSyncSqliteStatement<TResult, TParams>;
+    transaction<T>(callback: () => T): T;
+}
+
 /* Excluded from this release type: ObjectDiff */
 
 /**
@@ -119,6 +272,8 @@ export declare type OmitVoid<T, KS extends keyof T = keyof T> = {
 
 /* Excluded from this release type: PersistedRoomSnapshotForSupabase */
 
+/* Excluded from this release type: PresenceStore */
+
 /* Excluded from this release type: PutOp */
 
 /* Excluded from this release type: ReconnectManager */
@@ -143,7 +298,7 @@ export declare interface RoomSnapshot {
     /**
      * The current logical clock value for the room
      */
-    clock: number;
+    clock?: number;
     /**
      * Clock value when document data was last changed (optional for backwards compatibility)
      */
@@ -185,6 +340,7 @@ export declare interface RoomSnapshot {
  * ```
  *
  * @public
+ * @deprecated use the storage.transaction method instead
  */
 export declare interface RoomStoreMethods<R extends UnknownRecord = UnknownRecord> {
     /**
@@ -214,6 +370,73 @@ export declare interface RoomStoreMethods<R extends UnknownRecord = UnknownRecor
     getAll(): R[];
 }
 
+/**
+ * SQLite-based implementation of TLSyncStorage.
+ * Stores documents, tombstones, metadata, and clock values in SQLite tables.
+ *
+ * This storage backend provides persistent synchronization state that survives
+ * process restarts, unlike InMemorySyncStorage which loses data when the process ends.
+ *
+ * @example
+ * ```ts
+ * // With Cloudflare Durable Objects
+ * import { SQLiteSyncStorage, DurableObjectSqliteSyncWrapper } from '@tldraw/sync-core'
+ *
+ * const sql = new DurableObjectSqliteSyncWrapper(this.ctx.storage)
+ * const storage = new SQLiteSyncStorage({ sql })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With Node.js sqlite (Node 22.5+)
+ * import { DatabaseSync } from 'node:sqlite'
+ * import { SQLiteSyncStorage, NodeSqliteWrapper } from '@tldraw/sync-core'
+ *
+ * const db = new DatabaseSync('sync-state.db')
+ * const sql = new NodeSqliteWrapper(db)
+ * const storage = new SQLiteSyncStorage({ sql })
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Initialize with an existing snapshot
+ * const storage = new SQLiteSyncStorage({ sql, snapshot: existingSnapshot })
+ * ```
+ *
+ * @public
+ */
+export declare class SQLiteSyncStorage<R extends UnknownRecord> implements TLSyncStorage<R> {
+    /**
+     * Check if the storage has been initialized (has data in the clock table).
+     * Useful for determining whether to load from an external source on first access.
+     */
+    static hasBeenInitialized(storage: TLSyncSqliteWrapper): boolean;
+    /**
+     * Get the current document clock value from storage without fully initializing.
+     * Returns null if storage has not been initialized.
+     * Useful for comparing storage freshness against external sources.
+     */
+    static getDocumentClock(storage: TLSyncSqliteWrapper): null | number;
+    private readonly stmts;
+    private readonly sql;
+    constructor({ sql, snapshot, onChange, }: {
+        onChange?(arg: TLSyncStorageOnChangeCallbackProps): unknown;
+        snapshot?: RoomSnapshot | StoreSnapshot<R>;
+        sql: TLSyncSqliteWrapper;
+    });
+    private notifier;
+    onChange(callback: (arg: TLSyncStorageOnChangeCallbackProps) => void): () => void;
+    transaction<T>(callback: TLSyncStorageTransactionCallback<R, T>, opts?: TLSyncStorageTransactionOptions): TLSyncStorageTransactionResult<T, R>;
+    getClock(): number;
+    /* Excluded from this release type: _getTombstoneHistoryStartsAtClock */
+    /* Excluded from this release type: _getSchema */
+    /* Excluded from this release type: _setSchema */
+    /* Excluded from this release type: pruneTombstones */
+    getSnapshot(): RoomSnapshot;
+    private _iterateDocuments;
+    private _iterateTombstones;
+}
+
 /**
  * Function type for subscribing to events with a callback.
  * Returns an unsubscribe function to clean up the listener.
@@ -225,6 +448,29 @@ export declare interface RoomStoreMethods<R extends UnknownRecord = UnknownRecor
  */
 export declare type SubscribingFn<T> = (cb: (val: T) => void) => () => void;
 
+/**
+ * Minimal interface for a synchronous SQLite database.
+ *
+ * This interface is compatible with:
+ * - `node:sqlite` DatabaseSync (Node.js 22.5+)
+ * - `better-sqlite3` Database
+ *
+ * Any SQLite library that provides synchronous `exec` and `prepare` methods
+ * with the signatures below can be used with {@link NodeSqliteWrapper}.
+ *
+ * @public
+ */
+export declare interface SyncSqliteDatabase {
+    /** Execute raw SQL without returning results */
+    exec(sql: string): void;
+    /** Prepare a statement for execution */
+    prepare(sql: string): {
+        all(...params: unknown[]): unknown[];
+        iterate(...params: unknown[]): IterableIterator<unknown>;
+        run(...params: unknown[]): unknown;
+    };
+}
+
 /* Excluded from this release type: TLConnectRequest */
 
 /**
@@ -453,35 +699,12 @@ export declare class TLRemoteSyncError extends Error {
  * @public
  */
 export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, SessionMeta = void> {
-    readonly opts: {
-        /* Excluded from this release type: onPresenceChange */
-        clientTimeout?: number;
-        initialSnapshot?: RoomSnapshot | TLStoreSnapshot;
-        log?: TLSyncLog;
-        onAfterReceiveMessage?: (args: {
-            /* Excluded from this release type: message */
-            meta: SessionMeta;
-            sessionId: string;
-            stringified: string;
-        }) => void;
-        onBeforeSendMessage?: (args: {
-            /* Excluded from this release type: message */
-            meta: SessionMeta;
-            sessionId: string;
-            stringified: string;
-        }) => void;
-        onDataChange?(): void;
-        onSessionRemoved?: (room: TLSocketRoom<R, SessionMeta>, args: {
-            meta: SessionMeta;
-            numSessionsRemaining: number;
-            sessionId: string;
-        }) => void;
-        schema?: StoreSchema<R, any>;
-    };
+    readonly opts: TLSocketRoomOptions<R, SessionMeta>;
     private room;
     private readonly sessions;
     readonly log?: TLSyncLog;
-    private readonly syncCallbacks;
+    storage: TLSyncStorage<R>;
+    private disposables;
     /**
      * Creates a new TLSocketRoom instance for managing collaborative document synchronization.
      *
@@ -496,31 +719,7 @@ export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, Sessi
      *   - onDataChange - Called when document data changes
      *   - onPresenceChange - Called when presence data changes
      */
-    constructor(opts: {
-        /* Excluded from this release type: onPresenceChange */
-        clientTimeout?: number;
-        initialSnapshot?: RoomSnapshot | TLStoreSnapshot;
-        log?: TLSyncLog;
-        onAfterReceiveMessage?: (args: {
-            /* Excluded from this release type: message */
-            meta: SessionMeta;
-            sessionId: string;
-            stringified: string;
-        }) => void;
-        onBeforeSendMessage?: (args: {
-            /* Excluded from this release type: message */
-            meta: SessionMeta;
-            sessionId: string;
-            stringified: string;
-        }) => void;
-        onDataChange?(): void;
-        onSessionRemoved?: (room: TLSocketRoom<R, SessionMeta>, args: {
-            meta: SessionMeta;
-            numSessionsRemaining: number;
-            sessionId: string;
-        }) => void;
-        schema?: StoreSchema<R, any>;
-    });
+    constructor(opts: TLSocketRoomOptions<R, SessionMeta>);
     /**
      * Returns the number of active sessions.
      * Note that this is not the same as the number of connected sockets!
@@ -658,7 +857,7 @@ export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, Sessi
      * }
      * ```
      */
-    getRecord(id: string): R | undefined;
+    getRecord(id: string): R;
     /**
      * Returns information about all active sessions in the room. Each session
      * represents a connected client with their current connection status and metadata.
@@ -694,6 +893,7 @@ export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, Sessi
      * to restore the room state later or revert to a previous version.
      *
      * @returns Complete room snapshot including documents, clock values, and tombstones
+     * @deprecated if you need to do this use
      *
      * @example
      * ```ts
@@ -708,7 +908,6 @@ export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, Sessi
      */
     getCurrentSnapshot(): RoomSnapshot;
     /* Excluded from this release type: getPresenceRecords */
-    /* Excluded from this release type: getCurrentSerializedSnapshot */
     /**
      * Loads a document snapshot, completely replacing the current room state.
      * This will disconnect all current clients and update the document to match
@@ -770,6 +969,7 @@ export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, Sessi
      *   }
      * })
      * ```
+     * @deprecated use the storage.transaction method instead
      */
     updateStore(updater: (store: RoomStoreMethods<R>) => Promise<void> | void): Promise<void>;
     /**
@@ -859,6 +1059,43 @@ export declare class TLSocketRoom<R extends UnknownRecord = UnknownRecord, Sessi
     isClosed(): boolean;
 }
 
+/**
+ * Base options for TLSocketRoom.
+ * @public
+ */
+export declare interface TLSocketRoomOptions<R extends UnknownRecord, SessionMeta> {
+    storage?: TLSyncStorage<R>;
+    /**
+     * @deprecated use the storage option instead
+     */
+    initialSnapshot?: RoomSnapshot | TLStoreSnapshot;
+    /**
+     * @deprecated use the storage option with an onChange callback instead
+     */
+    onDataChange?(): void;
+    schema?: StoreSchema<R, any>;
+    clientTimeout?: number;
+    log?: TLSyncLog;
+    onSessionRemoved?: (room: TLSocketRoom<R, SessionMeta>, args: {
+        meta: SessionMeta;
+        numSessionsRemaining: number;
+        sessionId: string;
+    }) => void;
+    onBeforeSendMessage?: (args: {
+        /* Excluded from this release type: message */
+        meta: SessionMeta;
+        sessionId: string;
+        stringified: string;
+    }) => void;
+    onAfterReceiveMessage?: (args: {
+        /* Excluded from this release type: message */
+        meta: SessionMeta;
+        sessionId: string;
+        stringified: string;
+    }) => void;
+    /* Excluded from this release type: onPresenceChange */
+}
+
 /* Excluded from this release type: TLSocketServerSentDataEvent */
 
 /* Excluded from this release type: TLSocketServerSentEvent */
@@ -881,6 +1118,26 @@ export declare type TLSocketStatusChangeEvent = {
 
 /* Excluded from this release type: TLSocketStatusListener */
 
+/**
+ * Valid input value types for SQLite query parameters.
+ * These are the types that can be passed as bindings to prepared statements.
+ * @public
+ */
+export declare type TLSqliteInputValue = bigint | null | number | string | Uint8Array;
+
+/**
+ * Possible output value types returned from SQLite queries.
+ * Includes all input types plus Uint8Array for BLOB columns.
+ * @public
+ */
+export declare type TLSqliteOutputValue = bigint | null | number | string | Uint8Array;
+
+/**
+ * A row returned from a SQLite query, mapping column names to their values.
+ * @public
+ */
+export declare type TLSqliteRow = Record<string, TLSqliteOutputValue>;
+
 /**
  * Main client-side synchronization engine for collaborative tldraw applications.
  *
@@ -1144,6 +1401,15 @@ export declare const TLSyncErrorCloseEventReason: {
  */
 export declare type TLSyncErrorCloseEventReason = (typeof TLSyncErrorCloseEventReason)[keyof typeof TLSyncErrorCloseEventReason];
 
+/**
+ * Respresents a diff of puts and deletes.
+ * @public
+ */
+export declare interface TLSyncForwardDiff<R extends UnknownRecord> {
+    puts: Record<string, [before: R, after: R] | R>;
+    deletes: string[];
+}
+
 /**
  * Logging interface for TLSocketRoom operations. Provides optional methods
  * for warning and error logging during synchronization operations.
@@ -1175,6 +1441,165 @@ export declare interface TLSyncLog {
 
 /* Excluded from this release type: TLSyncRoom */
 
+/**
+ * A prepared statement that can be executed multiple times with different bindings.
+ * @public
+ */
+export declare interface TLSyncSqliteStatement<TResult extends TLSqliteRow | void, TParams extends TLSqliteInputValue[] = []> {
+    /** Execute the statement and iterate over results one at a time */
+    iterate(...bindings: TParams): IterableIterator<TResult>;
+    /** Execute the statement and return all results as an array */
+    all(...bindings: TParams): TResult[];
+    /** Execute the statement without returning results (for DML) */
+    run(...bindings: TParams): void;
+}
+
+/**
+ * Interface for SQLite storage with prepare, exec and transaction capabilities.
+ * @public
+ */
+export declare interface TLSyncSqliteWrapper {
+    /** Optional configuration for table names. If not provided, defaults are used. */
+    readonly config?: TLSyncSqliteWrapperConfig;
+    /** Prepare a SQL statement for execution */
+    prepare<TResult extends TLSqliteRow | void, TParams extends TLSqliteInputValue[] = []>(sql: string): TLSyncSqliteStatement<TResult, TParams>;
+    /** Execute raw SQL (for DDL, multi-statement scripts) */
+    exec(sql: string): void;
+    /** Execute a callback within a transaction */
+    transaction<T>(callback: () => T): T;
+}
+
+/**
+ * Configuration for SQLiteSyncStorage.
+ * @public
+ */
+export declare interface TLSyncSqliteWrapperConfig {
+    /** Prefix for all table names (default: ''). E.g. 'sync_' creates tables 'sync_documents', 'sync_tombstones', 'sync_metadata' */
+    tablePrefix?: string;
+}
+
+/**
+ * Pluggable synchronous transactional storage layer for TLSyncRoom.
+ * Provides methods for managing documents, tombstones, and clocks within transactions.
+ *
+ * @public
+ */
+export declare interface TLSyncStorage<R extends UnknownRecord> {
+    transaction<T>(callback: TLSyncStorageTransactionCallback<R, T>, opts?: TLSyncStorageTransactionOptions): TLSyncStorageTransactionResult<T, R>;
+    getClock(): number;
+    onChange(callback: (arg: TLSyncStorageOnChangeCallbackProps) => unknown): () => void;
+    getSnapshot?(): RoomSnapshot;
+}
+
+/**
+ * Result returned from getChangesSince, containing all changes since a given clock time.
+ * @public
+ */
+export declare interface TLSyncStorageGetChangesSinceResult<R extends UnknownRecord> {
+    /**
+     * The changes as a TLSyncForwardDiff.
+     */
+    diff: TLSyncForwardDiff<R>;
+    /**
+     * If true, the client should wipe all local data and replace with the server's state.
+     * This happens when the client's clock is too old and we've lost tombstone history.
+     */
+    wipeAll: boolean;
+}
+
+/**
+ * Properties passed to the onChange callback.
+ * @public
+ */
+export declare interface TLSyncStorageOnChangeCallbackProps {
+    /**
+     * The ID of the transaction that caused the change.
+     * This is useful for ignoring certain changes in onChange callbacks.
+     */
+    id?: string;
+    documentClock: number;
+}
+
+/**
+ * Transaction interface for storage operations. Provides methods to read and modify
+ * documents, tombstones, and metadata within a transaction.
+ *
+ * @public
+ */
+export declare interface TLSyncStorageTransaction<R extends UnknownRecord> extends SynchronousStorage<R> {
+    /**
+     * Get the current clock value.
+     * If the clock has incremented during the transaction,
+     * the incremented value will be returned.
+     *
+     * @returns The current clock value
+     */
+    getClock(): number;
+    /**
+     * Get all changes (document updates and deletions) since a given clock time.
+     * This is the main method for calculating diffs for client sync.
+     *
+     * @param sinceClock - The clock time to get changes since
+     * @returns Changes since the specified clock time
+     */
+    getChangesSince(sinceClock: number): TLSyncStorageGetChangesSinceResult<R> | undefined;
+}
+
+/**
+ * Callback type for a transaction.
+ * The conditional return type ensures that the callback is synchronous.
+ * @public
+ */
+export declare type TLSyncStorageTransactionCallback<R extends UnknownRecord, T> = (txn: TLSyncStorageTransaction<R>) => T extends Promise<any> ? {
+    __error: 'Transaction callbacks cannot be async. Use synchronous operations only.';
+} : T;
+
+/**
+ * Options for a transaction.
+ * @public
+ */
+export declare interface TLSyncStorageTransactionOptions {
+    /**
+     * Use this if you need to identify the transaction for logging or debugging purposes
+     * or for ignoring certain changes in onChange callbacks
+     */
+    id?: string;
+    /**
+     * Controls when the storage layer should emit the actual changes that occurred during the transaction.
+     *
+     * - `'always'` - Always emit the changes, regardless of whether they were applied verbatim
+     * - `'when-different'` - Only emit changes if the storage layer modified/embellished the records
+     *   (e.g., added server timestamps, normalized data, etc.)
+     *
+     * When changes are emitted, they will be available in the `changes` field of the transaction result.
+     * This is useful when the storage layer may transform records and the caller needs to know
+     * what actually changed rather than what was requested.
+     */
+    emitChanges?: 'always' | 'when-different';
+}
+
+/**
+ * Result returned from a storage transaction.
+ * @public
+ */
+export declare interface TLSyncStorageTransactionResult<T, R extends UnknownRecord = UnknownRecord> {
+    documentClock: number;
+    didChange: boolean;
+    result: T;
+    /**
+     * The actual changes that occurred during the transaction, if requested via `emitChanges` option.
+     * This is a RecordsDiff where:
+     * - `added` contains records that were put (we don't have "from" state for emitted changes)
+     * - `removed` contains records that were deleted (with placeholder values since we only have IDs)
+     * - `updated` is empty (emitted changes don't track before/after pairs)
+     *
+     * Only populated when:
+     * - `emitChanges: 'always'` was specified, or
+     * - `emitChanges: 'when-different'` was specified and the storage layer modified records
+     */
+    changes?: TLSyncForwardDiff<R>;
+}
+
 /* Excluded from this release type: ValueOp */
 
 /* Excluded from this release type: ValueOpType */