@tanstack/electric-db-collection 0.1.18 → 0.1.20

package/dist/cjs/electric.cjs

@@ -16,12 +16,9 @@ function hasTxids(message) {
 }
 function electricCollectionOptions(config) {
   const seenTxids = new store.Store(/* @__PURE__ */ new Set([]));
-  const sync = createElectricSync(
-    config.shapeOptions,
-    {
-      seenTxids
-    }
-  );
+  const sync = createElectricSync(config.shapeOptions, {
+    seenTxids
+  });
   const awaitTxId = async (txId, timeout = 3e4) => {
     debug(`awaitTxId called with txid %d`, txId);
     if (typeof txId !== `number`) {

package/dist/cjs/electric.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"electric.cjs","sources":["../../src/electric.ts"],"sourcesContent":["import {\n  ShapeStream,\n  isChangeMessage,\n  isControlMessage,\n} from \"@electric-sql/client\"\nimport { Store } from \"@tanstack/store\"\nimport DebugModule from \"debug\"\nimport {\n  ElectricDeleteHandlerMustReturnTxIdError,\n  ElectricInsertHandlerMustReturnTxIdError,\n  ElectricUpdateHandlerMustReturnTxIdError,\n  ExpectedNumberInAwaitTxIdError,\n  TimeoutWaitingForTxIdError,\n} from \"./errors\"\nimport type {\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InsertMutationFnParams,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"@tanstack/db\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type {\n  ControlMessage,\n  GetExtensions,\n  Message,\n  Row,\n  ShapeStreamOptions,\n} from \"@electric-sql/client\"\n\nconst debug = DebugModule.debug(`ts/db:electric`)\n\n/**\n * Type representing a transaction ID in ElectricSQL\n */\nexport type Txid = number\n\n// The `InferSchemaOutput` and `ResolveType` are copied from the `@tanstack/db` package\n// but we modified `InferSchemaOutput` slightly to restrict the schema output to `Row<unknown>`\n// This is needed in order for `GetExtensions` to be able to infer the parser extensions type from the schema\ntype InferSchemaOutput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferOutput<T> extends Row<unknown>\n    ? StandardSchemaV1.InferOutput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\ntype ResolveType<\n  TExplicit extends Row<unknown> = Row<unknown>,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends object = Record<string, unknown>,\n> =\n  unknown extends GetExtensions<TExplicit>\n    ? [TSchema] extends [never]\n      ? TFallback\n      : InferSchemaOutput<TSchema>\n    : TExplicit\n\n/**\n * Configuration interface for Electric collection options\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n *\n * @remarks\n * Type resolution follows a priority order:\n * 1. If you provide an explicit type via generic parameter, it will be used\n * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred\n * 3. If neither explicit type nor schema is provided, the fallback type will be used\n *\n * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.\n */\nexport interface ElectricCollectionConfig<\n  TExplicit extends Row<unknown> = Row<unknown>,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends Row<unknown> = Row<unknown>,\n> {\n  /**\n   * Configuration options for the ElectricSQL ShapeStream\n   */\n  shapeOptions: ShapeStreamOptions<\n    GetExtensions<ResolveType<TExplicit, TSchema, TFallback>>\n  >\n\n  /**\n   * All standard Collection configuration properties\n   */\n  id?: string\n  schema?: TSchema\n  getKey: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`getKey`]\n  sync?: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`sync`]\n\n  /**\n   * Optional asynchronous handler function called before an insert operation\n   * Must return an object containing a txid number or array of txids\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to an object with txid or txids\n   * @example\n   * // Basic Electric insert handler - MUST return { txid: number }\n   * onInsert: async ({ transaction }) => {\n   *   const newItem = transaction.mutations[0].modified\n   *   const result = await api.todos.create({\n   *     data: newItem\n   *   })\n   *   return { txid: result.txid } // Required for Electric sync matching\n   * }\n   *\n   * @example\n   * // Insert handler with multiple items - return array of txids\n   * onInsert: async ({ transaction }) => {\n   *   const items = transaction.mutations.map(m => m.modified)\n   *   const results = await Promise.all(\n   *     items.map(item => api.todos.create({ data: item }))\n   *   )\n   *   return { txid: results.map(r => r.txid) } // Array of txids\n   * }\n   *\n   * @example\n   * // Insert handler with error handling\n   * onInsert: async ({ transaction }) => {\n   *   try {\n   *     const newItem = transaction.mutations[0].modified\n   *     const result = await api.createTodo(newItem)\n   *     return { txid: result.txid }\n   *   } catch (error) {\n   *     console.error('Insert failed:', error)\n   *     throw error // This will cause the transaction to fail\n   *   }\n   * }\n   *\n   * @example\n   * // Insert handler with batch operation - single txid\n   * onInsert: async ({ transaction }) => {\n   *   const items = transaction.mutations.map(m => m.modified)\n   *   const result = await api.todos.createMany({\n   *     data: items\n   *   })\n   *   return { txid: result.txid } // Single txid for batch operation\n   * }\n   */\n  onInsert?: (\n    params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<{ txid: Txid | Array<Txid> }>\n\n  /**\n   * Optional asynchronous handler function called before an update operation\n   * Must return an object containing a txid number or array of txids\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to an object with txid or txids\n   * @example\n   * // Basic Electric update handler - MUST return { txid: number }\n   * onUpdate: async ({ transaction }) => {\n   *   const { original, changes } = transaction.mutations[0]\n   *   const result = await api.todos.update({\n   *     where: { id: original.id },\n   *     data: changes // Only the changed fields\n   *   })\n   *   return { txid: result.txid } // Required for Electric sync matching\n   * }\n   *\n   * @example\n   * // Update handler with multiple items - return array of txids\n   * onUpdate: async ({ transaction }) => {\n   *   const updates = await Promise.all(\n   *     transaction.mutations.map(m =>\n   *       api.todos.update({\n   *         where: { id: m.original.id },\n   *         data: m.changes\n   *       })\n   *     )\n   *   )\n   *   return { txid: updates.map(u => u.txid) } // Array of txids\n   * }\n   *\n   * @example\n   * // Update handler with optimistic rollback\n   * onUpdate: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   try {\n   *     const result = await api.updateTodo(mutation.original.id, mutation.changes)\n   *     return { txid: result.txid }\n   *   } catch (error) {\n   *     // Transaction will automatically rollback optimistic changes\n   *     console.error('Update failed, rolling back:', error)\n   *     throw error\n   *   }\n   * }\n   */\n  onUpdate?: (\n    params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<{ txid: Txid | Array<Txid> }>\n\n  /**\n   * Optional asynchronous handler function called before a delete operation\n   * Must return an object containing a txid number or array of txids\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to an object with txid or txids\n   * @example\n   * // Basic Electric delete handler - MUST return { txid: number }\n   * onDelete: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   const result = await api.todos.delete({\n   *     id: mutation.original.id\n   *   })\n   *   return { txid: result.txid } // Required for Electric sync matching\n   * }\n   *\n   * @example\n   * // Delete handler with multiple items - return array of txids\n   * onDelete: async ({ transaction }) => {\n   *   const deletes = await Promise.all(\n   *     transaction.mutations.map(m =>\n   *       api.todos.delete({\n   *         where: { id: m.key }\n   *       })\n   *     )\n   *   )\n   *   return { txid: deletes.map(d => d.txid) } // Array of txids\n   * }\n   *\n   * @example\n   * // Delete handler with batch operation - single txid\n   * onDelete: async ({ transaction }) => {\n   *   const idsToDelete = transaction.mutations.map(m => m.original.id)\n   *   const result = await api.todos.deleteMany({\n   *     ids: idsToDelete\n   *   })\n   *   return { txid: result.txid } // Single txid for batch operation\n   * }\n   *\n   * @example\n   * // Delete handler with optimistic rollback\n   * onDelete: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   try {\n   *     const result = await api.deleteTodo(mutation.original.id)\n   *     return { txid: result.txid }\n   *   } catch (error) {\n   *     // Transaction will automatically rollback optimistic changes\n   *     console.error('Delete failed, rolling back:', error)\n   *     throw error\n   *   }\n   * }\n   *\n   */\n  onDelete?: (\n    params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<{ txid: Txid | Array<Txid> }>\n}\n\nfunction isUpToDateMessage<T extends Row<unknown>>(\n  message: Message<T>\n): message is ControlMessage & { up_to_date: true } {\n  return isControlMessage(message) && message.headers.control === `up-to-date`\n}\n\nfunction isMustRefetchMessage<T extends Row<unknown>>(\n  message: Message<T>\n): message is ControlMessage & { headers: { control: `must-refetch` } } {\n  return isControlMessage(message) && message.headers.control === `must-refetch`\n}\n\n// Check if a message contains txids in its headers\nfunction hasTxids<T extends Row<unknown>>(\n  message: Message<T>\n): message is Message<T> & { headers: { txids?: Array<Txid> } } {\n  return `txids` in message.headers && Array.isArray(message.headers.txids)\n}\n\n/**\n * Type for the awaitTxId utility function\n */\nexport type AwaitTxIdFn = (txId: Txid, timeout?: number) => Promise<boolean>\n\n/**\n * Electric collection utilities type\n */\nexport interface ElectricCollectionUtils extends UtilsRecord {\n  awaitTxId: AwaitTxIdFn\n}\n\n/**\n * Creates Electric collection options for use with a standard Collection\n *\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @param config - Configuration options for the Electric collection\n * @returns Collection options with utilities\n */\nexport function electricCollectionOptions<\n  TExplicit extends Row<unknown> = Row<unknown>,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends Row<unknown> = Row<unknown>,\n>(config: ElectricCollectionConfig<TExplicit, TSchema, TFallback>) {\n  const seenTxids = new Store<Set<Txid>>(new Set([]))\n  const sync = createElectricSync<ResolveType<TExplicit, TSchema, TFallback>>(\n    config.shapeOptions,\n    {\n      seenTxids,\n    }\n  )\n\n  /**\n   * Wait for a specific transaction ID to be synced\n   * @param txId The transaction ID to wait for as a number\n   * @param timeout Optional timeout in milliseconds (defaults to 30000ms)\n   * @returns Promise that resolves when the txId is synced\n   */\n  const awaitTxId: AwaitTxIdFn = async (\n    txId: Txid,\n    timeout: number = 30000\n  ): Promise<boolean> => {\n    debug(`awaitTxId called with txid %d`, txId)\n    if (typeof txId !== `number`) {\n      throw new ExpectedNumberInAwaitTxIdError(typeof txId)\n    }\n\n    const hasTxid = seenTxids.state.has(txId)\n    if (hasTxid) return true\n\n    return new Promise((resolve, reject) => {\n      const timeoutId = setTimeout(() => {\n        unsubscribe()\n        reject(new TimeoutWaitingForTxIdError(txId))\n      }, timeout)\n\n      const unsubscribe = seenTxids.subscribe(() => {\n        if (seenTxids.state.has(txId)) {\n          debug(`awaitTxId found match for txid %o`, txId)\n          clearTimeout(timeoutId)\n          unsubscribe()\n          resolve(true)\n        }\n      })\n    })\n  }\n\n  // Create wrapper handlers for direct persistence operations that handle txid awaiting\n  const wrappedOnInsert = config.onInsert\n    ? async (\n        params: InsertMutationFnParams<\n          ResolveType<TExplicit, TSchema, TFallback>\n        >\n      ) => {\n        // Runtime check (that doesn't follow type)\n        // eslint-disable-next-line\n        const handlerResult = (await config.onInsert!(params)) ?? {}\n        const txid = (handlerResult as { txid?: Txid | Array<Txid> }).txid\n\n        if (!txid) {\n          throw new ElectricInsertHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(txid)) {\n          await Promise.all(txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnUpdate = config.onUpdate\n    ? async (\n        params: UpdateMutationFnParams<\n          ResolveType<TExplicit, TSchema, TFallback>\n        >\n      ) => {\n        // Runtime check (that doesn't follow type)\n        // eslint-disable-next-line\n        const handlerResult = (await config.onUpdate!(params)) ?? {}\n        const txid = (handlerResult as { txid?: Txid | Array<Txid> }).txid\n\n        if (!txid) {\n          throw new ElectricUpdateHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(txid)) {\n          await Promise.all(txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnDelete = config.onDelete\n    ? async (\n        params: DeleteMutationFnParams<\n          ResolveType<TExplicit, TSchema, TFallback>\n        >\n      ) => {\n        const handlerResult = await config.onDelete!(params)\n        if (!handlerResult.txid) {\n          throw new ElectricDeleteHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(handlerResult.txid)) {\n          await Promise.all(handlerResult.txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(handlerResult.txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  // Extract standard Collection config properties\n  const {\n    shapeOptions: _shapeOptions,\n    onInsert: _onInsert,\n    onUpdate: _onUpdate,\n    onDelete: _onDelete,\n    ...restConfig\n  } = config\n\n  return {\n    ...restConfig,\n    sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      awaitTxId,\n    },\n  }\n}\n\n/**\n * Internal function to create ElectricSQL sync configuration\n */\nfunction createElectricSync<T extends Row<unknown>>(\n  shapeOptions: ShapeStreamOptions<GetExtensions<T>>,\n  options: {\n    seenTxids: Store<Set<Txid>>\n  }\n): SyncConfig<T> {\n  const { seenTxids } = options\n\n  // Store for the relation schema information\n  const relationSchema = new Store<string | undefined>(undefined)\n\n  /**\n   * Get the sync metadata for insert operations\n   * @returns Record containing relation information\n   */\n  const getSyncMetadata = (): Record<string, unknown> => {\n    // Use the stored schema if available, otherwise default to 'public'\n    const schema = relationSchema.state || `public`\n\n    return {\n      relation: shapeOptions.params?.table\n        ? [schema, shapeOptions.params.table]\n        : undefined,\n    }\n  }\n\n  let unsubscribeStream: () => void\n\n  return {\n    sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {\n      const { begin, write, commit, markReady, truncate, collection } = params\n\n      // Abort controller for the stream - wraps the signal if provided\n      const abortController = new AbortController()\n\n      if (shapeOptions.signal) {\n        shapeOptions.signal.addEventListener(\n          `abort`,\n          () => {\n            abortController.abort()\n          },\n          {\n            once: true,\n          }\n        )\n        if (shapeOptions.signal.aborted) {\n          abortController.abort()\n        }\n      }\n\n      const stream = new ShapeStream({\n        ...shapeOptions,\n        signal: abortController.signal,\n        onError: (errorParams) => {\n          // Just immediately mark ready if there's an error to avoid blocking\n          // apps waiting for `.preload()` to finish.\n          // Note that Electric sends a 409 error on a `must-refetch` message, but the\n          // ShapeStream handled this and it will not reach this handler, therefor\n          // this markReady will not be triggers by a `must-refetch`.\n          markReady()\n\n          if (shapeOptions.onError) {\n            return shapeOptions.onError(errorParams)\n          } else {\n            console.error(\n              `An error occurred while syncing collection: ${collection.id}, \\n` +\n                `it has been marked as ready to avoid blocking apps waiting for '.preload()' to finish. \\n` +\n                `You can provide an 'onError' handler on the shapeOptions to handle this error, and this message will not be logged.`,\n              errorParams\n            )\n          }\n\n          return\n        },\n      })\n      let transactionStarted = false\n      const newTxids = new Set<Txid>()\n\n      unsubscribeStream = stream.subscribe((messages: Array<Message<T>>) => {\n        let hasUpToDate = false\n\n        for (const message of messages) {\n          // Check for txids in the message and add them to our store\n          if (hasTxids(message)) {\n            message.headers.txids?.forEach((txid) => newTxids.add(txid))\n          }\n\n          if (isChangeMessage(message)) {\n            // Check if the message contains schema information\n            const schema = message.headers.schema\n            if (schema && typeof schema === `string`) {\n              // Store the schema for future use if it's a valid string\n              relationSchema.setState(() => schema)\n            }\n\n            if (!transactionStarted) {\n              begin()\n              transactionStarted = true\n            }\n\n            write({\n              type: message.headers.operation,\n              value: message.value,\n              // Include the primary key and relation info in the metadata\n              metadata: {\n                ...message.headers,\n              },\n            })\n          } else if (isUpToDateMessage(message)) {\n            hasUpToDate = true\n          } else if (isMustRefetchMessage(message)) {\n            debug(\n              `Received must-refetch message, starting transaction with truncate`\n            )\n\n            // Start a transaction and truncate the collection\n            if (!transactionStarted) {\n              begin()\n              transactionStarted = true\n            }\n\n            truncate()\n\n            // Reset hasUpToDate so we continue accumulating changes until next up-to-date\n            hasUpToDate = false\n          }\n        }\n\n        if (hasUpToDate) {\n          // Commit transaction if one was started\n          if (transactionStarted) {\n            commit()\n            transactionStarted = false\n          }\n\n          // Mark the collection as ready now that sync is up to date\n          markReady()\n\n          // Always commit txids when we receive up-to-date, regardless of transaction state\n          seenTxids.setState((currentTxids) => {\n            const clonedSeen = new Set<Txid>(currentTxids)\n            if (newTxids.size > 0) {\n              debug(`new txids synced from pg %O`, Array.from(newTxids))\n            }\n            newTxids.forEach((txid) => clonedSeen.add(txid))\n            newTxids.clear()\n            return clonedSeen\n          })\n        }\n      })\n\n      // Return the unsubscribe function\n      return () => {\n        // Unsubscribe from the stream\n        unsubscribeStream()\n        // Abort the abort controller to stop the stream\n        abortController.abort()\n      }\n    },\n    // Expose the getSyncMetadata function\n    getSyncMetadata,\n  }\n}\n"],"names":["isControlMessage","Store","ExpectedNumberInAwaitTxIdError","TimeoutWaitingForTxIdError","ElectricInsertHandlerMustReturnTxIdError","ElectricUpdateHandlerMustReturnTxIdError","ElectricDeleteHandlerMustReturnTxIdError","ShapeStream","isChangeMessage"],"mappings":";;;;;;AA+BA,MAAM,QAAQ,YAAY,MAAM,gBAAgB;AA2NhD,SAAS,kBACP,SACkD;AAClD,SAAOA,OAAAA,iBAAiB,OAAO,KAAK,QAAQ,QAAQ,YAAY;AAClE;AAEA,SAAS,qBACP,SACsE;AACtE,SAAOA,OAAAA,iBAAiB,OAAO,KAAK,QAAQ,QAAQ,YAAY;AAClE;AAGA,SAAS,SACP,SAC8D;AAC9D,SAAO,WAAW,QAAQ,WAAW,MAAM,QAAQ,QAAQ,QAAQ,KAAK;AAC1E;AAuBO,SAAS,0BAId,QAAiE;AACjE,QAAM,YAAY,IAAIC,MAAAA,0BAAqB,IAAI,CAAA,CAAE,CAAC;AAClD,QAAM,OAAO;AAAA,IACX,OAAO;AAAA,IACP;AAAA,MACE;AAAA,IAAA;AAAA,EACF;AASF,QAAM,YAAyB,OAC7B,MACA,UAAkB,QACG;AACrB,UAAM,iCAAiC,IAAI;AAC3C,QAAI,OAAO,SAAS,UAAU;AAC5B,YAAM,IAAIC,OAAAA,+BAA+B,OAAO,IAAI;AAAA,IACtD;AAEA,UAAM,UAAU,UAAU,MAAM,IAAI,IAAI;AACxC,QAAI,QAAS,QAAO;AAEpB,WAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,YAAM,YAAY,WAAW,MAAM;AACjC,oBAAA;AACA,eAAO,IAAIC,kCAA2B,IAAI,CAAC;AAAA,MAC7C,GAAG,OAAO;AAEV,YAAM,cAAc,UAAU,UAAU,MAAM;AAC5C,YAAI,UAAU,MAAM,IAAI,IAAI,GAAG;AAC7B,gBAAM,qCAAqC,IAAI;AAC/C,uBAAa,SAAS;AACtB,sBAAA;AACA,kBAAQ,IAAI;AAAA,QACd;AAAA,MACF,CAAC;AAAA,IACH,CAAC;AAAA,EACH;AAGA,QAAM,kBAAkB,OAAO,WAC3B,OACE,WAGG;AAGH,UAAM,gBAAiB,MAAM,OAAO,SAAU,MAAM,KAAM,CAAA;AAC1D,UAAM,OAAQ,cAAgD;AAE9D,QAAI,CAAC,MAAM;AACT,YAAM,IAAIC,OAAAA,yCAAA;AAAA,IACZ;AAGA,QAAI,MAAM,QAAQ,IAAI,GAAG;AACvB,YAAM,QAAQ,IAAI,KAAK,IAAI,CAAC,OAAO,UAAU,EAAE,CAAC,CAAC;AAAA,IACnD,OAAO;AACL,YAAM,UAAU,IAAI;AAAA,IACtB;AAEA,WAAO;AAAA,EACT,IACA;AAEJ,QAAM,kBAAkB,OAAO,WAC3B,OACE,WAGG;AAGH,UAAM,gBAAiB,MAAM,OAAO,SAAU,MAAM,KAAM,CAAA;AAC1D,UAAM,OAAQ,cAAgD;AAE9D,QAAI,CAAC,MAAM;AACT,YAAM,IAAIC,OAAAA,yCAAA;AAAA,IACZ;AAGA,QAAI,MAAM,QAAQ,IAAI,GAAG;AACvB,YAAM,QAAQ,IAAI,KAAK,IAAI,CAAC,OAAO,UAAU,EAAE,CAAC,CAAC;AAAA,IACnD,OAAO;AACL,YAAM,UAAU,IAAI;AAAA,IACtB;AAEA,WAAO;AAAA,EACT,IACA;AAEJ,QAAM,kBAAkB,OAAO,WAC3B,OACE,WAGG;AACH,UAAM,gBAAgB,MAAM,OAAO,SAAU,MAAM;AACnD,QAAI,CAAC,cAAc,MAAM;AACvB,YAAM,IAAIC,OAAAA,yCAAA;AAAA,IACZ;AAGA,QAAI,MAAM,QAAQ,cAAc,IAAI,GAAG;AACrC,YAAM,QAAQ,IAAI,cAAc,KAAK,IAAI,CAAC,OAAO,UAAU,EAAE,CAAC,CAAC;AAAA,IACjE,OAAO;AACL,YAAM,UAAU,cAAc,IAAI;AAAA,IACpC;AAEA,WAAO;AAAA,EACT,IACA;AAGJ,QAAM;AAAA,IACJ,cAAc;AAAA,IACd,UAAU;AAAA,IACV,UAAU;AAAA,IACV,UAAU;AAAA,IACV,GAAG;AAAA,EAAA,IACD;AAEJ,SAAO;AAAA,IACL,GAAG;AAAA,IACH;AAAA,IACA,UAAU;AAAA,IACV,UAAU;AAAA,IACV,UAAU;AAAA,IACV,OAAO;AAAA,MACL;AAAA,IAAA;AAAA,EACF;AAEJ;AAKA,SAAS,mBACP,cACA,SAGe;AACf,QAAM,EAAE,cAAc;AAGtB,QAAM,iBAAiB,IAAIL,MAAAA,MAA0B,MAAS;AAM9D,QAAM,kBAAkB,MAA+B;;AAErD,UAAM,SAAS,eAAe,SAAS;AAEvC,WAAO;AAAA,MACL,YAAU,kBAAa,WAAb,mBAAqB,SAC3B,CAAC,QAAQ,aAAa,OAAO,KAAK,IAClC;AAAA,IAAA;AAAA,EAER;AAEA,MAAI;AAEJ,SAAO;AAAA,IACL,MAAM,CAAC,WAAiD;AACtD,YAAM,EAAE,OAAO,OAAO,QAAQ,WAAW,UAAU,eAAe;AAGlE,YAAM,kBAAkB,IAAI,gBAAA;AAE5B,UAAI,aAAa,QAAQ;AACvB,qBAAa,OAAO;AAAA,UAClB;AAAA,UACA,MAAM;AACJ,4BAAgB,MAAA;AAAA,UAClB;AAAA,UACA;AAAA,YACE,MAAM;AAAA,UAAA;AAAA,QACR;AAEF,YAAI,aAAa,OAAO,SAAS;AAC/B,0BAAgB,MAAA;AAAA,QAClB;AAAA,MACF;AAEA,YAAM,SAAS,IAAIM,mBAAY;AAAA,QAC7B,GAAG;AAAA,QACH,QAAQ,gBAAgB;AAAA,QACxB,SAAS,CAAC,gBAAgB;AAMxB,oBAAA;AAEA,cAAI,aAAa,SAAS;AACxB,mBAAO,aAAa,QAAQ,WAAW;AAAA,UACzC,OAAO;AACL,oBAAQ;AAAA,cACN,+CAA+C,WAAW,EAAE;AAAA;AAAA;AAAA,cAG5D;AAAA,YAAA;AAAA,UAEJ;AAEA;AAAA,QACF;AAAA,MAAA,CACD;AACD,UAAI,qBAAqB;AACzB,YAAM,+BAAe,IAAA;AAErB,0BAAoB,OAAO,UAAU,CAAC,aAAgC;;AACpE,YAAI,cAAc;AAElB,mBAAW,WAAW,UAAU;AAE9B,cAAI,SAAS,OAAO,GAAG;AACrB,0BAAQ,QAAQ,UAAhB,mBAAuB,QAAQ,CAAC,SAAS,SAAS,IAAI,IAAI;AAAA,UAC5D;AAEA,cAAIC,OAAAA,gBAAgB,OAAO,GAAG;AAE5B,kBAAM,SAAS,QAAQ,QAAQ;AAC/B,gBAAI,UAAU,OAAO,WAAW,UAAU;AAExC,6BAAe,SAAS,MAAM,MAAM;AAAA,YACtC;AAEA,gBAAI,CAAC,oBAAoB;AACvB,oBAAA;AACA,mCAAqB;AAAA,YACvB;AAEA,kBAAM;AAAA,cACJ,MAAM,QAAQ,QAAQ;AAAA,cACtB,OAAO,QAAQ;AAAA;AAAA,cAEf,UAAU;AAAA,gBACR,GAAG,QAAQ;AAAA,cAAA;AAAA,YACb,CACD;AAAA,UACH,WAAW,kBAAkB,OAAO,GAAG;AACrC,0BAAc;AAAA,UAChB,WAAW,qBAAqB,OAAO,GAAG;AACxC;AAAA,cACE;AAAA,YAAA;AAIF,gBAAI,CAAC,oBAAoB;AACvB,oBAAA;AACA,mCAAqB;AAAA,YACvB;AAEA,qBAAA;AAGA,0BAAc;AAAA,UAChB;AAAA,QACF;AAEA,YAAI,aAAa;AAEf,cAAI,oBAAoB;AACtB,mBAAA;AACA,iCAAqB;AAAA,UACvB;AAGA,oBAAA;AAGA,oBAAU,SAAS,CAAC,iBAAiB;AACnC,kBAAM,aAAa,IAAI,IAAU,YAAY;AAC7C,gBAAI,SAAS,OAAO,GAAG;AACrB,oBAAM,+BAA+B,MAAM,KAAK,QAAQ,CAAC;AAAA,YAC3D;AACA,qBAAS,QAAQ,CAAC,SAAS,WAAW,IAAI,IAAI,CAAC;AAC/C,qBAAS,MAAA;AACT,mBAAO;AAAA,UACT,CAAC;AAAA,QACH;AAAA,MACF,CAAC;AAGD,aAAO,MAAM;AAEX,0BAAA;AAEA,wBAAgB,MAAA;AAAA,MAClB;AAAA,IACF;AAAA;AAAA,IAEA;AAAA,EAAA;AAEJ;;"}
+{"version":3,"file":"electric.cjs","sources":["../../src/electric.ts"],"sourcesContent":["import {\n  ShapeStream,\n  isChangeMessage,\n  isControlMessage,\n} from \"@electric-sql/client\"\nimport { Store } from \"@tanstack/store\"\nimport DebugModule from \"debug\"\nimport {\n  ElectricDeleteHandlerMustReturnTxIdError,\n  ElectricInsertHandlerMustReturnTxIdError,\n  ElectricUpdateHandlerMustReturnTxIdError,\n  ExpectedNumberInAwaitTxIdError,\n  TimeoutWaitingForTxIdError,\n} from \"./errors\"\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  Fn,\n  InsertMutationFnParams,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"@tanstack/db\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type {\n  ControlMessage,\n  GetExtensions,\n  Message,\n  Row,\n  ShapeStreamOptions,\n} from \"@electric-sql/client\"\n\nconst debug = DebugModule.debug(`ts/db:electric`)\n\n/**\n * Type representing a transaction ID in ElectricSQL\n */\nexport type Txid = number\n\n// The `InferSchemaOutput` and `ResolveType` are copied from the `@tanstack/db` package\n// but we modified `InferSchemaOutput` slightly to restrict the schema output to `Row<unknown>`\n// This is needed in order for `GetExtensions` to be able to infer the parser extensions type from the schema\ntype InferSchemaOutput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferOutput<T> extends Row<unknown>\n    ? StandardSchemaV1.InferOutput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\n/**\n * Configuration interface for Electric collection options\n * @template T - The type of items in the collection\n * @template TSchema - The schema type for validation\n */\nexport interface ElectricCollectionConfig<\n  T extends Row<unknown> = Row<unknown>,\n  TSchema extends StandardSchemaV1 = never,\n> extends BaseCollectionConfig<\n    T,\n    string | number,\n    TSchema,\n    Record<string, Fn>,\n    { txid: Txid | Array<Txid> }\n  > {\n  /**\n   * Configuration options for the ElectricSQL ShapeStream\n   */\n  shapeOptions: ShapeStreamOptions<GetExtensions<T>>\n}\n\nfunction isUpToDateMessage<T extends Row<unknown>>(\n  message: Message<T>\n): message is ControlMessage & { up_to_date: true } {\n  return isControlMessage(message) && message.headers.control === `up-to-date`\n}\n\nfunction isMustRefetchMessage<T extends Row<unknown>>(\n  message: Message<T>\n): message is ControlMessage & { headers: { control: `must-refetch` } } {\n  return isControlMessage(message) && message.headers.control === `must-refetch`\n}\n\n// Check if a message contains txids in its headers\nfunction hasTxids<T extends Row<unknown>>(\n  message: Message<T>\n): message is Message<T> & { headers: { txids?: Array<Txid> } } {\n  return `txids` in message.headers && Array.isArray(message.headers.txids)\n}\n\n/**\n * Type for the awaitTxId utility function\n */\nexport type AwaitTxIdFn = (txId: Txid, timeout?: number) => Promise<boolean>\n\n/**\n * Electric collection utilities type\n */\nexport interface ElectricCollectionUtils extends UtilsRecord {\n  awaitTxId: AwaitTxIdFn\n}\n\n/**\n * Creates Electric collection options for use with a standard Collection\n *\n * @template T - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @param config - Configuration options for the Electric collection\n * @returns Collection options with utilities\n */\n\n// Overload for when schema is provided\nexport function electricCollectionOptions<T extends StandardSchemaV1>(\n  config: ElectricCollectionConfig<InferSchemaOutput<T>, T> & {\n    schema: T\n  }\n): CollectionConfig<InferSchemaOutput<T>, string | number, T> & {\n  id?: string\n  utils: ElectricCollectionUtils\n  schema: T\n}\n\n// Overload for when no schema is provided\nexport function electricCollectionOptions<T extends Row<unknown>>(\n  config: ElectricCollectionConfig<T> & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, string | number> & {\n  id?: string\n  utils: ElectricCollectionUtils\n  schema?: never // no schema in the result\n}\n\nexport function electricCollectionOptions(\n  config: ElectricCollectionConfig<any, any>\n): CollectionConfig<any, string | number, any> & {\n  id?: string\n  utils: ElectricCollectionUtils\n  schema?: any\n} {\n  const seenTxids = new Store<Set<Txid>>(new Set([]))\n  const sync = createElectricSync<any>(config.shapeOptions, {\n    seenTxids,\n  })\n\n  /**\n   * Wait for a specific transaction ID to be synced\n   * @param txId The transaction ID to wait for as a number\n   * @param timeout Optional timeout in milliseconds (defaults to 30000ms)\n   * @returns Promise that resolves when the txId is synced\n   */\n  const awaitTxId: AwaitTxIdFn = async (\n    txId: Txid,\n    timeout: number = 30000\n  ): Promise<boolean> => {\n    debug(`awaitTxId called with txid %d`, txId)\n    if (typeof txId !== `number`) {\n      throw new ExpectedNumberInAwaitTxIdError(typeof txId)\n    }\n\n    const hasTxid = seenTxids.state.has(txId)\n    if (hasTxid) return true\n\n    return new Promise((resolve, reject) => {\n      const timeoutId = setTimeout(() => {\n        unsubscribe()\n        reject(new TimeoutWaitingForTxIdError(txId))\n      }, timeout)\n\n      const unsubscribe = seenTxids.subscribe(() => {\n        if (seenTxids.state.has(txId)) {\n          debug(`awaitTxId found match for txid %o`, txId)\n          clearTimeout(timeoutId)\n          unsubscribe()\n          resolve(true)\n        }\n      })\n    })\n  }\n\n  // Create wrapper handlers for direct persistence operations that handle txid awaiting\n  const wrappedOnInsert = config.onInsert\n    ? async (params: InsertMutationFnParams<any>) => {\n        // Runtime check (that doesn't follow type)\n\n        const handlerResult = (await config.onInsert!(params)) ?? {}\n        const txid = (handlerResult as { txid?: Txid | Array<Txid> }).txid\n\n        if (!txid) {\n          throw new ElectricInsertHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(txid)) {\n          await Promise.all(txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnUpdate = config.onUpdate\n    ? async (params: UpdateMutationFnParams<any>) => {\n        // Runtime check (that doesn't follow type)\n\n        const handlerResult = (await config.onUpdate!(params)) ?? {}\n        const txid = (handlerResult as { txid?: Txid | Array<Txid> }).txid\n\n        if (!txid) {\n          throw new ElectricUpdateHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(txid)) {\n          await Promise.all(txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnDelete = config.onDelete\n    ? async (params: DeleteMutationFnParams<any>) => {\n        const handlerResult = await config.onDelete!(params)\n        if (!handlerResult.txid) {\n          throw new ElectricDeleteHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(handlerResult.txid)) {\n          await Promise.all(handlerResult.txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(handlerResult.txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  // Extract standard Collection config properties\n  const {\n    shapeOptions: _shapeOptions,\n    onInsert: _onInsert,\n    onUpdate: _onUpdate,\n    onDelete: _onDelete,\n    ...restConfig\n  } = config\n\n  return {\n    ...restConfig,\n    sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      awaitTxId,\n    },\n  }\n}\n\n/**\n * Internal function to create ElectricSQL sync configuration\n */\nfunction createElectricSync<T extends Row<unknown>>(\n  shapeOptions: ShapeStreamOptions<GetExtensions<T>>,\n  options: {\n    seenTxids: Store<Set<Txid>>\n  }\n): SyncConfig<T> {\n  const { seenTxids } = options\n\n  // Store for the relation schema information\n  const relationSchema = new Store<string | undefined>(undefined)\n\n  /**\n   * Get the sync metadata for insert operations\n   * @returns Record containing relation information\n   */\n  const getSyncMetadata = (): Record<string, unknown> => {\n    // Use the stored schema if available, otherwise default to 'public'\n    const schema = relationSchema.state || `public`\n\n    return {\n      relation: shapeOptions.params?.table\n        ? [schema, shapeOptions.params.table]\n        : undefined,\n    }\n  }\n\n  let unsubscribeStream: () => void\n\n  return {\n    sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {\n      const { begin, write, commit, markReady, truncate, collection } = params\n\n      // Abort controller for the stream - wraps the signal if provided\n      const abortController = new AbortController()\n\n      if (shapeOptions.signal) {\n        shapeOptions.signal.addEventListener(\n          `abort`,\n          () => {\n            abortController.abort()\n          },\n          {\n            once: true,\n          }\n        )\n        if (shapeOptions.signal.aborted) {\n          abortController.abort()\n        }\n      }\n\n      const stream = new ShapeStream({\n        ...shapeOptions,\n        signal: abortController.signal,\n        onError: (errorParams) => {\n          // Just immediately mark ready if there's an error to avoid blocking\n          // apps waiting for `.preload()` to finish.\n          // Note that Electric sends a 409 error on a `must-refetch` message, but the\n          // ShapeStream handled this and it will not reach this handler, therefor\n          // this markReady will not be triggers by a `must-refetch`.\n          markReady()\n\n          if (shapeOptions.onError) {\n            return shapeOptions.onError(errorParams)\n          } else {\n            console.error(\n              `An error occurred while syncing collection: ${collection.id}, \\n` +\n                `it has been marked as ready to avoid blocking apps waiting for '.preload()' to finish. \\n` +\n                `You can provide an 'onError' handler on the shapeOptions to handle this error, and this message will not be logged.`,\n              errorParams\n            )\n          }\n\n          return\n        },\n      })\n      let transactionStarted = false\n      const newTxids = new Set<Txid>()\n\n      unsubscribeStream = stream.subscribe((messages: Array<Message<T>>) => {\n        let hasUpToDate = false\n\n        for (const message of messages) {\n          // Check for txids in the message and add them to our store\n          if (hasTxids(message)) {\n            message.headers.txids?.forEach((txid) => newTxids.add(txid))\n          }\n\n          if (isChangeMessage(message)) {\n            // Check if the message contains schema information\n            const schema = message.headers.schema\n            if (schema && typeof schema === `string`) {\n              // Store the schema for future use if it's a valid string\n              relationSchema.setState(() => schema)\n            }\n\n            if (!transactionStarted) {\n              begin()\n              transactionStarted = true\n            }\n\n            write({\n              type: message.headers.operation,\n              value: message.value,\n              // Include the primary key and relation info in the metadata\n              metadata: {\n                ...message.headers,\n              },\n            })\n          } else if (isUpToDateMessage(message)) {\n            hasUpToDate = true\n          } else if (isMustRefetchMessage(message)) {\n            debug(\n              `Received must-refetch message, starting transaction with truncate`\n            )\n\n            // Start a transaction and truncate the collection\n            if (!transactionStarted) {\n              begin()\n              transactionStarted = true\n            }\n\n            truncate()\n\n            // Reset hasUpToDate so we continue accumulating changes until next up-to-date\n            hasUpToDate = false\n          }\n        }\n\n        if (hasUpToDate) {\n          // Commit transaction if one was started\n          if (transactionStarted) {\n            commit()\n            transactionStarted = false\n          }\n\n          // Mark the collection as ready now that sync is up to date\n          markReady()\n\n          // Always commit txids when we receive up-to-date, regardless of transaction state\n          seenTxids.setState((currentTxids) => {\n            const clonedSeen = new Set<Txid>(currentTxids)\n            if (newTxids.size > 0) {\n              debug(`new txids synced from pg %O`, Array.from(newTxids))\n            }\n            newTxids.forEach((txid) => clonedSeen.add(txid))\n            newTxids.clear()\n            return clonedSeen\n          })\n        }\n      })\n\n      // Return the unsubscribe function\n      return () => {\n        // Unsubscribe from the stream\n        unsubscribeStream()\n        // Abort the abort controller to stop the stream\n        abortController.abort()\n      }\n    },\n    // Expose the getSyncMetadata function\n    getSyncMetadata,\n  }\n}\n"],"names":["isControlMessage","Store","ExpectedNumberInAwaitTxIdError","TimeoutWaitingForTxIdError","ElectricInsertHandlerMustReturnTxIdError","ElectricUpdateHandlerMustReturnTxIdError","ElectricDeleteHandlerMustReturnTxIdError","ShapeStream","isChangeMessage"],"mappings":"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"}

package/dist/cjs/electric.d.cts

@@ -1,4 +1,4 @@
-import { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, SyncConfig, UpdateMutationFnParams, UtilsRecord } from '@tanstack/db';
+import { BaseCollectionConfig, CollectionConfig, Fn, UtilsRecord } from '@tanstack/db';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { GetExtensions, Row, ShapeStreamOptions } from '@electric-sql/client';
 /**
@@ -6,187 +6,18 @@ import { GetExtensions, Row, ShapeStreamOptions } from '@electric-sql/client';
  */
 export type Txid = number;
 type InferSchemaOutput<T> = T extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<T> extends Row<unknown> ? StandardSchemaV1.InferOutput<T> : Record<string, unknown> : Record<string, unknown>;
-type ResolveType<TExplicit extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never, TFallback extends object = Record<string, unknown>> = unknown extends GetExtensions<TExplicit> ? [TSchema] extends [never] ? TFallback : InferSchemaOutput<TSchema> : TExplicit;
 /**
  * Configuration interface for Electric collection options
- * @template TExplicit - The explicit type of items in the collection (highest priority)
- * @template TSchema - The schema type for validation and type inference (second priority)
- * @template TFallback - The fallback type if no explicit or schema type is provided
- *
- * @remarks
- * Type resolution follows a priority order:
- * 1. If you provide an explicit type via generic parameter, it will be used
- * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred
- * 3. If neither explicit type nor schema is provided, the fallback type will be used
- *
- * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.
+ * @template T - The type of items in the collection
+ * @template TSchema - The schema type for validation
  */
-export interface ElectricCollectionConfig<TExplicit extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never, TFallback extends Row<unknown> = Row<unknown>> {
+export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never> extends BaseCollectionConfig<T, string | number, TSchema, Record<string, Fn>, {
+    txid: Txid | Array<Txid>;
+}> {
     /**
      * Configuration options for the ElectricSQL ShapeStream
      */
-    shapeOptions: ShapeStreamOptions<GetExtensions<ResolveType<TExplicit, TSchema, TFallback>>>;
-    /**
-     * All standard Collection configuration properties
-     */
-    id?: string;
-    schema?: TSchema;
-    getKey: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`getKey`];
-    sync?: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`sync`];
-    /**
-     * Optional asynchronous handler function called before an insert operation
-     * Must return an object containing a txid number or array of txids
-     * @param params Object containing transaction and collection information
-     * @returns Promise resolving to an object with txid or txids
-     * @example
-     * // Basic Electric insert handler - MUST return { txid: number }
-     * onInsert: async ({ transaction }) => {
-     *   const newItem = transaction.mutations[0].modified
-     *   const result = await api.todos.create({
-     *     data: newItem
-     *   })
-     *   return { txid: result.txid } // Required for Electric sync matching
-     * }
-     *
-     * @example
-     * // Insert handler with multiple items - return array of txids
-     * onInsert: async ({ transaction }) => {
-     *   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) } // Array of txids
-     * }
-     *
-     * @example
-     * // Insert handler with error handling
-     * onInsert: async ({ transaction }) => {
-     *   try {
-     *     const newItem = transaction.mutations[0].modified
-     *     const result = await api.createTodo(newItem)
-     *     return { txid: result.txid }
-     *   } catch (error) {
-     *     console.error('Insert failed:', error)
-     *     throw error // This will cause the transaction to fail
-     *   }
-     * }
-     *
-     * @example
-     * // Insert handler with batch operation - single txid
-     * onInsert: async ({ transaction }) => {
-     *   const items = transaction.mutations.map(m => m.modified)
-     *   const result = await api.todos.createMany({
-     *     data: items
-     *   })
-     *   return { txid: result.txid } // Single txid for batch operation
-     * }
-     */
-    onInsert?: (params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>;
-    /**
-     * Optional asynchronous handler function called before an update operation
-     * Must return an object containing a txid number or array of txids
-     * @param params Object containing transaction and collection information
-     * @returns Promise resolving to an object with txid or txids
-     * @example
-     * // Basic Electric update handler - MUST return { txid: number }
-     * onUpdate: async ({ transaction }) => {
-     *   const { original, changes } = transaction.mutations[0]
-     *   const result = await api.todos.update({
-     *     where: { id: original.id },
-     *     data: changes // Only the changed fields
-     *   })
-     *   return { txid: result.txid } // Required for Electric sync matching
-     * }
-     *
-     * @example
-     * // Update handler with multiple items - return array of txids
-     * onUpdate: async ({ transaction }) => {
-     *   const updates = await Promise.all(
-     *     transaction.mutations.map(m =>
-     *       api.todos.update({
-     *         where: { id: m.original.id },
-     *         data: m.changes
-     *       })
-     *     )
-     *   )
-     *   return { txid: updates.map(u => u.txid) } // Array of txids
-     * }
-     *
-     * @example
-     * // Update handler with optimistic rollback
-     * onUpdate: async ({ transaction }) => {
-     *   const mutation = transaction.mutations[0]
-     *   try {
-     *     const result = await api.updateTodo(mutation.original.id, mutation.changes)
-     *     return { txid: result.txid }
-     *   } catch (error) {
-     *     // Transaction will automatically rollback optimistic changes
-     *     console.error('Update failed, rolling back:', error)
-     *     throw error
-     *   }
-     * }
-     */
-    onUpdate?: (params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>;
-    /**
-     * Optional asynchronous handler function called before a delete operation
-     * Must return an object containing a txid number or array of txids
-     * @param params Object containing transaction and collection information
-     * @returns Promise resolving to an object with txid or txids
-     * @example
-     * // Basic Electric delete handler - MUST return { txid: number }
-     * onDelete: async ({ transaction }) => {
-     *   const mutation = transaction.mutations[0]
-     *   const result = await api.todos.delete({
-     *     id: mutation.original.id
-     *   })
-     *   return { txid: result.txid } // Required for Electric sync matching
-     * }
-     *
-     * @example
-     * // Delete handler with multiple items - return array of txids
-     * onDelete: async ({ transaction }) => {
-     *   const deletes = await Promise.all(
-     *     transaction.mutations.map(m =>
-     *       api.todos.delete({
-     *         where: { id: m.key }
-     *       })
-     *     )
-     *   )
-     *   return { txid: deletes.map(d => d.txid) } // Array of txids
-     * }
-     *
-     * @example
-     * // Delete handler with batch operation - single txid
-     * onDelete: async ({ transaction }) => {
-     *   const idsToDelete = transaction.mutations.map(m => m.original.id)
-     *   const result = await api.todos.deleteMany({
-     *     ids: idsToDelete
-     *   })
-     *   return { txid: result.txid } // Single txid for batch operation
-     * }
-     *
-     * @example
-     * // Delete handler with optimistic rollback
-     * onDelete: async ({ transaction }) => {
-     *   const mutation = transaction.mutations[0]
-     *   try {
-     *     const result = await api.deleteTodo(mutation.original.id)
-     *     return { txid: result.txid }
-     *   } catch (error) {
-     *     // Transaction will automatically rollback optimistic changes
-     *     console.error('Delete failed, rolling back:', error)
-     *     throw error
-     *   }
-     * }
-     *
-     */
-    onDelete?: (params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>;
+    shapeOptions: ShapeStreamOptions<GetExtensions<T>>;
 }
 /**
  * Type for the awaitTxId utility function
@@ -201,31 +32,24 @@ export interface ElectricCollectionUtils extends UtilsRecord {
 /**
  * Creates Electric collection options for use with a standard Collection
  *
- * @template TExplicit - The explicit type of items in the collection (highest priority)
+ * @template T - The explicit type of items in the collection (highest priority)
  * @template TSchema - The schema type for validation and type inference (second priority)
  * @template TFallback - The fallback type if no explicit or schema type is provided
  * @param config - Configuration options for the Electric collection
  * @returns Collection options with utilities
  */
-export declare function electricCollectionOptions<TExplicit extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never, TFallback extends Row<unknown> = Row<unknown>>(config: ElectricCollectionConfig<TExplicit, TSchema, TFallback>): {
-    sync: SyncConfig<ResolveType<TExplicit, TSchema, TFallback>, string | number>;
-    onInsert: ((params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>) | undefined;
-    onUpdate: ((params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>) | undefined;
-    onDelete: ((params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>) | undefined;
-    utils: {
-        awaitTxId: AwaitTxIdFn;
-    };
-    /**
-     * All standard Collection configuration properties
-     */
+export declare function electricCollectionOptions<T extends StandardSchemaV1>(config: ElectricCollectionConfig<InferSchemaOutput<T>, T> & {
+    schema: T;
+}): CollectionConfig<InferSchemaOutput<T>, string | number, T> & {
+    id?: string;
+    utils: ElectricCollectionUtils;
+    schema: T;
+};
+export declare function electricCollectionOptions<T extends Row<unknown>>(config: ElectricCollectionConfig<T> & {
+    schema?: never;
+}): CollectionConfig<T, string | number> & {
     id?: string;
-    schema?: TSchema | undefined;
-    getKey: (item: ResolveType<TExplicit, TSchema, TFallback>) => string | number;
+    utils: ElectricCollectionUtils;
+    schema?: never;
 };
 export {};

package/dist/esm/electric.d.ts

@@ -1,4 +1,4 @@
-import { CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, SyncConfig, UpdateMutationFnParams, UtilsRecord } from '@tanstack/db';
+import { BaseCollectionConfig, CollectionConfig, Fn, UtilsRecord } from '@tanstack/db';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { GetExtensions, Row, ShapeStreamOptions } from '@electric-sql/client';
 /**
@@ -6,187 +6,18 @@ import { GetExtensions, Row, ShapeStreamOptions } from '@electric-sql/client';
  */
 export type Txid = number;
 type InferSchemaOutput<T> = T extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<T> extends Row<unknown> ? StandardSchemaV1.InferOutput<T> : Record<string, unknown> : Record<string, unknown>;
-type ResolveType<TExplicit extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never, TFallback extends object = Record<string, unknown>> = unknown extends GetExtensions<TExplicit> ? [TSchema] extends [never] ? TFallback : InferSchemaOutput<TSchema> : TExplicit;
 /**
  * Configuration interface for Electric collection options
- * @template TExplicit - The explicit type of items in the collection (highest priority)
- * @template TSchema - The schema type for validation and type inference (second priority)
- * @template TFallback - The fallback type if no explicit or schema type is provided
- *
- * @remarks
- * Type resolution follows a priority order:
- * 1. If you provide an explicit type via generic parameter, it will be used
- * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred
- * 3. If neither explicit type nor schema is provided, the fallback type will be used
- *
- * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.
+ * @template T - The type of items in the collection
+ * @template TSchema - The schema type for validation
  */
-export interface ElectricCollectionConfig<TExplicit extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never, TFallback extends Row<unknown> = Row<unknown>> {
+export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never> extends BaseCollectionConfig<T, string | number, TSchema, Record<string, Fn>, {
+    txid: Txid | Array<Txid>;
+}> {
     /**
      * Configuration options for the ElectricSQL ShapeStream
      */
-    shapeOptions: ShapeStreamOptions<GetExtensions<ResolveType<TExplicit, TSchema, TFallback>>>;
-    /**
-     * All standard Collection configuration properties
-     */
-    id?: string;
-    schema?: TSchema;
-    getKey: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`getKey`];
-    sync?: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`sync`];
-    /**
-     * Optional asynchronous handler function called before an insert operation
-     * Must return an object containing a txid number or array of txids
-     * @param params Object containing transaction and collection information
-     * @returns Promise resolving to an object with txid or txids
-     * @example
-     * // Basic Electric insert handler - MUST return { txid: number }
-     * onInsert: async ({ transaction }) => {
-     *   const newItem = transaction.mutations[0].modified
-     *   const result = await api.todos.create({
-     *     data: newItem
-     *   })
-     *   return { txid: result.txid } // Required for Electric sync matching
-     * }
-     *
-     * @example
-     * // Insert handler with multiple items - return array of txids
-     * onInsert: async ({ transaction }) => {
-     *   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) } // Array of txids
-     * }
-     *
-     * @example
-     * // Insert handler with error handling
-     * onInsert: async ({ transaction }) => {
-     *   try {
-     *     const newItem = transaction.mutations[0].modified
-     *     const result = await api.createTodo(newItem)
-     *     return { txid: result.txid }
-     *   } catch (error) {
-     *     console.error('Insert failed:', error)
-     *     throw error // This will cause the transaction to fail
-     *   }
-     * }
-     *
-     * @example
-     * // Insert handler with batch operation - single txid
-     * onInsert: async ({ transaction }) => {
-     *   const items = transaction.mutations.map(m => m.modified)
-     *   const result = await api.todos.createMany({
-     *     data: items
-     *   })
-     *   return { txid: result.txid } // Single txid for batch operation
-     * }
-     */
-    onInsert?: (params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>;
-    /**
-     * Optional asynchronous handler function called before an update operation
-     * Must return an object containing a txid number or array of txids
-     * @param params Object containing transaction and collection information
-     * @returns Promise resolving to an object with txid or txids
-     * @example
-     * // Basic Electric update handler - MUST return { txid: number }
-     * onUpdate: async ({ transaction }) => {
-     *   const { original, changes } = transaction.mutations[0]
-     *   const result = await api.todos.update({
-     *     where: { id: original.id },
-     *     data: changes // Only the changed fields
-     *   })
-     *   return { txid: result.txid } // Required for Electric sync matching
-     * }
-     *
-     * @example
-     * // Update handler with multiple items - return array of txids
-     * onUpdate: async ({ transaction }) => {
-     *   const updates = await Promise.all(
-     *     transaction.mutations.map(m =>
-     *       api.todos.update({
-     *         where: { id: m.original.id },
-     *         data: m.changes
-     *       })
-     *     )
-     *   )
-     *   return { txid: updates.map(u => u.txid) } // Array of txids
-     * }
-     *
-     * @example
-     * // Update handler with optimistic rollback
-     * onUpdate: async ({ transaction }) => {
-     *   const mutation = transaction.mutations[0]
-     *   try {
-     *     const result = await api.updateTodo(mutation.original.id, mutation.changes)
-     *     return { txid: result.txid }
-     *   } catch (error) {
-     *     // Transaction will automatically rollback optimistic changes
-     *     console.error('Update failed, rolling back:', error)
-     *     throw error
-     *   }
-     * }
-     */
-    onUpdate?: (params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>;
-    /**
-     * Optional asynchronous handler function called before a delete operation
-     * Must return an object containing a txid number or array of txids
-     * @param params Object containing transaction and collection information
-     * @returns Promise resolving to an object with txid or txids
-     * @example
-     * // Basic Electric delete handler - MUST return { txid: number }
-     * onDelete: async ({ transaction }) => {
-     *   const mutation = transaction.mutations[0]
-     *   const result = await api.todos.delete({
-     *     id: mutation.original.id
-     *   })
-     *   return { txid: result.txid } // Required for Electric sync matching
-     * }
-     *
-     * @example
-     * // Delete handler with multiple items - return array of txids
-     * onDelete: async ({ transaction }) => {
-     *   const deletes = await Promise.all(
-     *     transaction.mutations.map(m =>
-     *       api.todos.delete({
-     *         where: { id: m.key }
-     *       })
-     *     )
-     *   )
-     *   return { txid: deletes.map(d => d.txid) } // Array of txids
-     * }
-     *
-     * @example
-     * // Delete handler with batch operation - single txid
-     * onDelete: async ({ transaction }) => {
-     *   const idsToDelete = transaction.mutations.map(m => m.original.id)
-     *   const result = await api.todos.deleteMany({
-     *     ids: idsToDelete
-     *   })
-     *   return { txid: result.txid } // Single txid for batch operation
-     * }
-     *
-     * @example
-     * // Delete handler with optimistic rollback
-     * onDelete: async ({ transaction }) => {
-     *   const mutation = transaction.mutations[0]
-     *   try {
-     *     const result = await api.deleteTodo(mutation.original.id)
-     *     return { txid: result.txid }
-     *   } catch (error) {
-     *     // Transaction will automatically rollback optimistic changes
-     *     console.error('Delete failed, rolling back:', error)
-     *     throw error
-     *   }
-     * }
-     *
-     */
-    onDelete?: (params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>;
+    shapeOptions: ShapeStreamOptions<GetExtensions<T>>;
 }
 /**
  * Type for the awaitTxId utility function
@@ -201,31 +32,24 @@ export interface ElectricCollectionUtils extends UtilsRecord {
 /**
  * Creates Electric collection options for use with a standard Collection
  *
- * @template TExplicit - The explicit type of items in the collection (highest priority)
+ * @template T - The explicit type of items in the collection (highest priority)
  * @template TSchema - The schema type for validation and type inference (second priority)
  * @template TFallback - The fallback type if no explicit or schema type is provided
  * @param config - Configuration options for the Electric collection
  * @returns Collection options with utilities
  */
-export declare function electricCollectionOptions<TExplicit extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never, TFallback extends Row<unknown> = Row<unknown>>(config: ElectricCollectionConfig<TExplicit, TSchema, TFallback>): {
-    sync: SyncConfig<ResolveType<TExplicit, TSchema, TFallback>, string | number>;
-    onInsert: ((params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>) | undefined;
-    onUpdate: ((params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>) | undefined;
-    onDelete: ((params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>) => Promise<{
-        txid: Txid | Array<Txid>;
-    }>) | undefined;
-    utils: {
-        awaitTxId: AwaitTxIdFn;
-    };
-    /**
-     * All standard Collection configuration properties
-     */
+export declare function electricCollectionOptions<T extends StandardSchemaV1>(config: ElectricCollectionConfig<InferSchemaOutput<T>, T> & {
+    schema: T;
+}): CollectionConfig<InferSchemaOutput<T>, string | number, T> & {
+    id?: string;
+    utils: ElectricCollectionUtils;
+    schema: T;
+};
+export declare function electricCollectionOptions<T extends Row<unknown>>(config: ElectricCollectionConfig<T> & {
+    schema?: never;
+}): CollectionConfig<T, string | number> & {
     id?: string;
-    schema?: TSchema | undefined;
-    getKey: (item: ResolveType<TExplicit, TSchema, TFallback>) => string | number;
+    utils: ElectricCollectionUtils;
+    schema?: never;
 };
 export {};

package/dist/esm/electric.js

@@ -14,12 +14,9 @@ function hasTxids(message) {
 }
 function electricCollectionOptions(config) {
   const seenTxids = new Store(/* @__PURE__ */ new Set([]));
-  const sync = createElectricSync(
-    config.shapeOptions,
-    {
-      seenTxids
-    }
-  );
+  const sync = createElectricSync(config.shapeOptions, {
+    seenTxids
+  });
   const awaitTxId = async (txId, timeout = 3e4) => {
     debug(`awaitTxId called with txid %d`, txId);
     if (typeof txId !== `number`) {

package/dist/esm/electric.js.map

@@ -1 +1 @@
-{"version":3,"file":"electric.js","sources":["../../src/electric.ts"],"sourcesContent":["import {\n  ShapeStream,\n  isChangeMessage,\n  isControlMessage,\n} from \"@electric-sql/client\"\nimport { Store } from \"@tanstack/store\"\nimport DebugModule from \"debug\"\nimport {\n  ElectricDeleteHandlerMustReturnTxIdError,\n  ElectricInsertHandlerMustReturnTxIdError,\n  ElectricUpdateHandlerMustReturnTxIdError,\n  ExpectedNumberInAwaitTxIdError,\n  TimeoutWaitingForTxIdError,\n} from \"./errors\"\nimport type {\n  CollectionConfig,\n  DeleteMutationFnParams,\n  InsertMutationFnParams,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"@tanstack/db\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type {\n  ControlMessage,\n  GetExtensions,\n  Message,\n  Row,\n  ShapeStreamOptions,\n} from \"@electric-sql/client\"\n\nconst debug = DebugModule.debug(`ts/db:electric`)\n\n/**\n * Type representing a transaction ID in ElectricSQL\n */\nexport type Txid = number\n\n// The `InferSchemaOutput` and `ResolveType` are copied from the `@tanstack/db` package\n// but we modified `InferSchemaOutput` slightly to restrict the schema output to `Row<unknown>`\n// This is needed in order for `GetExtensions` to be able to infer the parser extensions type from the schema\ntype InferSchemaOutput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferOutput<T> extends Row<unknown>\n    ? StandardSchemaV1.InferOutput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\ntype ResolveType<\n  TExplicit extends Row<unknown> = Row<unknown>,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends object = Record<string, unknown>,\n> =\n  unknown extends GetExtensions<TExplicit>\n    ? [TSchema] extends [never]\n      ? TFallback\n      : InferSchemaOutput<TSchema>\n    : TExplicit\n\n/**\n * Configuration interface for Electric collection options\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n *\n * @remarks\n * Type resolution follows a priority order:\n * 1. If you provide an explicit type via generic parameter, it will be used\n * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred\n * 3. If neither explicit type nor schema is provided, the fallback type will be used\n *\n * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.\n */\nexport interface ElectricCollectionConfig<\n  TExplicit extends Row<unknown> = Row<unknown>,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends Row<unknown> = Row<unknown>,\n> {\n  /**\n   * Configuration options for the ElectricSQL ShapeStream\n   */\n  shapeOptions: ShapeStreamOptions<\n    GetExtensions<ResolveType<TExplicit, TSchema, TFallback>>\n  >\n\n  /**\n   * All standard Collection configuration properties\n   */\n  id?: string\n  schema?: TSchema\n  getKey: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`getKey`]\n  sync?: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`sync`]\n\n  /**\n   * Optional asynchronous handler function called before an insert operation\n   * Must return an object containing a txid number or array of txids\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to an object with txid or txids\n   * @example\n   * // Basic Electric insert handler - MUST return { txid: number }\n   * onInsert: async ({ transaction }) => {\n   *   const newItem = transaction.mutations[0].modified\n   *   const result = await api.todos.create({\n   *     data: newItem\n   *   })\n   *   return { txid: result.txid } // Required for Electric sync matching\n   * }\n   *\n   * @example\n   * // Insert handler with multiple items - return array of txids\n   * onInsert: async ({ transaction }) => {\n   *   const items = transaction.mutations.map(m => m.modified)\n   *   const results = await Promise.all(\n   *     items.map(item => api.todos.create({ data: item }))\n   *   )\n   *   return { txid: results.map(r => r.txid) } // Array of txids\n   * }\n   *\n   * @example\n   * // Insert handler with error handling\n   * onInsert: async ({ transaction }) => {\n   *   try {\n   *     const newItem = transaction.mutations[0].modified\n   *     const result = await api.createTodo(newItem)\n   *     return { txid: result.txid }\n   *   } catch (error) {\n   *     console.error('Insert failed:', error)\n   *     throw error // This will cause the transaction to fail\n   *   }\n   * }\n   *\n   * @example\n   * // Insert handler with batch operation - single txid\n   * onInsert: async ({ transaction }) => {\n   *   const items = transaction.mutations.map(m => m.modified)\n   *   const result = await api.todos.createMany({\n   *     data: items\n   *   })\n   *   return { txid: result.txid } // Single txid for batch operation\n   * }\n   */\n  onInsert?: (\n    params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<{ txid: Txid | Array<Txid> }>\n\n  /**\n   * Optional asynchronous handler function called before an update operation\n   * Must return an object containing a txid number or array of txids\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to an object with txid or txids\n   * @example\n   * // Basic Electric update handler - MUST return { txid: number }\n   * onUpdate: async ({ transaction }) => {\n   *   const { original, changes } = transaction.mutations[0]\n   *   const result = await api.todos.update({\n   *     where: { id: original.id },\n   *     data: changes // Only the changed fields\n   *   })\n   *   return { txid: result.txid } // Required for Electric sync matching\n   * }\n   *\n   * @example\n   * // Update handler with multiple items - return array of txids\n   * onUpdate: async ({ transaction }) => {\n   *   const updates = await Promise.all(\n   *     transaction.mutations.map(m =>\n   *       api.todos.update({\n   *         where: { id: m.original.id },\n   *         data: m.changes\n   *       })\n   *     )\n   *   )\n   *   return { txid: updates.map(u => u.txid) } // Array of txids\n   * }\n   *\n   * @example\n   * // Update handler with optimistic rollback\n   * onUpdate: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   try {\n   *     const result = await api.updateTodo(mutation.original.id, mutation.changes)\n   *     return { txid: result.txid }\n   *   } catch (error) {\n   *     // Transaction will automatically rollback optimistic changes\n   *     console.error('Update failed, rolling back:', error)\n   *     throw error\n   *   }\n   * }\n   */\n  onUpdate?: (\n    params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<{ txid: Txid | Array<Txid> }>\n\n  /**\n   * Optional asynchronous handler function called before a delete operation\n   * Must return an object containing a txid number or array of txids\n   * @param params Object containing transaction and collection information\n   * @returns Promise resolving to an object with txid or txids\n   * @example\n   * // Basic Electric delete handler - MUST return { txid: number }\n   * onDelete: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   const result = await api.todos.delete({\n   *     id: mutation.original.id\n   *   })\n   *   return { txid: result.txid } // Required for Electric sync matching\n   * }\n   *\n   * @example\n   * // Delete handler with multiple items - return array of txids\n   * onDelete: async ({ transaction }) => {\n   *   const deletes = await Promise.all(\n   *     transaction.mutations.map(m =>\n   *       api.todos.delete({\n   *         where: { id: m.key }\n   *       })\n   *     )\n   *   )\n   *   return { txid: deletes.map(d => d.txid) } // Array of txids\n   * }\n   *\n   * @example\n   * // Delete handler with batch operation - single txid\n   * onDelete: async ({ transaction }) => {\n   *   const idsToDelete = transaction.mutations.map(m => m.original.id)\n   *   const result = await api.todos.deleteMany({\n   *     ids: idsToDelete\n   *   })\n   *   return { txid: result.txid } // Single txid for batch operation\n   * }\n   *\n   * @example\n   * // Delete handler with optimistic rollback\n   * onDelete: async ({ transaction }) => {\n   *   const mutation = transaction.mutations[0]\n   *   try {\n   *     const result = await api.deleteTodo(mutation.original.id)\n   *     return { txid: result.txid }\n   *   } catch (error) {\n   *     // Transaction will automatically rollback optimistic changes\n   *     console.error('Delete failed, rolling back:', error)\n   *     throw error\n   *   }\n   * }\n   *\n   */\n  onDelete?: (\n    params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>\n  ) => Promise<{ txid: Txid | Array<Txid> }>\n}\n\nfunction isUpToDateMessage<T extends Row<unknown>>(\n  message: Message<T>\n): message is ControlMessage & { up_to_date: true } {\n  return isControlMessage(message) && message.headers.control === `up-to-date`\n}\n\nfunction isMustRefetchMessage<T extends Row<unknown>>(\n  message: Message<T>\n): message is ControlMessage & { headers: { control: `must-refetch` } } {\n  return isControlMessage(message) && message.headers.control === `must-refetch`\n}\n\n// Check if a message contains txids in its headers\nfunction hasTxids<T extends Row<unknown>>(\n  message: Message<T>\n): message is Message<T> & { headers: { txids?: Array<Txid> } } {\n  return `txids` in message.headers && Array.isArray(message.headers.txids)\n}\n\n/**\n * Type for the awaitTxId utility function\n */\nexport type AwaitTxIdFn = (txId: Txid, timeout?: number) => Promise<boolean>\n\n/**\n * Electric collection utilities type\n */\nexport interface ElectricCollectionUtils extends UtilsRecord {\n  awaitTxId: AwaitTxIdFn\n}\n\n/**\n * Creates Electric collection options for use with a standard Collection\n *\n * @template TExplicit - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @param config - Configuration options for the Electric collection\n * @returns Collection options with utilities\n */\nexport function electricCollectionOptions<\n  TExplicit extends Row<unknown> = Row<unknown>,\n  TSchema extends StandardSchemaV1 = never,\n  TFallback extends Row<unknown> = Row<unknown>,\n>(config: ElectricCollectionConfig<TExplicit, TSchema, TFallback>) {\n  const seenTxids = new Store<Set<Txid>>(new Set([]))\n  const sync = createElectricSync<ResolveType<TExplicit, TSchema, TFallback>>(\n    config.shapeOptions,\n    {\n      seenTxids,\n    }\n  )\n\n  /**\n   * Wait for a specific transaction ID to be synced\n   * @param txId The transaction ID to wait for as a number\n   * @param timeout Optional timeout in milliseconds (defaults to 30000ms)\n   * @returns Promise that resolves when the txId is synced\n   */\n  const awaitTxId: AwaitTxIdFn = async (\n    txId: Txid,\n    timeout: number = 30000\n  ): Promise<boolean> => {\n    debug(`awaitTxId called with txid %d`, txId)\n    if (typeof txId !== `number`) {\n      throw new ExpectedNumberInAwaitTxIdError(typeof txId)\n    }\n\n    const hasTxid = seenTxids.state.has(txId)\n    if (hasTxid) return true\n\n    return new Promise((resolve, reject) => {\n      const timeoutId = setTimeout(() => {\n        unsubscribe()\n        reject(new TimeoutWaitingForTxIdError(txId))\n      }, timeout)\n\n      const unsubscribe = seenTxids.subscribe(() => {\n        if (seenTxids.state.has(txId)) {\n          debug(`awaitTxId found match for txid %o`, txId)\n          clearTimeout(timeoutId)\n          unsubscribe()\n          resolve(true)\n        }\n      })\n    })\n  }\n\n  // Create wrapper handlers for direct persistence operations that handle txid awaiting\n  const wrappedOnInsert = config.onInsert\n    ? async (\n        params: InsertMutationFnParams<\n          ResolveType<TExplicit, TSchema, TFallback>\n        >\n      ) => {\n        // Runtime check (that doesn't follow type)\n        // eslint-disable-next-line\n        const handlerResult = (await config.onInsert!(params)) ?? {}\n        const txid = (handlerResult as { txid?: Txid | Array<Txid> }).txid\n\n        if (!txid) {\n          throw new ElectricInsertHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(txid)) {\n          await Promise.all(txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnUpdate = config.onUpdate\n    ? async (\n        params: UpdateMutationFnParams<\n          ResolveType<TExplicit, TSchema, TFallback>\n        >\n      ) => {\n        // Runtime check (that doesn't follow type)\n        // eslint-disable-next-line\n        const handlerResult = (await config.onUpdate!(params)) ?? {}\n        const txid = (handlerResult as { txid?: Txid | Array<Txid> }).txid\n\n        if (!txid) {\n          throw new ElectricUpdateHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(txid)) {\n          await Promise.all(txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnDelete = config.onDelete\n    ? async (\n        params: DeleteMutationFnParams<\n          ResolveType<TExplicit, TSchema, TFallback>\n        >\n      ) => {\n        const handlerResult = await config.onDelete!(params)\n        if (!handlerResult.txid) {\n          throw new ElectricDeleteHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(handlerResult.txid)) {\n          await Promise.all(handlerResult.txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(handlerResult.txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  // Extract standard Collection config properties\n  const {\n    shapeOptions: _shapeOptions,\n    onInsert: _onInsert,\n    onUpdate: _onUpdate,\n    onDelete: _onDelete,\n    ...restConfig\n  } = config\n\n  return {\n    ...restConfig,\n    sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      awaitTxId,\n    },\n  }\n}\n\n/**\n * Internal function to create ElectricSQL sync configuration\n */\nfunction createElectricSync<T extends Row<unknown>>(\n  shapeOptions: ShapeStreamOptions<GetExtensions<T>>,\n  options: {\n    seenTxids: Store<Set<Txid>>\n  }\n): SyncConfig<T> {\n  const { seenTxids } = options\n\n  // Store for the relation schema information\n  const relationSchema = new Store<string | undefined>(undefined)\n\n  /**\n   * Get the sync metadata for insert operations\n   * @returns Record containing relation information\n   */\n  const getSyncMetadata = (): Record<string, unknown> => {\n    // Use the stored schema if available, otherwise default to 'public'\n    const schema = relationSchema.state || `public`\n\n    return {\n      relation: shapeOptions.params?.table\n        ? [schema, shapeOptions.params.table]\n        : undefined,\n    }\n  }\n\n  let unsubscribeStream: () => void\n\n  return {\n    sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {\n      const { begin, write, commit, markReady, truncate, collection } = params\n\n      // Abort controller for the stream - wraps the signal if provided\n      const abortController = new AbortController()\n\n      if (shapeOptions.signal) {\n        shapeOptions.signal.addEventListener(\n          `abort`,\n          () => {\n            abortController.abort()\n          },\n          {\n            once: true,\n          }\n        )\n        if (shapeOptions.signal.aborted) {\n          abortController.abort()\n        }\n      }\n\n      const stream = new ShapeStream({\n        ...shapeOptions,\n        signal: abortController.signal,\n        onError: (errorParams) => {\n          // Just immediately mark ready if there's an error to avoid blocking\n          // apps waiting for `.preload()` to finish.\n          // Note that Electric sends a 409 error on a `must-refetch` message, but the\n          // ShapeStream handled this and it will not reach this handler, therefor\n          // this markReady will not be triggers by a `must-refetch`.\n          markReady()\n\n          if (shapeOptions.onError) {\n            return shapeOptions.onError(errorParams)\n          } else {\n            console.error(\n              `An error occurred while syncing collection: ${collection.id}, \\n` +\n                `it has been marked as ready to avoid blocking apps waiting for '.preload()' to finish. \\n` +\n                `You can provide an 'onError' handler on the shapeOptions to handle this error, and this message will not be logged.`,\n              errorParams\n            )\n          }\n\n          return\n        },\n      })\n      let transactionStarted = false\n      const newTxids = new Set<Txid>()\n\n      unsubscribeStream = stream.subscribe((messages: Array<Message<T>>) => {\n        let hasUpToDate = false\n\n        for (const message of messages) {\n          // Check for txids in the message and add them to our store\n          if (hasTxids(message)) {\n            message.headers.txids?.forEach((txid) => newTxids.add(txid))\n          }\n\n          if (isChangeMessage(message)) {\n            // Check if the message contains schema information\n            const schema = message.headers.schema\n            if (schema && typeof schema === `string`) {\n              // Store the schema for future use if it's a valid string\n              relationSchema.setState(() => schema)\n            }\n\n            if (!transactionStarted) {\n              begin()\n              transactionStarted = true\n            }\n\n            write({\n              type: message.headers.operation,\n              value: message.value,\n              // Include the primary key and relation info in the metadata\n              metadata: {\n                ...message.headers,\n              },\n            })\n          } else if (isUpToDateMessage(message)) {\n            hasUpToDate = true\n          } else if (isMustRefetchMessage(message)) {\n            debug(\n              `Received must-refetch message, starting transaction with truncate`\n            )\n\n            // Start a transaction and truncate the collection\n            if (!transactionStarted) {\n              begin()\n              transactionStarted = true\n            }\n\n            truncate()\n\n            // Reset hasUpToDate so we continue accumulating changes until next up-to-date\n            hasUpToDate = false\n          }\n        }\n\n        if (hasUpToDate) {\n          // Commit transaction if one was started\n          if (transactionStarted) {\n            commit()\n            transactionStarted = false\n          }\n\n          // Mark the collection as ready now that sync is up to date\n          markReady()\n\n          // Always commit txids when we receive up-to-date, regardless of transaction state\n          seenTxids.setState((currentTxids) => {\n            const clonedSeen = new Set<Txid>(currentTxids)\n            if (newTxids.size > 0) {\n              debug(`new txids synced from pg %O`, Array.from(newTxids))\n            }\n            newTxids.forEach((txid) => clonedSeen.add(txid))\n            newTxids.clear()\n            return clonedSeen\n          })\n        }\n      })\n\n      // Return the unsubscribe function\n      return () => {\n        // Unsubscribe from the stream\n        unsubscribeStream()\n        // Abort the abort controller to stop the stream\n        abortController.abort()\n      }\n    },\n    // Expose the getSyncMetadata function\n    getSyncMetadata,\n  }\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"electric.js","sources":["../../src/electric.ts"],"sourcesContent":["import {\n  ShapeStream,\n  isChangeMessage,\n  isControlMessage,\n} from \"@electric-sql/client\"\nimport { Store } from \"@tanstack/store\"\nimport DebugModule from \"debug\"\nimport {\n  ElectricDeleteHandlerMustReturnTxIdError,\n  ElectricInsertHandlerMustReturnTxIdError,\n  ElectricUpdateHandlerMustReturnTxIdError,\n  ExpectedNumberInAwaitTxIdError,\n  TimeoutWaitingForTxIdError,\n} from \"./errors\"\nimport type {\n  BaseCollectionConfig,\n  CollectionConfig,\n  DeleteMutationFnParams,\n  Fn,\n  InsertMutationFnParams,\n  SyncConfig,\n  UpdateMutationFnParams,\n  UtilsRecord,\n} from \"@tanstack/db\"\nimport type { StandardSchemaV1 } from \"@standard-schema/spec\"\nimport type {\n  ControlMessage,\n  GetExtensions,\n  Message,\n  Row,\n  ShapeStreamOptions,\n} from \"@electric-sql/client\"\n\nconst debug = DebugModule.debug(`ts/db:electric`)\n\n/**\n * Type representing a transaction ID in ElectricSQL\n */\nexport type Txid = number\n\n// The `InferSchemaOutput` and `ResolveType` are copied from the `@tanstack/db` package\n// but we modified `InferSchemaOutput` slightly to restrict the schema output to `Row<unknown>`\n// This is needed in order for `GetExtensions` to be able to infer the parser extensions type from the schema\ntype InferSchemaOutput<T> = T extends StandardSchemaV1\n  ? StandardSchemaV1.InferOutput<T> extends Row<unknown>\n    ? StandardSchemaV1.InferOutput<T>\n    : Record<string, unknown>\n  : Record<string, unknown>\n\n/**\n * Configuration interface for Electric collection options\n * @template T - The type of items in the collection\n * @template TSchema - The schema type for validation\n */\nexport interface ElectricCollectionConfig<\n  T extends Row<unknown> = Row<unknown>,\n  TSchema extends StandardSchemaV1 = never,\n> extends BaseCollectionConfig<\n    T,\n    string | number,\n    TSchema,\n    Record<string, Fn>,\n    { txid: Txid | Array<Txid> }\n  > {\n  /**\n   * Configuration options for the ElectricSQL ShapeStream\n   */\n  shapeOptions: ShapeStreamOptions<GetExtensions<T>>\n}\n\nfunction isUpToDateMessage<T extends Row<unknown>>(\n  message: Message<T>\n): message is ControlMessage & { up_to_date: true } {\n  return isControlMessage(message) && message.headers.control === `up-to-date`\n}\n\nfunction isMustRefetchMessage<T extends Row<unknown>>(\n  message: Message<T>\n): message is ControlMessage & { headers: { control: `must-refetch` } } {\n  return isControlMessage(message) && message.headers.control === `must-refetch`\n}\n\n// Check if a message contains txids in its headers\nfunction hasTxids<T extends Row<unknown>>(\n  message: Message<T>\n): message is Message<T> & { headers: { txids?: Array<Txid> } } {\n  return `txids` in message.headers && Array.isArray(message.headers.txids)\n}\n\n/**\n * Type for the awaitTxId utility function\n */\nexport type AwaitTxIdFn = (txId: Txid, timeout?: number) => Promise<boolean>\n\n/**\n * Electric collection utilities type\n */\nexport interface ElectricCollectionUtils extends UtilsRecord {\n  awaitTxId: AwaitTxIdFn\n}\n\n/**\n * Creates Electric collection options for use with a standard Collection\n *\n * @template T - The explicit type of items in the collection (highest priority)\n * @template TSchema - The schema type for validation and type inference (second priority)\n * @template TFallback - The fallback type if no explicit or schema type is provided\n * @param config - Configuration options for the Electric collection\n * @returns Collection options with utilities\n */\n\n// Overload for when schema is provided\nexport function electricCollectionOptions<T extends StandardSchemaV1>(\n  config: ElectricCollectionConfig<InferSchemaOutput<T>, T> & {\n    schema: T\n  }\n): CollectionConfig<InferSchemaOutput<T>, string | number, T> & {\n  id?: string\n  utils: ElectricCollectionUtils\n  schema: T\n}\n\n// Overload for when no schema is provided\nexport function electricCollectionOptions<T extends Row<unknown>>(\n  config: ElectricCollectionConfig<T> & {\n    schema?: never // prohibit schema\n  }\n): CollectionConfig<T, string | number> & {\n  id?: string\n  utils: ElectricCollectionUtils\n  schema?: never // no schema in the result\n}\n\nexport function electricCollectionOptions(\n  config: ElectricCollectionConfig<any, any>\n): CollectionConfig<any, string | number, any> & {\n  id?: string\n  utils: ElectricCollectionUtils\n  schema?: any\n} {\n  const seenTxids = new Store<Set<Txid>>(new Set([]))\n  const sync = createElectricSync<any>(config.shapeOptions, {\n    seenTxids,\n  })\n\n  /**\n   * Wait for a specific transaction ID to be synced\n   * @param txId The transaction ID to wait for as a number\n   * @param timeout Optional timeout in milliseconds (defaults to 30000ms)\n   * @returns Promise that resolves when the txId is synced\n   */\n  const awaitTxId: AwaitTxIdFn = async (\n    txId: Txid,\n    timeout: number = 30000\n  ): Promise<boolean> => {\n    debug(`awaitTxId called with txid %d`, txId)\n    if (typeof txId !== `number`) {\n      throw new ExpectedNumberInAwaitTxIdError(typeof txId)\n    }\n\n    const hasTxid = seenTxids.state.has(txId)\n    if (hasTxid) return true\n\n    return new Promise((resolve, reject) => {\n      const timeoutId = setTimeout(() => {\n        unsubscribe()\n        reject(new TimeoutWaitingForTxIdError(txId))\n      }, timeout)\n\n      const unsubscribe = seenTxids.subscribe(() => {\n        if (seenTxids.state.has(txId)) {\n          debug(`awaitTxId found match for txid %o`, txId)\n          clearTimeout(timeoutId)\n          unsubscribe()\n          resolve(true)\n        }\n      })\n    })\n  }\n\n  // Create wrapper handlers for direct persistence operations that handle txid awaiting\n  const wrappedOnInsert = config.onInsert\n    ? async (params: InsertMutationFnParams<any>) => {\n        // Runtime check (that doesn't follow type)\n\n        const handlerResult = (await config.onInsert!(params)) ?? {}\n        const txid = (handlerResult as { txid?: Txid | Array<Txid> }).txid\n\n        if (!txid) {\n          throw new ElectricInsertHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(txid)) {\n          await Promise.all(txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnUpdate = config.onUpdate\n    ? async (params: UpdateMutationFnParams<any>) => {\n        // Runtime check (that doesn't follow type)\n\n        const handlerResult = (await config.onUpdate!(params)) ?? {}\n        const txid = (handlerResult as { txid?: Txid | Array<Txid> }).txid\n\n        if (!txid) {\n          throw new ElectricUpdateHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(txid)) {\n          await Promise.all(txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  const wrappedOnDelete = config.onDelete\n    ? async (params: DeleteMutationFnParams<any>) => {\n        const handlerResult = await config.onDelete!(params)\n        if (!handlerResult.txid) {\n          throw new ElectricDeleteHandlerMustReturnTxIdError()\n        }\n\n        // Handle both single txid and array of txids\n        if (Array.isArray(handlerResult.txid)) {\n          await Promise.all(handlerResult.txid.map((id) => awaitTxId(id)))\n        } else {\n          await awaitTxId(handlerResult.txid)\n        }\n\n        return handlerResult\n      }\n    : undefined\n\n  // Extract standard Collection config properties\n  const {\n    shapeOptions: _shapeOptions,\n    onInsert: _onInsert,\n    onUpdate: _onUpdate,\n    onDelete: _onDelete,\n    ...restConfig\n  } = config\n\n  return {\n    ...restConfig,\n    sync,\n    onInsert: wrappedOnInsert,\n    onUpdate: wrappedOnUpdate,\n    onDelete: wrappedOnDelete,\n    utils: {\n      awaitTxId,\n    },\n  }\n}\n\n/**\n * Internal function to create ElectricSQL sync configuration\n */\nfunction createElectricSync<T extends Row<unknown>>(\n  shapeOptions: ShapeStreamOptions<GetExtensions<T>>,\n  options: {\n    seenTxids: Store<Set<Txid>>\n  }\n): SyncConfig<T> {\n  const { seenTxids } = options\n\n  // Store for the relation schema information\n  const relationSchema = new Store<string | undefined>(undefined)\n\n  /**\n   * Get the sync metadata for insert operations\n   * @returns Record containing relation information\n   */\n  const getSyncMetadata = (): Record<string, unknown> => {\n    // Use the stored schema if available, otherwise default to 'public'\n    const schema = relationSchema.state || `public`\n\n    return {\n      relation: shapeOptions.params?.table\n        ? [schema, shapeOptions.params.table]\n        : undefined,\n    }\n  }\n\n  let unsubscribeStream: () => void\n\n  return {\n    sync: (params: Parameters<SyncConfig<T>[`sync`]>[0]) => {\n      const { begin, write, commit, markReady, truncate, collection } = params\n\n      // Abort controller for the stream - wraps the signal if provided\n      const abortController = new AbortController()\n\n      if (shapeOptions.signal) {\n        shapeOptions.signal.addEventListener(\n          `abort`,\n          () => {\n            abortController.abort()\n          },\n          {\n            once: true,\n          }\n        )\n        if (shapeOptions.signal.aborted) {\n          abortController.abort()\n        }\n      }\n\n      const stream = new ShapeStream({\n        ...shapeOptions,\n        signal: abortController.signal,\n        onError: (errorParams) => {\n          // Just immediately mark ready if there's an error to avoid blocking\n          // apps waiting for `.preload()` to finish.\n          // Note that Electric sends a 409 error on a `must-refetch` message, but the\n          // ShapeStream handled this and it will not reach this handler, therefor\n          // this markReady will not be triggers by a `must-refetch`.\n          markReady()\n\n          if (shapeOptions.onError) {\n            return shapeOptions.onError(errorParams)\n          } else {\n            console.error(\n              `An error occurred while syncing collection: ${collection.id}, \\n` +\n                `it has been marked as ready to avoid blocking apps waiting for '.preload()' to finish. \\n` +\n                `You can provide an 'onError' handler on the shapeOptions to handle this error, and this message will not be logged.`,\n              errorParams\n            )\n          }\n\n          return\n        },\n      })\n      let transactionStarted = false\n      const newTxids = new Set<Txid>()\n\n      unsubscribeStream = stream.subscribe((messages: Array<Message<T>>) => {\n        let hasUpToDate = false\n\n        for (const message of messages) {\n          // Check for txids in the message and add them to our store\n          if (hasTxids(message)) {\n            message.headers.txids?.forEach((txid) => newTxids.add(txid))\n          }\n\n          if (isChangeMessage(message)) {\n            // Check if the message contains schema information\n            const schema = message.headers.schema\n            if (schema && typeof schema === `string`) {\n              // Store the schema for future use if it's a valid string\n              relationSchema.setState(() => schema)\n            }\n\n            if (!transactionStarted) {\n              begin()\n              transactionStarted = true\n            }\n\n            write({\n              type: message.headers.operation,\n              value: message.value,\n              // Include the primary key and relation info in the metadata\n              metadata: {\n                ...message.headers,\n              },\n            })\n          } else if (isUpToDateMessage(message)) {\n            hasUpToDate = true\n          } else if (isMustRefetchMessage(message)) {\n            debug(\n              `Received must-refetch message, starting transaction with truncate`\n            )\n\n            // Start a transaction and truncate the collection\n            if (!transactionStarted) {\n              begin()\n              transactionStarted = true\n            }\n\n            truncate()\n\n            // Reset hasUpToDate so we continue accumulating changes until next up-to-date\n            hasUpToDate = false\n          }\n        }\n\n        if (hasUpToDate) {\n          // Commit transaction if one was started\n          if (transactionStarted) {\n            commit()\n            transactionStarted = false\n          }\n\n          // Mark the collection as ready now that sync is up to date\n          markReady()\n\n          // Always commit txids when we receive up-to-date, regardless of transaction state\n          seenTxids.setState((currentTxids) => {\n            const clonedSeen = new Set<Txid>(currentTxids)\n            if (newTxids.size > 0) {\n              debug(`new txids synced from pg %O`, Array.from(newTxids))\n            }\n            newTxids.forEach((txid) => clonedSeen.add(txid))\n            newTxids.clear()\n            return clonedSeen\n          })\n        }\n      })\n\n      // Return the unsubscribe function\n      return () => {\n        // Unsubscribe from the stream\n        unsubscribeStream()\n        // Abort the abort controller to stop the stream\n        abortController.abort()\n      }\n    },\n    // Expose the getSyncMetadata function\n    getSyncMetadata,\n  }\n}\n"],"names":[],"mappings":"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"}

package/package.json

@@ -1,13 +1,13 @@
 {
   "name": "@tanstack/electric-db-collection",
   "description": "ElectricSQL collection for TanStack DB",
-  "version": "0.1.18",
+  "version": "0.1.20",
   "dependencies": {
     "@electric-sql/client": "1.0.9",
     "@standard-schema/spec": "^1.0.0",
     "@tanstack/store": "^0.7.5",
     "debug": "^4.4.1",
-    "@tanstack/db": "0.2.3"
+    "@tanstack/db": "0.2.5"
   },
   "devDependencies": {
     "@types/debug": "^4.1.12",

package/src/electric.ts

@@ -13,8 +13,10 @@ import {
   TimeoutWaitingForTxIdError,
 } from "./errors"
 import type {
+  BaseCollectionConfig,
   CollectionConfig,
   DeleteMutationFnParams,
+  Fn,
   InsertMutationFnParams,
   SyncConfig,
   UpdateMutationFnParams,
@@ -45,207 +47,25 @@ type InferSchemaOutput<T> = T extends StandardSchemaV1
     : Record<string, unknown>
   : Record<string, unknown>
 
-type ResolveType<
-  TExplicit extends Row<unknown> = Row<unknown>,
-  TSchema extends StandardSchemaV1 = never,
-  TFallback extends object = Record<string, unknown>,
-> =
-  unknown extends GetExtensions<TExplicit>
-    ? [TSchema] extends [never]
-      ? TFallback
-      : InferSchemaOutput<TSchema>
-    : TExplicit
-
 /**
  * Configuration interface for Electric collection options
- * @template TExplicit - The explicit type of items in the collection (highest priority)
- * @template TSchema - The schema type for validation and type inference (second priority)
- * @template TFallback - The fallback type if no explicit or schema type is provided
- *
- * @remarks
- * Type resolution follows a priority order:
- * 1. If you provide an explicit type via generic parameter, it will be used
- * 2. If no explicit type is provided but a schema is, the schema's output type will be inferred
- * 3. If neither explicit type nor schema is provided, the fallback type will be used
- *
- * You should provide EITHER an explicit type OR a schema, but not both, as they would conflict.
+ * @template T - The type of items in the collection
+ * @template TSchema - The schema type for validation
  */
 export interface ElectricCollectionConfig<
-  TExplicit extends Row<unknown> = Row<unknown>,
+  T extends Row<unknown> = Row<unknown>,
   TSchema extends StandardSchemaV1 = never,
-  TFallback extends Row<unknown> = Row<unknown>,
-> {
+> extends BaseCollectionConfig<
+    T,
+    string | number,
+    TSchema,
+    Record<string, Fn>,
+    { txid: Txid | Array<Txid> }
+  > {
   /**
    * Configuration options for the ElectricSQL ShapeStream
    */
-  shapeOptions: ShapeStreamOptions<
-    GetExtensions<ResolveType<TExplicit, TSchema, TFallback>>
-  >
-
-  /**
-   * All standard Collection configuration properties
-   */
-  id?: string
-  schema?: TSchema
-  getKey: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`getKey`]
-  sync?: CollectionConfig<ResolveType<TExplicit, TSchema, TFallback>>[`sync`]
-
-  /**
-   * Optional asynchronous handler function called before an insert operation
-   * Must return an object containing a txid number or array of txids
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to an object with txid or txids
-   * @example
-   * // Basic Electric insert handler - MUST return { txid: number }
-   * onInsert: async ({ transaction }) => {
-   *   const newItem = transaction.mutations[0].modified
-   *   const result = await api.todos.create({
-   *     data: newItem
-   *   })
-   *   return { txid: result.txid } // Required for Electric sync matching
-   * }
-   *
-   * @example
-   * // Insert handler with multiple items - return array of txids
-   * onInsert: async ({ transaction }) => {
-   *   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) } // Array of txids
-   * }
-   *
-   * @example
-   * // Insert handler with error handling
-   * onInsert: async ({ transaction }) => {
-   *   try {
-   *     const newItem = transaction.mutations[0].modified
-   *     const result = await api.createTodo(newItem)
-   *     return { txid: result.txid }
-   *   } catch (error) {
-   *     console.error('Insert failed:', error)
-   *     throw error // This will cause the transaction to fail
-   *   }
-   * }
-   *
-   * @example
-   * // Insert handler with batch operation - single txid
-   * onInsert: async ({ transaction }) => {
-   *   const items = transaction.mutations.map(m => m.modified)
-   *   const result = await api.todos.createMany({
-   *     data: items
-   *   })
-   *   return { txid: result.txid } // Single txid for batch operation
-   * }
-   */
-  onInsert?: (
-    params: InsertMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>
-  ) => Promise<{ txid: Txid | Array<Txid> }>
-
-  /**
-   * Optional asynchronous handler function called before an update operation
-   * Must return an object containing a txid number or array of txids
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to an object with txid or txids
-   * @example
-   * // Basic Electric update handler - MUST return { txid: number }
-   * onUpdate: async ({ transaction }) => {
-   *   const { original, changes } = transaction.mutations[0]
-   *   const result = await api.todos.update({
-   *     where: { id: original.id },
-   *     data: changes // Only the changed fields
-   *   })
-   *   return { txid: result.txid } // Required for Electric sync matching
-   * }
-   *
-   * @example
-   * // Update handler with multiple items - return array of txids
-   * onUpdate: async ({ transaction }) => {
-   *   const updates = await Promise.all(
-   *     transaction.mutations.map(m =>
-   *       api.todos.update({
-   *         where: { id: m.original.id },
-   *         data: m.changes
-   *       })
-   *     )
-   *   )
-   *   return { txid: updates.map(u => u.txid) } // Array of txids
-   * }
-   *
-   * @example
-   * // Update handler with optimistic rollback
-   * onUpdate: async ({ transaction }) => {
-   *   const mutation = transaction.mutations[0]
-   *   try {
-   *     const result = await api.updateTodo(mutation.original.id, mutation.changes)
-   *     return { txid: result.txid }
-   *   } catch (error) {
-   *     // Transaction will automatically rollback optimistic changes
-   *     console.error('Update failed, rolling back:', error)
-   *     throw error
-   *   }
-   * }
-   */
-  onUpdate?: (
-    params: UpdateMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>
-  ) => Promise<{ txid: Txid | Array<Txid> }>
-
-  /**
-   * Optional asynchronous handler function called before a delete operation
-   * Must return an object containing a txid number or array of txids
-   * @param params Object containing transaction and collection information
-   * @returns Promise resolving to an object with txid or txids
-   * @example
-   * // Basic Electric delete handler - MUST return { txid: number }
-   * onDelete: async ({ transaction }) => {
-   *   const mutation = transaction.mutations[0]
-   *   const result = await api.todos.delete({
-   *     id: mutation.original.id
-   *   })
-   *   return { txid: result.txid } // Required for Electric sync matching
-   * }
-   *
-   * @example
-   * // Delete handler with multiple items - return array of txids
-   * onDelete: async ({ transaction }) => {
-   *   const deletes = await Promise.all(
-   *     transaction.mutations.map(m =>
-   *       api.todos.delete({
-   *         where: { id: m.key }
-   *       })
-   *     )
-   *   )
-   *   return { txid: deletes.map(d => d.txid) } // Array of txids
-   * }
-   *
-   * @example
-   * // Delete handler with batch operation - single txid
-   * onDelete: async ({ transaction }) => {
-   *   const idsToDelete = transaction.mutations.map(m => m.original.id)
-   *   const result = await api.todos.deleteMany({
-   *     ids: idsToDelete
-   *   })
-   *   return { txid: result.txid } // Single txid for batch operation
-   * }
-   *
-   * @example
-   * // Delete handler with optimistic rollback
-   * onDelete: async ({ transaction }) => {
-   *   const mutation = transaction.mutations[0]
-   *   try {
-   *     const result = await api.deleteTodo(mutation.original.id)
-   *     return { txid: result.txid }
-   *   } catch (error) {
-   *     // Transaction will automatically rollback optimistic changes
-   *     console.error('Delete failed, rolling back:', error)
-   *     throw error
-   *   }
-   * }
-   *
-   */
-  onDelete?: (
-    params: DeleteMutationFnParams<ResolveType<TExplicit, TSchema, TFallback>>
-  ) => Promise<{ txid: Txid | Array<Txid> }>
+  shapeOptions: ShapeStreamOptions<GetExtensions<T>>
 }
 
 function isUpToDateMessage<T extends Row<unknown>>(
@@ -282,24 +102,46 @@ export interface ElectricCollectionUtils extends UtilsRecord {
 /**
  * Creates Electric collection options for use with a standard Collection
  *
- * @template TExplicit - The explicit type of items in the collection (highest priority)
+ * @template T - The explicit type of items in the collection (highest priority)
  * @template TSchema - The schema type for validation and type inference (second priority)
  * @template TFallback - The fallback type if no explicit or schema type is provided
  * @param config - Configuration options for the Electric collection
  * @returns Collection options with utilities
  */
-export function electricCollectionOptions<
-  TExplicit extends Row<unknown> = Row<unknown>,
-  TSchema extends StandardSchemaV1 = never,
-  TFallback extends Row<unknown> = Row<unknown>,
->(config: ElectricCollectionConfig<TExplicit, TSchema, TFallback>) {
+
+// Overload for when schema is provided
+export function electricCollectionOptions<T extends StandardSchemaV1>(
+  config: ElectricCollectionConfig<InferSchemaOutput<T>, T> & {
+    schema: T
+  }
+): CollectionConfig<InferSchemaOutput<T>, string | number, T> & {
+  id?: string
+  utils: ElectricCollectionUtils
+  schema: T
+}
+
+// Overload for when no schema is provided
+export function electricCollectionOptions<T extends Row<unknown>>(
+  config: ElectricCollectionConfig<T> & {
+    schema?: never // prohibit schema
+  }
+): CollectionConfig<T, string | number> & {
+  id?: string
+  utils: ElectricCollectionUtils
+  schema?: never // no schema in the result
+}
+
+export function electricCollectionOptions(
+  config: ElectricCollectionConfig<any, any>
+): CollectionConfig<any, string | number, any> & {
+  id?: string
+  utils: ElectricCollectionUtils
+  schema?: any
+} {
   const seenTxids = new Store<Set<Txid>>(new Set([]))
-  const sync = createElectricSync<ResolveType<TExplicit, TSchema, TFallback>>(
-    config.shapeOptions,
-    {
-      seenTxids,
-    }
-  )
+  const sync = createElectricSync<any>(config.shapeOptions, {
+    seenTxids,
+  })
 
   /**
    * Wait for a specific transaction ID to be synced
@@ -338,13 +180,9 @@ export function electricCollectionOptions<
 
   // Create wrapper handlers for direct persistence operations that handle txid awaiting
   const wrappedOnInsert = config.onInsert
-    ? async (
-        params: InsertMutationFnParams<
-          ResolveType<TExplicit, TSchema, TFallback>
-        >
-      ) => {
+    ? async (params: InsertMutationFnParams<any>) => {
         // Runtime check (that doesn't follow type)
-        // eslint-disable-next-line
+
         const handlerResult = (await config.onInsert!(params)) ?? {}
         const txid = (handlerResult as { txid?: Txid | Array<Txid> }).txid
 
@@ -364,13 +202,9 @@ export function electricCollectionOptions<
     : undefined
 
   const wrappedOnUpdate = config.onUpdate
-    ? async (
-        params: UpdateMutationFnParams<
-          ResolveType<TExplicit, TSchema, TFallback>
-        >
-      ) => {
+    ? async (params: UpdateMutationFnParams<any>) => {
         // Runtime check (that doesn't follow type)
-        // eslint-disable-next-line
+
         const handlerResult = (await config.onUpdate!(params)) ?? {}
         const txid = (handlerResult as { txid?: Txid | Array<Txid> }).txid
 
@@ -390,11 +224,7 @@ export function electricCollectionOptions<
     : undefined
 
   const wrappedOnDelete = config.onDelete
-    ? async (
-        params: DeleteMutationFnParams<
-          ResolveType<TExplicit, TSchema, TFallback>
-        >
-      ) => {
+    ? async (params: DeleteMutationFnParams<any>) => {
         const handlerResult = await config.onDelete!(params)
         if (!handlerResult.txid) {
           throw new ElectricDeleteHandlerMustReturnTxIdError()