@tanstack/electric-db-collection 0.4.10 → 0.5.1

package/dist/esm/electric.d.ts

@@ -1,4 +1,4 @@
-import { BaseCollectionConfig, CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, SyncMode, UpdateMutationFnParams, UtilsRecord } from '@tanstack/db';
+import { BaseCollectionConfig, CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, SyncMode, UpdateMutationFnParams } from '@tanstack/db';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { GetExtensions, Message, Row, ShapeStreamOptions } from '@electric-sql/client';
 export { isChangeMessage, isControlMessage } from '@electric-sql/client';
@@ -28,11 +28,11 @@ export type MatchFunction<T extends Row<unknown>> = (message: Message<T>) => boo
 /**
  * Matching strategies for Electric synchronization
  * Handlers can return:
- * - Txid strategy: { txid: number | number[], timeout?: number } (recommended)
+ * - Txid strategy: { txid: number | number[], timeout?: number } (deprecated compatibility behavior)
  * - Void (no return value) - mutation completes without waiting
  *
  * The optional timeout property specifies how long to wait for the txid(s) in milliseconds.
- * If not specified, defaults to 5000ms.
+ * If not specified, defaults to 15000ms.
  */
 export type MatchingStrategy = {
     txid: Txid | Array<Txid>;
@@ -61,7 +61,7 @@ export type ElectricSyncMode = SyncMode | `progressive`;
  * @template T - The type of items in the collection
  * @template TSchema - The schema type for validation
  */
-export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never> extends Omit<BaseCollectionConfig<T, string | number, TSchema, ElectricCollectionUtils<T>, any>, `onInsert` | `onUpdate` | `onDelete` | `syncMode`> {
+export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never> extends Omit<BaseCollectionConfig<T, string | number, TSchema, ElectricCollectionUtils<T>>, `onInsert` | `onUpdate` | `onDelete` | `syncMode`> {
     /**
      * Configuration options for the ElectricSQL ShapeStream
      */
@@ -74,43 +74,82 @@ export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>,
     [ELECTRIC_TEST_HOOKS]?: ElectricTestHooks;
     /**
      * Optional asynchronous handler function called before an insert operation
+     *
+     * **IMPORTANT - Electric Synchronization:**
+     * This handler **must not resolve** until synchronization is confirmed.
+     * Await one of these synchronization utilities before the handler completes:
+     * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+     * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+     *
+     * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
+     *
      * @param params Object containing transaction and collection information
-     * @returns Promise resolving to { txid, timeout? } or void
+     * @returns Promise that should resolve after synchronization is complete
+     *
+     * **Deprecation notice:** Returning `{ txid }` from handlers is deprecated and will be removed in v1.0.
+     * Use `await collection.utils.awaitTxId(txid)` within the handler instead.
+     *
      * @example
-     * // Basic Electric insert handler with txid (recommended)
-     * onInsert: async ({ transaction }) => {
+     * // Recommended: Wait for txid to sync
+     * onInsert: async ({ transaction, collection }) => {
      *   const newItem = transaction.mutations[0].modified
      *   const result = await api.todos.create({
      *     data: newItem
      *   })
-     *   return { txid: result.txid }
+     *   // Wait for txid to sync before handler completes
+     *   await collection.utils.awaitTxId(result.txid)
      * }
      *
      * @example
      * // Insert handler with custom timeout
-     * onInsert: async ({ transaction }) => {
+     * onInsert: async ({ transaction, collection }) => {
+     *   const newItem = transaction.mutations[0].modified
+     *   const result = await api.todos.create({
+     *     data: newItem
+     *   })
+     *   // Wait up to 10 seconds for txid
+     *   await collection.utils.awaitTxId(result.txid, 10000)
+     * }
+     *
+     * @example
+     * // Insert handler with timeout error handling
+     * onInsert: async ({ transaction, collection }) => {
      *   const newItem = transaction.mutations[0].modified
      *   const result = await api.todos.create({
      *     data: newItem
      *   })
-     *   return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds
+     *
+     *   try {
+     *     await collection.utils.awaitTxId(result.txid, 5000)
+     *   } catch (error) {
+     *     // Decide sync timeout policy:
+     *     // - Throw to rollback optimistic state
+     *     // - Catch to keep optimistic state (eventual consistency)
+     *     // - Schedule background retry
+     *     console.warn('Sync timeout, keeping optimistic state:', error)
+     *     // Don't throw - allow optimistic state to persist
+     *   }
      * }
      *
      * @example
-     * // Insert handler with multiple items - return array of txids
-     * onInsert: async ({ transaction }) => {
+     * // Insert handler with multiple items
+     * onInsert: async ({ transaction, collection }) => {
      *   const items = transaction.mutations.map(m => m.modified)
      *   const results = await Promise.all(
      *     items.map(item => api.todos.create({ data: item }))
      *   )
-     *   return { txid: results.map(r => r.txid) }
+     *   // Wait for all txids to sync
+     *   await Promise.all(
+     *     results.map(r => collection.utils.awaitTxId(r.txid))
+     *   )
      * }
      *
      * @example
-     * // Use awaitMatch utility for custom matching
+     * // Alternative: Use awaitMatch utility for custom matching logic
      * onInsert: async ({ transaction, collection }) => {
      *   const newItem = transaction.mutations[0].modified
      *   await api.todos.create({ data: newItem })
+     *   // Wait for specific change to appear in sync stream
      *   await collection.utils.awaitMatch(
      *     (message) => isChangeMessage(message) &&
      *                  message.headers.operation === 'insert' &&
@@ -121,24 +160,39 @@ export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>,
     onInsert?: (params: InsertMutationFnParams<T, string | number, ElectricCollectionUtils<T>>) => Promise<MatchingStrategy>;
     /**
      * Optional asynchronous handler function called before an update operation
+     *
+     * **IMPORTANT - Electric Synchronization:**
+     * This handler **must not resolve** until synchronization is confirmed.
+     * Await one of these synchronization utilities before the handler completes:
+     * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+     * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+     *
+     * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
+     *
      * @param params Object containing transaction and collection information
-     * @returns Promise resolving to { txid, timeout? } or void
+     * @returns Promise that should resolve after synchronization is complete
+     *
+     * **Deprecation notice:** Returning `{ txid }` from handlers is deprecated and will be removed in v1.0.
+     * Use `await collection.utils.awaitTxId(txid)` within the handler instead.
+     *
      * @example
-     * // Basic Electric update handler with txid (recommended)
-     * onUpdate: async ({ transaction }) => {
+     * // Recommended: Wait for txid to sync
+     * onUpdate: async ({ transaction, collection }) => {
      *   const { original, changes } = transaction.mutations[0]
      *   const result = await api.todos.update({
      *     where: { id: original.id },
      *     data: changes
      *   })
-     *   return { txid: result.txid }
+     *   // Wait for txid to sync before handler completes
+     *   await collection.utils.awaitTxId(result.txid)
      * }
      *
      * @example
-     * // Use awaitMatch utility for custom matching
+     * // Alternative: Use awaitMatch utility for custom matching logic
      * onUpdate: async ({ transaction, collection }) => {
      *   const { original, changes } = transaction.mutations[0]
      *   await api.todos.update({ where: { id: original.id }, data: changes })
+     *   // Wait for specific change to appear in sync stream
      *   await collection.utils.awaitMatch(
      *     (message) => isChangeMessage(message) &&
      *                  message.headers.operation === 'update' &&
@@ -149,23 +203,38 @@ export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>,
     onUpdate?: (params: UpdateMutationFnParams<T, string | number, ElectricCollectionUtils<T>>) => Promise<MatchingStrategy>;
     /**
      * Optional asynchronous handler function called before a delete operation
+     *
+     * **IMPORTANT - Electric Synchronization:**
+     * This handler **must not resolve** until synchronization is confirmed.
+     * Await one of these synchronization utilities before the handler completes:
+     * 1. `await collection.utils.awaitTxId(txid)` (recommended for most cases)
+     * 2. `await collection.utils.awaitMatch(fn)` for custom matching logic
+     *
+     * Simply returning without waiting for sync will drop optimistic state too early, causing UI glitches.
+     *
      * @param params Object containing transaction and collection information
-     * @returns Promise resolving to { txid, timeout? } or void
+     * @returns Promise that should resolve after synchronization is complete
+     *
+     * **Deprecation notice:** Returning `{ txid }` from handlers is deprecated and will be removed in v1.0.
+     * Use `await collection.utils.awaitTxId(txid)` within the handler instead.
+     *
      * @example
-     * // Basic Electric delete handler with txid (recommended)
-     * onDelete: async ({ transaction }) => {
+     * // Recommended: Wait for txid to sync
+     * onDelete: async ({ transaction, collection }) => {
      *   const mutation = transaction.mutations[0]
      *   const result = await api.todos.delete({
      *     id: mutation.original.id
      *   })
-     *   return { txid: result.txid }
+     *   // Wait for txid to sync before handler completes
+     *   await collection.utils.awaitTxId(result.txid)
      * }
      *
      * @example
-     * // Use awaitMatch utility for custom matching
+     * // Alternative: Use awaitMatch utility for custom matching logic
      * onDelete: async ({ transaction, collection }) => {
      *   const mutation = transaction.mutations[0]
      *   await api.todos.delete({ id: mutation.original.id })
+     *   // Wait for specific change to appear in sync stream
      *   await collection.utils.awaitMatch(
      *     (message) => isChangeMessage(message) &&
      *                  message.headers.operation === 'delete' &&
@@ -186,7 +255,7 @@ export type AwaitMatchFn<T extends Row<unknown>> = (matchFn: MatchFunction<T>, t
 /**
  * Electric collection utilities type
  */
-export interface ElectricCollectionUtils<T extends Row<unknown> = Row<unknown>> extends UtilsRecord {
+export interface ElectricCollectionUtils<T extends Row<unknown> = Row<unknown>> {
     awaitTxId: AwaitTxIdFn;
     awaitMatch: AwaitMatchFn<T>;
 }