@tanstack/electric-db-collection 0.1.29 → 0.1.31

package/dist/cjs/errors.cjs

@@ -2,51 +2,38 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const db = require("@tanstack/db");
 class ElectricDBCollectionError extends db.TanStackDBError {
-  constructor(message) {
-    super(message);
+  constructor(message, collectionId) {
+    super(`${collectionId ? `[${collectionId}] ` : ``}${message}`);
     this.name = `ElectricDBCollectionError`;
   }
 }
 class ExpectedNumberInAwaitTxIdError extends ElectricDBCollectionError {
-  constructor(txIdType) {
-    super(`Expected number in awaitTxId, received ${txIdType}`);
+  constructor(txIdType, collectionId) {
+    super(`Expected number in awaitTxId, received ${txIdType}`, collectionId);
     this.name = `ExpectedNumberInAwaitTxIdError`;
   }
 }
 class TimeoutWaitingForTxIdError extends ElectricDBCollectionError {
-  constructor(txId) {
-    super(`Timeout waiting for txId: ${txId}`);
+  constructor(txId, collectionId) {
+    super(`Timeout waiting for txId: ${txId}`, collectionId);
     this.name = `TimeoutWaitingForTxIdError`;
   }
 }
-class ElectricInsertHandlerMustReturnTxIdError extends ElectricDBCollectionError {
-  constructor() {
-    super(
-      `Electric collection onInsert handler must return a txid or array of txids`
-    );
-    this.name = `ElectricInsertHandlerMustReturnTxIdError`;
+class TimeoutWaitingForMatchError extends ElectricDBCollectionError {
+  constructor(collectionId) {
+    super(`Timeout waiting for custom match function`, collectionId);
+    this.name = `TimeoutWaitingForMatchError`;
   }
 }
-class ElectricUpdateHandlerMustReturnTxIdError extends ElectricDBCollectionError {
-  constructor() {
-    super(
-      `Electric collection onUpdate handler must return a txid or array of txids`
-    );
-    this.name = `ElectricUpdateHandlerMustReturnTxIdError`;
-  }
-}
-class ElectricDeleteHandlerMustReturnTxIdError extends ElectricDBCollectionError {
-  constructor() {
-    super(
-      `Electric collection onDelete handler must return a txid or array of txids`
-    );
-    this.name = `ElectricDeleteHandlerMustReturnTxIdError`;
+class StreamAbortedError extends ElectricDBCollectionError {
+  constructor(collectionId) {
+    super(`Stream aborted`, collectionId);
+    this.name = `StreamAbortedError`;
   }
 }
 exports.ElectricDBCollectionError = ElectricDBCollectionError;
-exports.ElectricDeleteHandlerMustReturnTxIdError = ElectricDeleteHandlerMustReturnTxIdError;
-exports.ElectricInsertHandlerMustReturnTxIdError = ElectricInsertHandlerMustReturnTxIdError;
-exports.ElectricUpdateHandlerMustReturnTxIdError = ElectricUpdateHandlerMustReturnTxIdError;
 exports.ExpectedNumberInAwaitTxIdError = ExpectedNumberInAwaitTxIdError;
+exports.StreamAbortedError = StreamAbortedError;
+exports.TimeoutWaitingForMatchError = TimeoutWaitingForMatchError;
 exports.TimeoutWaitingForTxIdError = TimeoutWaitingForTxIdError;
 //# sourceMappingURL=errors.cjs.map

package/dist/cjs/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.cjs","sources":["../../src/errors.ts"],"sourcesContent":["import { TanStackDBError } from \"@tanstack/db\"\n\n// Electric DB Collection Errors\nexport class ElectricDBCollectionError extends TanStackDBError {\n  constructor(message: string) {\n    super(message)\n    this.name = `ElectricDBCollectionError`\n  }\n}\n\nexport class ExpectedNumberInAwaitTxIdError extends ElectricDBCollectionError {\n  constructor(txIdType: string) {\n    super(`Expected number in awaitTxId, received ${txIdType}`)\n    this.name = `ExpectedNumberInAwaitTxIdError`\n  }\n}\n\nexport class TimeoutWaitingForTxIdError extends ElectricDBCollectionError {\n  constructor(txId: number) {\n    super(`Timeout waiting for txId: ${txId}`)\n    this.name = `TimeoutWaitingForTxIdError`\n  }\n}\n\nexport class ElectricInsertHandlerMustReturnTxIdError extends ElectricDBCollectionError {\n  constructor() {\n    super(\n      `Electric collection onInsert handler must return a txid or array of txids`\n    )\n    this.name = `ElectricInsertHandlerMustReturnTxIdError`\n  }\n}\n\nexport class ElectricUpdateHandlerMustReturnTxIdError extends ElectricDBCollectionError {\n  constructor() {\n    super(\n      `Electric collection onUpdate handler must return a txid or array of txids`\n    )\n    this.name = `ElectricUpdateHandlerMustReturnTxIdError`\n  }\n}\n\nexport class ElectricDeleteHandlerMustReturnTxIdError extends ElectricDBCollectionError {\n  constructor() {\n    super(\n      `Electric collection onDelete handler must return a txid or array of txids`\n    )\n    this.name = `ElectricDeleteHandlerMustReturnTxIdError`\n  }\n}\n"],"names":["TanStackDBError"],"mappings":";;;AAGO,MAAM,kCAAkCA,GAAAA,gBAAgB;AAAA,EAC7D,YAAY,SAAiB;AAC3B,UAAM,OAAO;AACb,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,uCAAuC,0BAA0B;AAAA,EAC5E,YAAY,UAAkB;AAC5B,UAAM,0CAA0C,QAAQ,EAAE;AAC1D,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,mCAAmC,0BAA0B;AAAA,EACxE,YAAY,MAAc;AACxB,UAAM,6BAA6B,IAAI,EAAE;AACzC,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,iDAAiD,0BAA0B;AAAA,EACtF,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAEF,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,iDAAiD,0BAA0B;AAAA,EACtF,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAEF,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,iDAAiD,0BAA0B;AAAA,EACtF,cAAc;AACZ;AAAA,MACE;AAAA,IAAA;AAEF,SAAK,OAAO;AAAA,EACd;AACF;;;;;;;"}
+{"version":3,"file":"errors.cjs","sources":["../../src/errors.ts"],"sourcesContent":["import { TanStackDBError } from \"@tanstack/db\"\n\n// Electric DB Collection Errors\nexport class ElectricDBCollectionError extends TanStackDBError {\n  constructor(message: string, collectionId?: string) {\n    super(`${collectionId ? `[${collectionId}] ` : ``}${message}`)\n    this.name = `ElectricDBCollectionError`\n  }\n}\n\nexport class ExpectedNumberInAwaitTxIdError extends ElectricDBCollectionError {\n  constructor(txIdType: string, collectionId?: string) {\n    super(`Expected number in awaitTxId, received ${txIdType}`, collectionId)\n    this.name = `ExpectedNumberInAwaitTxIdError`\n  }\n}\n\nexport class TimeoutWaitingForTxIdError extends ElectricDBCollectionError {\n  constructor(txId: number, collectionId?: string) {\n    super(`Timeout waiting for txId: ${txId}`, collectionId)\n    this.name = `TimeoutWaitingForTxIdError`\n  }\n}\n\nexport class TimeoutWaitingForMatchError extends ElectricDBCollectionError {\n  constructor(collectionId?: string) {\n    super(`Timeout waiting for custom match function`, collectionId)\n    this.name = `TimeoutWaitingForMatchError`\n  }\n}\n\nexport class StreamAbortedError extends ElectricDBCollectionError {\n  constructor(collectionId?: string) {\n    super(`Stream aborted`, collectionId)\n    this.name = `StreamAbortedError`\n  }\n}\n"],"names":["TanStackDBError"],"mappings":";;;AAGO,MAAM,kCAAkCA,GAAAA,gBAAgB;AAAA,EAC7D,YAAY,SAAiB,cAAuB;AAClD,UAAM,GAAG,eAAe,IAAI,YAAY,OAAO,EAAE,GAAG,OAAO,EAAE;AAC7D,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,uCAAuC,0BAA0B;AAAA,EAC5E,YAAY,UAAkB,cAAuB;AACnD,UAAM,0CAA0C,QAAQ,IAAI,YAAY;AACxE,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,mCAAmC,0BAA0B;AAAA,EACxE,YAAY,MAAc,cAAuB;AAC/C,UAAM,6BAA6B,IAAI,IAAI,YAAY;AACvD,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,oCAAoC,0BAA0B;AAAA,EACzE,YAAY,cAAuB;AACjC,UAAM,6CAA6C,YAAY;AAC/D,SAAK,OAAO;AAAA,EACd;AACF;AAEO,MAAM,2BAA2B,0BAA0B;AAAA,EAChE,YAAY,cAAuB;AACjC,UAAM,kBAAkB,YAAY;AACpC,SAAK,OAAO;AAAA,EACd;AACF;;;;;;"}

package/dist/cjs/errors.d.cts

@@ -1,19 +1,16 @@
 import { TanStackDBError } from '@tanstack/db';
 export declare class ElectricDBCollectionError extends TanStackDBError {
-    constructor(message: string);
+    constructor(message: string, collectionId?: string);
 }
 export declare class ExpectedNumberInAwaitTxIdError extends ElectricDBCollectionError {
-    constructor(txIdType: string);
+    constructor(txIdType: string, collectionId?: string);
 }
 export declare class TimeoutWaitingForTxIdError extends ElectricDBCollectionError {
-    constructor(txId: number);
+    constructor(txId: number, collectionId?: string);
 }
-export declare class ElectricInsertHandlerMustReturnTxIdError extends ElectricDBCollectionError {
-    constructor();
+export declare class TimeoutWaitingForMatchError extends ElectricDBCollectionError {
+    constructor(collectionId?: string);
 }
-export declare class ElectricUpdateHandlerMustReturnTxIdError extends ElectricDBCollectionError {
-    constructor();
-}
-export declare class ElectricDeleteHandlerMustReturnTxIdError extends ElectricDBCollectionError {
-    constructor();
+export declare class StreamAbortedError extends ElectricDBCollectionError {
+    constructor(collectionId?: string);
 }

package/dist/cjs/index.cjs

@@ -4,9 +4,8 @@ const electric = require("./electric.cjs");
 const errors = require("./errors.cjs");
 exports.electricCollectionOptions = electric.electricCollectionOptions;
 exports.ElectricDBCollectionError = errors.ElectricDBCollectionError;
-exports.ElectricDeleteHandlerMustReturnTxIdError = errors.ElectricDeleteHandlerMustReturnTxIdError;
-exports.ElectricInsertHandlerMustReturnTxIdError = errors.ElectricInsertHandlerMustReturnTxIdError;
-exports.ElectricUpdateHandlerMustReturnTxIdError = errors.ElectricUpdateHandlerMustReturnTxIdError;
 exports.ExpectedNumberInAwaitTxIdError = errors.ExpectedNumberInAwaitTxIdError;
+exports.StreamAbortedError = errors.StreamAbortedError;
+exports.TimeoutWaitingForMatchError = errors.TimeoutWaitingForMatchError;
 exports.TimeoutWaitingForTxIdError = errors.TimeoutWaitingForTxIdError;
 //# sourceMappingURL=index.cjs.map

package/dist/cjs/index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;;"}
+{"version":3,"file":"index.cjs","sources":[],"sourcesContent":[],"names":[],"mappings":";;;;;;;;;;"}

package/dist/esm/electric.d.ts

@@ -1,33 +1,143 @@
-import { BaseCollectionConfig, CollectionConfig, Fn, UtilsRecord } from '@tanstack/db';
+import { BaseCollectionConfig, CollectionConfig, DeleteMutationFnParams, InsertMutationFnParams, UpdateMutationFnParams, UtilsRecord } from '@tanstack/db';
 import { StandardSchemaV1 } from '@standard-schema/spec';
-import { GetExtensions, Row, ShapeStreamOptions } from '@electric-sql/client';
+import { GetExtensions, Message, Row, ShapeStreamOptions } from '@electric-sql/client';
+export { isChangeMessage, isControlMessage } from '@electric-sql/client';
 /**
  * Type representing a transaction ID in ElectricSQL
  */
 export type Txid = number;
+/**
+ * Custom match function type - receives stream messages and returns boolean
+ * indicating if the mutation has been synchronized
+ */
+export type MatchFunction<T extends Row<unknown>> = (message: Message<T>) => boolean;
+/**
+ * Matching strategies for Electric synchronization
+ * Handlers can return:
+ * - Txid strategy: { txid: number | number[] } (recommended)
+ * - Void (no return value) - mutation completes without waiting
+ */
+export type MatchingStrategy = {
+    txid: Txid | Array<Txid>;
+} | void;
 type InferSchemaOutput<T> = T extends StandardSchemaV1 ? StandardSchemaV1.InferOutput<T> extends Row<unknown> ? StandardSchemaV1.InferOutput<T> : Record<string, unknown> : Record<string, unknown>;
 /**
  * Configuration interface for Electric collection options
  * @template T - The type of items in the collection
  * @template TSchema - The schema type for validation
  */
-export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never> extends BaseCollectionConfig<T, string | number, TSchema, Record<string, Fn>, {
-    txid: Txid | Array<Txid>;
-}> {
+export interface ElectricCollectionConfig<T extends Row<unknown> = Row<unknown>, TSchema extends StandardSchemaV1 = never> extends Omit<BaseCollectionConfig<T, string | number, TSchema, UtilsRecord, any>, `onInsert` | `onUpdate` | `onDelete`> {
     /**
      * Configuration options for the ElectricSQL ShapeStream
      */
     shapeOptions: ShapeStreamOptions<GetExtensions<T>>;
+    /**
+     * Optional asynchronous handler function called before an insert operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to { txid } or void
+     * @example
+     * // Basic Electric insert handler with txid (recommended)
+     * onInsert: async ({ transaction }) => {
+     *   const newItem = transaction.mutations[0].modified
+     *   const result = await api.todos.create({
+     *     data: newItem
+     *   })
+     *   return { txid: result.txid }
+     * }
+     *
+     * @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) }
+     * }
+     *
+     * @example
+     * // Use awaitMatch utility for custom matching
+     * onInsert: async ({ transaction, collection }) => {
+     *   const newItem = transaction.mutations[0].modified
+     *   await api.todos.create({ data: newItem })
+     *   await collection.utils.awaitMatch(
+     *     (message) => isChangeMessage(message) &&
+     *                  message.headers.operation === 'insert' &&
+     *                  message.value.name === newItem.name
+     *   )
+     * }
+     */
+    onInsert?: (params: InsertMutationFnParams<T>) => Promise<MatchingStrategy>;
+    /**
+     * Optional asynchronous handler function called before an update operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to { txid } or void
+     * @example
+     * // Basic Electric update handler with txid (recommended)
+     * onUpdate: async ({ transaction }) => {
+     *   const { original, changes } = transaction.mutations[0]
+     *   const result = await api.todos.update({
+     *     where: { id: original.id },
+     *     data: changes
+     *   })
+     *   return { txid: result.txid }
+     * }
+     *
+     * @example
+     * // Use awaitMatch utility for custom matching
+     * onUpdate: async ({ transaction, collection }) => {
+     *   const { original, changes } = transaction.mutations[0]
+     *   await api.todos.update({ where: { id: original.id }, data: changes })
+     *   await collection.utils.awaitMatch(
+     *     (message) => isChangeMessage(message) &&
+     *                  message.headers.operation === 'update' &&
+     *                  message.value.id === original.id
+     *   )
+     * }
+     */
+    onUpdate?: (params: UpdateMutationFnParams<T>) => Promise<MatchingStrategy>;
+    /**
+     * Optional asynchronous handler function called before a delete operation
+     * @param params Object containing transaction and collection information
+     * @returns Promise resolving to { txid } or void
+     * @example
+     * // Basic Electric delete handler with txid (recommended)
+     * onDelete: async ({ transaction }) => {
+     *   const mutation = transaction.mutations[0]
+     *   const result = await api.todos.delete({
+     *     id: mutation.original.id
+     *   })
+     *   return { txid: result.txid }
+     * }
+     *
+     * @example
+     * // Use awaitMatch utility for custom matching
+     * onDelete: async ({ transaction, collection }) => {
+     *   const mutation = transaction.mutations[0]
+     *   await api.todos.delete({ id: mutation.original.id })
+     *   await collection.utils.awaitMatch(
+     *     (message) => isChangeMessage(message) &&
+     *                  message.headers.operation === 'delete' &&
+     *                  message.value.id === mutation.original.id
+     *   )
+     * }
+     */
+    onDelete?: (params: DeleteMutationFnParams<T>) => Promise<MatchingStrategy>;
 }
 /**
  * Type for the awaitTxId utility function
  */
 export type AwaitTxIdFn = (txId: Txid, timeout?: number) => Promise<boolean>;
+/**
+ * Type for the awaitMatch utility function
+ */
+export type AwaitMatchFn<T extends Row<unknown>> = (matchFn: MatchFunction<T>, timeout?: number) => Promise<boolean>;
 /**
  * Electric collection utilities type
  */
-export interface ElectricCollectionUtils extends UtilsRecord {
+export interface ElectricCollectionUtils<T extends Row<unknown> = Row<unknown>> extends UtilsRecord {
     awaitTxId: AwaitTxIdFn;
+    awaitMatch: AwaitMatchFn<T>;
 }
 /**
  * Creates Electric collection options for use with a standard Collection
@@ -52,4 +162,3 @@ export declare function electricCollectionOptions<T extends Row<unknown>>(config
     utils: ElectricCollectionUtils;
     schema?: never;
 };
-export {};

package/dist/esm/electric.js

@@ -1,7 +1,8 @@
 import { ShapeStream, isChangeMessage, isVisibleInSnapshot, isControlMessage } from "@electric-sql/client";
+import { isChangeMessage as isChangeMessage2, isControlMessage as isControlMessage2 } from "@electric-sql/client";
 import { Store } from "@tanstack/store";
 import DebugModule from "debug";
-import { ElectricInsertHandlerMustReturnTxIdError, ElectricUpdateHandlerMustReturnTxIdError, ElectricDeleteHandlerMustReturnTxIdError, ExpectedNumberInAwaitTxIdError, TimeoutWaitingForTxIdError } from "./errors.js";
+import { StreamAbortedError, ExpectedNumberInAwaitTxIdError, TimeoutWaitingForTxIdError, TimeoutWaitingForMatchError } from "./errors.js";
 const debug = DebugModule.debug(`ts/db:electric`);
 function isUpToDateMessage(message) {
   return isControlMessage(message) && message.headers.control === `up-to-date`;
@@ -25,14 +26,48 @@ function hasTxids(message) {
 function electricCollectionOptions(config) {
   const seenTxids = new Store(/* @__PURE__ */ new Set([]));
   const seenSnapshots = new Store([]);
+  const pendingMatches = new Store(/* @__PURE__ */ new Map());
+  const currentBatchMessages = new Store([]);
+  const removePendingMatches = (matchIds) => {
+    if (matchIds.length > 0) {
+      pendingMatches.setState((current) => {
+        const newMatches = new Map(current);
+        matchIds.forEach((id) => newMatches.delete(id));
+        return newMatches;
+      });
+    }
+  };
+  const resolveMatchedPendingMatches = () => {
+    const matchesToResolve = [];
+    pendingMatches.state.forEach((match, matchId) => {
+      if (match.matched) {
+        clearTimeout(match.timeoutId);
+        match.resolve(true);
+        matchesToResolve.push(matchId);
+        debug(
+          `${config.id ? `[${config.id}] ` : ``}awaitMatch resolved on up-to-date for match %s`,
+          matchId
+        );
+      }
+    });
+    removePendingMatches(matchesToResolve);
+  };
   const sync = createElectricSync(config.shapeOptions, {
     seenTxids,
-    seenSnapshots
+    seenSnapshots,
+    pendingMatches,
+    currentBatchMessages,
+    removePendingMatches,
+    resolveMatchedPendingMatches,
+    collectionId: config.id
   });
-  const awaitTxId = async (txId, timeout = 3e4) => {
-    debug(`awaitTxId called with txid %d`, txId);
+  const awaitTxId = async (txId, timeout = 5e3) => {
+    debug(
+      `${config.id ? `[${config.id}] ` : ``}awaitTxId called with txid %d`,
+      txId
+    );
     if (typeof txId !== `number`) {
-      throw new ExpectedNumberInAwaitTxIdError(typeof txId);
+      throw new ExpectedNumberInAwaitTxIdError(typeof txId, config.id);
     }
     const hasTxid = seenTxids.state.has(txId);
     if (hasTxid) return true;
@@ -44,11 +79,14 @@ function electricCollectionOptions(config) {
       const timeoutId = setTimeout(() => {
         unsubscribeSeenTxids();
         unsubscribeSeenSnapshots();
-        reject(new TimeoutWaitingForTxIdError(txId));
+        reject(new TimeoutWaitingForTxIdError(txId, config.id));
       }, timeout);
       const unsubscribeSeenTxids = seenTxids.subscribe(() => {
         if (seenTxids.state.has(txId)) {
-          debug(`awaitTxId found match for txid %o`, txId);
+          debug(
+            `${config.id ? `[${config.id}] ` : ``}awaitTxId found match for txid %o`,
+            txId
+          );
           clearTimeout(timeoutId);
           unsubscribeSeenTxids();
           unsubscribeSeenSnapshots();
@@ -61,7 +99,7 @@ function electricCollectionOptions(config) {
         );
         if (visibleSnapshot) {
           debug(
-            `awaitTxId found match for txid %o in snapshot %o`,
+            `${config.id ? `[${config.id}] ` : ``}awaitTxId found match for txid %o in snapshot %o`,
             txId,
             visibleSnapshot
           );
@@ -73,42 +111,96 @@ function electricCollectionOptions(config) {
       });
     });
   };
-  const wrappedOnInsert = config.onInsert ? async (params) => {
-    const handlerResult = await config.onInsert(params) ?? {};
-    const txid = handlerResult.txid;
-    if (!txid) {
-      throw new ElectricInsertHandlerMustReturnTxIdError();
-    }
-    if (Array.isArray(txid)) {
-      await Promise.all(txid.map((id) => awaitTxId(id)));
-    } else {
-      await awaitTxId(txid);
+  const awaitMatch = async (matchFn, timeout = 3e3) => {
+    debug(
+      `${config.id ? `[${config.id}] ` : ``}awaitMatch called with custom function`
+    );
+    return new Promise((resolve, reject) => {
+      const matchId = Math.random().toString(36);
+      const cleanupMatch = () => {
+        pendingMatches.setState((current) => {
+          const newMatches = new Map(current);
+          newMatches.delete(matchId);
+          return newMatches;
+        });
+      };
+      const onTimeout = () => {
+        cleanupMatch();
+        reject(new TimeoutWaitingForMatchError(config.id));
+      };
+      const timeoutId = setTimeout(onTimeout, timeout);
+      const checkMatch = (message) => {
+        if (matchFn(message)) {
+          debug(
+            `${config.id ? `[${config.id}] ` : ``}awaitMatch found matching message, waiting for up-to-date`
+          );
+          pendingMatches.setState((current) => {
+            const newMatches = new Map(current);
+            const existing = newMatches.get(matchId);
+            if (existing) {
+              newMatches.set(matchId, { ...existing, matched: true });
+            }
+            return newMatches;
+          });
+          return true;
+        }
+        return false;
+      };
+      for (const message of currentBatchMessages.state) {
+        if (matchFn(message)) {
+          debug(
+            `${config.id ? `[${config.id}] ` : ``}awaitMatch found immediate match in current batch, waiting for up-to-date`
+          );
+          pendingMatches.setState((current) => {
+            const newMatches = new Map(current);
+            newMatches.set(matchId, {
+              matchFn: checkMatch,
+              resolve,
+              reject,
+              timeoutId,
+              matched: true
+              // Already matched
+            });
+            return newMatches;
+          });
+          return;
+        }
+      }
+      pendingMatches.setState((current) => {
+        const newMatches = new Map(current);
+        newMatches.set(matchId, {
+          matchFn: checkMatch,
+          resolve,
+          reject,
+          timeoutId,
+          matched: false
+        });
+        return newMatches;
+      });
+    });
+  };
+  const processMatchingStrategy = async (result) => {
+    if (result && `txid` in result) {
+      if (Array.isArray(result.txid)) {
+        await Promise.all(result.txid.map(awaitTxId));
+      } else {
+        await awaitTxId(result.txid);
+      }
     }
+  };
+  const wrappedOnInsert = config.onInsert ? async (params) => {
+    const handlerResult = await config.onInsert(params);
+    await processMatchingStrategy(handlerResult);
     return handlerResult;
   } : void 0;
   const wrappedOnUpdate = config.onUpdate ? async (params) => {
-    const handlerResult = await config.onUpdate(params) ?? {};
-    const txid = handlerResult.txid;
-    if (!txid) {
-      throw new ElectricUpdateHandlerMustReturnTxIdError();
-    }
-    if (Array.isArray(txid)) {
-      await Promise.all(txid.map((id) => awaitTxId(id)));
-    } else {
-      await awaitTxId(txid);
-    }
+    const handlerResult = await config.onUpdate(params);
+    await processMatchingStrategy(handlerResult);
     return handlerResult;
   } : void 0;
   const wrappedOnDelete = config.onDelete ? async (params) => {
     const handlerResult = await config.onDelete(params);
-    if (!handlerResult.txid) {
-      throw new ElectricDeleteHandlerMustReturnTxIdError();
-    }
-    if (Array.isArray(handlerResult.txid)) {
-      await Promise.all(handlerResult.txid.map((id) => awaitTxId(id)));
-    } else {
-      await awaitTxId(handlerResult.txid);
-    }
+    await processMatchingStrategy(handlerResult);
     return handlerResult;
   } : void 0;
   const {
@@ -125,13 +217,22 @@ function electricCollectionOptions(config) {
     onUpdate: wrappedOnUpdate,
     onDelete: wrappedOnDelete,
     utils: {
-      awaitTxId
+      awaitTxId,
+      awaitMatch
     }
   };
 }
 function createElectricSync(shapeOptions, options) {
-  const { seenTxids } = options;
-  const { seenSnapshots } = options;
+  const {
+    seenTxids,
+    seenSnapshots,
+    pendingMatches,
+    currentBatchMessages,
+    removePendingMatches,
+    resolveMatchedPendingMatches,
+    collectionId
+  } = options;
+  const MAX_BATCH_MESSAGES = 1e3;
   const relationSchema = new Store(void 0);
   const getSyncMetadata = () => {
     const schema = relationSchema.state || `public`;
@@ -158,6 +259,15 @@ function createElectricSync(shapeOptions, options) {
           abortController.abort();
         }
       }
+      abortController.signal.addEventListener(`abort`, () => {
+        pendingMatches.setState((current) => {
+          current.forEach((match) => {
+            clearTimeout(match.timeoutId);
+            match.reject(new StreamAbortedError());
+          });
+          return /* @__PURE__ */ new Map();
+        });
+      });
       const stream = new ShapeStream({
         ...shapeOptions,
         signal: abortController.signal,
@@ -182,9 +292,34 @@ You can provide an 'onError' handler on the shapeOptions to handle this error, a
       unsubscribeStream = stream.subscribe((messages) => {
         let hasUpToDate = false;
         for (const message of messages) {
+          if (isChangeMessage(message)) {
+            currentBatchMessages.setState((currentBuffer) => {
+              const newBuffer = [...currentBuffer, message];
+              if (newBuffer.length > MAX_BATCH_MESSAGES) {
+                newBuffer.splice(0, newBuffer.length - MAX_BATCH_MESSAGES);
+              }
+              return newBuffer;
+            });
+          }
           if (hasTxids(message)) {
             message.headers.txids?.forEach((txid) => newTxids.add(txid));
           }
+          const matchesToRemove = [];
+          pendingMatches.state.forEach((match, matchId) => {
+            if (!match.matched) {
+              try {
+                match.matchFn(message);
+              } catch (err) {
+                clearTimeout(match.timeoutId);
+                match.reject(
+                  err instanceof Error ? err : new Error(String(err))
+                );
+                matchesToRemove.push(matchId);
+                debug(`matchFn error: %o`, err);
+              }
+            }
+          });
+          removePendingMatches(matchesToRemove);
           if (isChangeMessage(message)) {
             const schema = message.headers.schema;
             if (schema && typeof schema === `string`) {
@@ -208,7 +343,7 @@ You can provide an 'onError' handler on the shapeOptions to handle this error, a
             hasUpToDate = true;
           } else if (isMustRefetchMessage(message)) {
             debug(
-              `Received must-refetch message, starting transaction with truncate`
+              `${collectionId ? `[${collectionId}] ` : ``}Received must-refetch message, starting transaction with truncate`
             );
             if (!transactionStarted) {
               begin();
@@ -219,6 +354,7 @@ You can provide an 'onError' handler on the shapeOptions to handle this error, a
           }
         }
         if (hasUpToDate) {
+          currentBatchMessages.setState(() => []);
           if (transactionStarted) {
             commit();
             transactionStarted = false;
@@ -227,7 +363,10 @@ You can provide an 'onError' handler on the shapeOptions to handle this error, a
           seenTxids.setState((currentTxids) => {
             const clonedSeen = new Set(currentTxids);
             if (newTxids.size > 0) {
-              debug(`new txids synced from pg %O`, Array.from(newTxids));
+              debug(
+                `${collectionId ? `[${collectionId}] ` : ``}new txids synced from pg %O`,
+                Array.from(newTxids)
+              );
             }
             newTxids.forEach((txid) => clonedSeen.add(txid));
             newTxids.clear();
@@ -236,11 +375,15 @@ You can provide an 'onError' handler on the shapeOptions to handle this error, a
           seenSnapshots.setState((currentSnapshots) => {
             const seen = [...currentSnapshots, ...newSnapshots];
             newSnapshots.forEach(
-              (snapshot) => debug(`new snapshot synced from pg %o`, snapshot)
+              (snapshot) => debug(
+                `${collectionId ? `[${collectionId}] ` : ``}new snapshot synced from pg %o`,
+                snapshot
+              )
             );
             newSnapshots.length = 0;
             return seen;
           });
+          resolveMatchedPendingMatches();
         }
       });
       return () => {
@@ -253,6 +396,8 @@ You can provide an 'onError' handler on the shapeOptions to handle this error, a
   };
 }
 export {
-  electricCollectionOptions
+  electricCollectionOptions,
+  isChangeMessage2 as isChangeMessage,
+  isControlMessage2 as isControlMessage
 };
 //# sourceMappingURL=electric.js.map