From 8c7ff520d87b6d6861dc77b67297e63f350cb1d5 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 11 Nov 2025 15:56:24 +0000 Subject: [PATCH 1/4] Add timeout support to electricCollectionOptions This change allows users to specify a custom timeout when returning txids from mutation handlers (onInsert, onUpdate, onDelete). Previously, users could only customize timeouts when manually calling collection.utils.awaitTxId(), but not when using the automatic txid matching strategy via electricCollectionOptions. Changes: - Updated MatchingStrategy type to include optional timeout property - Modified processMatchingStrategy to extract and pass timeout to awaitTxId - Added documentation example showing how to use custom timeout - Updated JSDoc comments for mutation handlers This addresses the feature request in GitHub discussion #794. Default timeout remains 5000ms when not specified. --- .../electric-db-collection/src/electric.ts | 31 ++++++++++++++----- 1 file changed, 24 insertions(+), 7 deletions(-) diff --git a/packages/electric-db-collection/src/electric.ts b/packages/electric-db-collection/src/electric.ts index bdd6f34a7..147204f08 100644 --- a/packages/electric-db-collection/src/electric.ts +++ b/packages/electric-db-collection/src/electric.ts @@ -52,10 +52,16 @@ export type MatchFunction> = ( /** * Matching strategies for Electric synchronization * Handlers can return: - * - Txid strategy: { txid: number | number[] } (recommended) + * - Txid strategy: { txid: number | number[], timeout?: number } (recommended) * - Void (no return value) - mutation completes without waiting + * + * The optional timeout property specifies how long to wait for the txid(s) in milliseconds. + * If not specified, defaults to 5000ms. */ -export type MatchingStrategy = { txid: Txid | Array } | void +export type MatchingStrategy = { + txid: Txid | Array + timeout?: number +} | void /** * Type representing a snapshot end message @@ -92,7 +98,7 @@ export interface ElectricCollectionConfig< /** * Optional asynchronous handler function called before an insert operation * @param params Object containing transaction and collection information - * @returns Promise resolving to { txid } or void + * @returns Promise resolving to { txid, timeout? } or void * @example * // Basic Electric insert handler with txid (recommended) * onInsert: async ({ transaction }) => { @@ -104,6 +110,16 @@ export interface ElectricCollectionConfig< * } * * @example + * // Insert handler with custom timeout + * onInsert: async ({ transaction }) => { + * const newItem = transaction.mutations[0].modified + * const result = await api.todos.create({ + * data: newItem + * }) + * return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds + * } + * + * @example * // Insert handler with multiple items - return array of txids * onInsert: async ({ transaction }) => { * const items = transaction.mutations.map(m => m.modified) @@ -130,7 +146,7 @@ export interface ElectricCollectionConfig< /** * Optional asynchronous handler function called before an update operation * @param params Object containing transaction and collection information - * @returns Promise resolving to { txid } or void + * @returns Promise resolving to { txid, timeout? } or void * @example * // Basic Electric update handler with txid (recommended) * onUpdate: async ({ transaction }) => { @@ -159,7 +175,7 @@ export interface ElectricCollectionConfig< /** * Optional asynchronous handler function called before a delete operation * @param params Object containing transaction and collection information - * @returns Promise resolving to { txid } or void + * @returns Promise resolving to { txid, timeout? } or void * @example * // Basic Electric delete handler with txid (recommended) * onDelete: async ({ transaction }) => { @@ -504,11 +520,12 @@ export function electricCollectionOptions( ): Promise => { // Only wait if result contains txid if (result && `txid` in result) { + const timeout = result.timeout // Handle both single txid and array of txids if (Array.isArray(result.txid)) { - await Promise.all(result.txid.map(awaitTxId)) + await Promise.all(result.txid.map((txid) => awaitTxId(txid, timeout))) } else { - await awaitTxId(result.txid) + await awaitTxId(result.txid, timeout) } } // If result is void/undefined, don't wait - mutation completes immediately From c108bd76a32cf2fbd8d751599464d479c90f3586 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 11 Nov 2025 16:04:53 +0000 Subject: [PATCH 2/4] Add test and changeset for timeout support - Add new test to verify custom timeout in matching strategy - Test ensures timeout is properly passed to awaitTxId and triggers timeout error - Add changeset documenting the new timeout feature as a minor release All 60 tests passing including the new timeout test. --- .changeset/add-timeout-support-electric.md | 25 +++++++++++++++ .../tests/electric.test.ts | 31 +++++++++++++++++++ 2 files changed, 56 insertions(+) create mode 100644 .changeset/add-timeout-support-electric.md diff --git a/.changeset/add-timeout-support-electric.md b/.changeset/add-timeout-support-electric.md new file mode 100644 index 000000000..144e6eae2 --- /dev/null +++ b/.changeset/add-timeout-support-electric.md @@ -0,0 +1,25 @@ +--- +"@tanstack/electric-db-collection": minor +--- + +Add timeout support to electricCollectionOptions matching strategies. You can now specify a custom timeout when returning txids from mutation handlers (onInsert, onUpdate, onDelete). + +Previously, users could only customize timeouts when manually calling `collection.utils.awaitTxId()`, but not when using the automatic txid matching strategy. + +**Example:** + +```ts +const collection = createCollection( + electricCollectionOptions({ + // ... other config + onInsert: async ({ transaction }) => { + const newItem = transaction.mutations[0].modified + const result = await api.todos.create({ data: newItem }) + // Specify custom timeout (in milliseconds) + return { txid: result.txid, timeout: 10000 } + }, + }) +) +``` + +The timeout parameter is optional and defaults to 5000ms when not specified. It works with both single txids and arrays of txids. diff --git a/packages/electric-db-collection/tests/electric.test.ts b/packages/electric-db-collection/tests/electric.test.ts index bf059a021..564ec6f75 100644 --- a/packages/electric-db-collection/tests/electric.test.ts +++ b/packages/electric-db-collection/tests/electric.test.ts @@ -667,6 +667,37 @@ describe(`Electric Integration`, () => { expect(onInsert).toHaveBeenCalled() }) + it(`should support custom timeout in matching strategy`, async () => { + const onInsert = vi.fn(async () => { + // Return a txid that will never arrive with a very short timeout + return { txid: 999999, timeout: 100 } + }) + + const config = { + id: `test-custom-timeout`, + shapeOptions: { + url: `http://test-url`, + params: { table: `test_table` }, + }, + startSync: true, + getKey: (item: Row) => item.id as number, + onInsert, + } + + const testCollection = createCollection(electricCollectionOptions(config)) + + // Insert data - should timeout after 100ms + const tx = testCollection.insert({ id: 1, name: `Timeout Test` }) + + // Verify that our onInsert handler was called + expect(onInsert).toHaveBeenCalled() + + // The transaction should reject due to timeout + await expect(tx.isPersisted.promise).rejects.toThrow( + `Timeout waiting for txId: 999999` + ) + }) + it(`should support custom match function using awaitMatch utility`, async () => { let resolveCustomMatch: () => void const customMatchPromise = new Promise((resolve) => { From 893acda2fab0858fd03db75aed0e731897fc033d Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 11 Nov 2025 16:19:10 +0000 Subject: [PATCH 3/4] docs: regenerate API documentation --- .../classes/ElectricDBCollectionError.md | 4 +-- .../classes/ExpectedNumberInAwaitTxIdError.md | 4 +-- .../classes/StreamAbortedError.md | 4 +-- .../classes/TimeoutWaitingForMatchError.md | 4 +-- .../classes/TimeoutWaitingForTxIdError.md | 4 +-- .../functions/electricCollectionOptions.md | 4 +-- .../interfaces/ElectricCollectionConfig.md | 27 +++++++++++++------ .../interfaces/ElectricCollectionUtils.md | 6 ++--- .../type-aliases/AwaitTxIdFn.md | 2 +- .../type-aliases/Txid.md | 2 +- 10 files changed, 36 insertions(+), 25 deletions(-) diff --git a/docs/reference/electric-db-collection/classes/ElectricDBCollectionError.md b/docs/reference/electric-db-collection/classes/ElectricDBCollectionError.md index 8ec928746..4ded4090d 100644 --- a/docs/reference/electric-db-collection/classes/ElectricDBCollectionError.md +++ b/docs/reference/electric-db-collection/classes/ElectricDBCollectionError.md @@ -5,7 +5,7 @@ title: ElectricDBCollectionError # Class: ElectricDBCollectionError -Defined in: [packages/electric-db-collection/src/errors.ts:4](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/errors.ts#L4) +Defined in: packages/electric-db-collection/src/errors.ts:4 ## Extends @@ -26,7 +26,7 @@ Defined in: [packages/electric-db-collection/src/errors.ts:4](https://github.com new ElectricDBCollectionError(message, collectionId?): ElectricDBCollectionError; ``` -Defined in: [packages/electric-db-collection/src/errors.ts:5](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/errors.ts#L5) +Defined in: packages/electric-db-collection/src/errors.ts:5 #### Parameters diff --git a/docs/reference/electric-db-collection/classes/ExpectedNumberInAwaitTxIdError.md b/docs/reference/electric-db-collection/classes/ExpectedNumberInAwaitTxIdError.md index a0c31569e..4190837a5 100644 --- a/docs/reference/electric-db-collection/classes/ExpectedNumberInAwaitTxIdError.md +++ b/docs/reference/electric-db-collection/classes/ExpectedNumberInAwaitTxIdError.md @@ -5,7 +5,7 @@ title: ExpectedNumberInAwaitTxIdError # Class: ExpectedNumberInAwaitTxIdError -Defined in: [packages/electric-db-collection/src/errors.ts:11](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/errors.ts#L11) +Defined in: packages/electric-db-collection/src/errors.ts:11 ## Extends @@ -19,7 +19,7 @@ Defined in: [packages/electric-db-collection/src/errors.ts:11](https://github.co new ExpectedNumberInAwaitTxIdError(txIdType, collectionId?): ExpectedNumberInAwaitTxIdError; ``` -Defined in: [packages/electric-db-collection/src/errors.ts:12](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/errors.ts#L12) +Defined in: packages/electric-db-collection/src/errors.ts:12 #### Parameters diff --git a/docs/reference/electric-db-collection/classes/StreamAbortedError.md b/docs/reference/electric-db-collection/classes/StreamAbortedError.md index d08f6639f..997cec4ef 100644 --- a/docs/reference/electric-db-collection/classes/StreamAbortedError.md +++ b/docs/reference/electric-db-collection/classes/StreamAbortedError.md @@ -5,7 +5,7 @@ title: StreamAbortedError # Class: StreamAbortedError -Defined in: [packages/electric-db-collection/src/errors.ts:32](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/errors.ts#L32) +Defined in: packages/electric-db-collection/src/errors.ts:32 ## Extends @@ -19,7 +19,7 @@ Defined in: [packages/electric-db-collection/src/errors.ts:32](https://github.co new StreamAbortedError(collectionId?): StreamAbortedError; ``` -Defined in: [packages/electric-db-collection/src/errors.ts:33](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/errors.ts#L33) +Defined in: packages/electric-db-collection/src/errors.ts:33 #### Parameters diff --git a/docs/reference/electric-db-collection/classes/TimeoutWaitingForMatchError.md b/docs/reference/electric-db-collection/classes/TimeoutWaitingForMatchError.md index 2cfd78e55..b390865c8 100644 --- a/docs/reference/electric-db-collection/classes/TimeoutWaitingForMatchError.md +++ b/docs/reference/electric-db-collection/classes/TimeoutWaitingForMatchError.md @@ -5,7 +5,7 @@ title: TimeoutWaitingForMatchError # Class: TimeoutWaitingForMatchError -Defined in: [packages/electric-db-collection/src/errors.ts:25](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/errors.ts#L25) +Defined in: packages/electric-db-collection/src/errors.ts:25 ## Extends @@ -19,7 +19,7 @@ Defined in: [packages/electric-db-collection/src/errors.ts:25](https://github.co new TimeoutWaitingForMatchError(collectionId?): TimeoutWaitingForMatchError; ``` -Defined in: [packages/electric-db-collection/src/errors.ts:26](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/errors.ts#L26) +Defined in: packages/electric-db-collection/src/errors.ts:26 #### Parameters diff --git a/docs/reference/electric-db-collection/classes/TimeoutWaitingForTxIdError.md b/docs/reference/electric-db-collection/classes/TimeoutWaitingForTxIdError.md index 5f7f76187..ae570ef98 100644 --- a/docs/reference/electric-db-collection/classes/TimeoutWaitingForTxIdError.md +++ b/docs/reference/electric-db-collection/classes/TimeoutWaitingForTxIdError.md @@ -5,7 +5,7 @@ title: TimeoutWaitingForTxIdError # Class: TimeoutWaitingForTxIdError -Defined in: [packages/electric-db-collection/src/errors.ts:18](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/errors.ts#L18) +Defined in: packages/electric-db-collection/src/errors.ts:18 ## Extends @@ -19,7 +19,7 @@ Defined in: [packages/electric-db-collection/src/errors.ts:18](https://github.co new TimeoutWaitingForTxIdError(txId, collectionId?): TimeoutWaitingForTxIdError; ``` -Defined in: [packages/electric-db-collection/src/errors.ts:19](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/errors.ts#L19) +Defined in: packages/electric-db-collection/src/errors.ts:19 #### Parameters diff --git a/docs/reference/electric-db-collection/functions/electricCollectionOptions.md b/docs/reference/electric-db-collection/functions/electricCollectionOptions.md index b2d1ecbac..73170f7c0 100644 --- a/docs/reference/electric-db-collection/functions/electricCollectionOptions.md +++ b/docs/reference/electric-db-collection/functions/electricCollectionOptions.md @@ -11,7 +11,7 @@ title: electricCollectionOptions function electricCollectionOptions(config): CollectionConfig, string | number, T, UtilsRecord> & object; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:254](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L254) +Defined in: packages/electric-db-collection/src/electric.ts:270 Creates Electric collection options for use with a standard Collection @@ -43,7 +43,7 @@ Collection options with utilities function electricCollectionOptions(config): CollectionConfig & object; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:265](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L265) +Defined in: packages/electric-db-collection/src/electric.ts:281 Creates Electric collection options for use with a standard Collection diff --git a/docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig.md b/docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig.md index 8af918787..ee5c7b8ef 100644 --- a/docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig.md +++ b/docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig.md @@ -5,7 +5,7 @@ title: ElectricCollectionConfig # Interface: ElectricCollectionConfig\ -Defined in: [packages/electric-db-collection/src/electric.ts:80](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L80) +Defined in: packages/electric-db-collection/src/electric.ts:86 Configuration interface for Electric collection options @@ -35,7 +35,7 @@ The schema type for validation optional onDelete: (params) => Promise; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:185](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L185) +Defined in: packages/electric-db-collection/src/electric.ts:201 Optional asynchronous handler function called before a delete operation @@ -51,7 +51,7 @@ Object containing transaction and collection information `Promise`\<`MatchingStrategy`\> -Promise resolving to { txid } or void +Promise resolving to { txid, timeout? } or void #### Examples @@ -87,7 +87,7 @@ onDelete: async ({ transaction, collection }) => { optional onInsert: (params) => Promise; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:128](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L128) +Defined in: packages/electric-db-collection/src/electric.ts:144 Optional asynchronous handler function called before an insert operation @@ -103,7 +103,7 @@ Object containing transaction and collection information `Promise`\<`MatchingStrategy`\> -Promise resolving to { txid } or void +Promise resolving to { txid, timeout? } or void #### Examples @@ -118,6 +118,17 @@ onInsert: async ({ transaction }) => { } ``` +```ts +// Insert handler with custom timeout +onInsert: async ({ transaction }) => { + const newItem = transaction.mutations[0].modified + const result = await api.todos.create({ + data: newItem + }) + return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds +} +``` + ```ts // Insert handler with multiple items - return array of txids onInsert: async ({ transaction }) => { @@ -150,7 +161,7 @@ onInsert: async ({ transaction, collection }) => { optional onUpdate: (params) => Promise; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:157](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L157) +Defined in: packages/electric-db-collection/src/electric.ts:173 Optional asynchronous handler function called before an update operation @@ -166,7 +177,7 @@ Object containing transaction and collection information `Promise`\<`MatchingStrategy`\> -Promise resolving to { txid } or void +Promise resolving to { txid, timeout? } or void #### Examples @@ -203,6 +214,6 @@ onUpdate: async ({ transaction, collection }) => { shapeOptions: ShapeStreamOptions>; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:90](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L90) +Defined in: packages/electric-db-collection/src/electric.ts:96 Configuration options for the ElectricSQL ShapeStream diff --git a/docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md b/docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md index ed955d29a..1ffacd01d 100644 --- a/docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md +++ b/docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md @@ -5,7 +5,7 @@ title: ElectricCollectionUtils # Interface: ElectricCollectionUtils\ -Defined in: [packages/electric-db-collection/src/electric.ts:237](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L237) +Defined in: packages/electric-db-collection/src/electric.ts:253 Electric collection utilities type @@ -33,7 +33,7 @@ Electric collection utilities type awaitMatch: AwaitMatchFn; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:240](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L240) +Defined in: packages/electric-db-collection/src/electric.ts:256 *** @@ -43,4 +43,4 @@ Defined in: [packages/electric-db-collection/src/electric.ts:240](https://github awaitTxId: AwaitTxIdFn; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:239](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L239) +Defined in: packages/electric-db-collection/src/electric.ts:255 diff --git a/docs/reference/electric-db-collection/type-aliases/AwaitTxIdFn.md b/docs/reference/electric-db-collection/type-aliases/AwaitTxIdFn.md index 4501b500b..dc00f915c 100644 --- a/docs/reference/electric-db-collection/type-aliases/AwaitTxIdFn.md +++ b/docs/reference/electric-db-collection/type-aliases/AwaitTxIdFn.md @@ -9,7 +9,7 @@ title: AwaitTxIdFn type AwaitTxIdFn = (txId, timeout?) => Promise; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:224](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L224) +Defined in: packages/electric-db-collection/src/electric.ts:240 Type for the awaitTxId utility function diff --git a/docs/reference/electric-db-collection/type-aliases/Txid.md b/docs/reference/electric-db-collection/type-aliases/Txid.md index 09c5cc47f..e19ec26f5 100644 --- a/docs/reference/electric-db-collection/type-aliases/Txid.md +++ b/docs/reference/electric-db-collection/type-aliases/Txid.md @@ -9,6 +9,6 @@ title: Txid type Txid = number; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:42](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L42) +Defined in: packages/electric-db-collection/src/electric.ts:42 Type representing a transaction ID in ElectricSQL From c0a8ee09eeaa74a410ed4d483c09fe9bf2ba5a26 Mon Sep 17 00:00:00 2001 From: Claude Date: Wed, 12 Nov 2025 00:52:10 +0000 Subject: [PATCH 4/4] docs: update electric-db-collection docs after merge with main --- .../functions/electricCollectionOptions.md | 4 +-- .../interfaces/ElectricCollectionConfig.md | 29 +++++++++++++------ .../interfaces/ElectricCollectionUtils.md | 6 ++-- .../type-aliases/AwaitTxIdFn.md | 2 +- .../type-aliases/Txid.md | 2 +- 5 files changed, 27 insertions(+), 16 deletions(-) diff --git a/docs/reference/electric-db-collection/functions/electricCollectionOptions.md b/docs/reference/electric-db-collection/functions/electricCollectionOptions.md index 1d12a115d..fb9f9754e 100644 --- a/docs/reference/electric-db-collection/functions/electricCollectionOptions.md +++ b/docs/reference/electric-db-collection/functions/electricCollectionOptions.md @@ -11,7 +11,7 @@ title: electricCollectionOptions function electricCollectionOptions(config): CollectionConfig, string | number, T, UtilsRecord> & object; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:277](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L277) +Defined in: packages/electric-db-collection/src/electric.ts:293 Creates Electric collection options for use with a standard Collection @@ -43,7 +43,7 @@ Collection options with utilities function electricCollectionOptions(config): CollectionConfig & object; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:288](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L288) +Defined in: packages/electric-db-collection/src/electric.ts:304 Creates Electric collection options for use with a standard Collection diff --git a/docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig.md b/docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig.md index 5bf6b0af6..cbbf1d294 100644 --- a/docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig.md +++ b/docs/reference/electric-db-collection/interfaces/ElectricCollectionConfig.md @@ -5,7 +5,7 @@ title: ElectricCollectionConfig # Interface: ElectricCollectionConfig\ -Defined in: [packages/electric-db-collection/src/electric.ts:102](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L102) +Defined in: packages/electric-db-collection/src/electric.ts:108 Configuration interface for Electric collection options @@ -35,7 +35,7 @@ The schema type for validation optional onDelete: (params) => Promise; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:208](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L208) +Defined in: packages/electric-db-collection/src/electric.ts:224 Optional asynchronous handler function called before a delete operation @@ -51,7 +51,7 @@ Object containing transaction and collection information `Promise`\<`MatchingStrategy`\> -Promise resolving to { txid } or void +Promise resolving to { txid, timeout? } or void #### Examples @@ -87,7 +87,7 @@ onDelete: async ({ transaction, collection }) => { optional onInsert: (params) => Promise; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:151](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L151) +Defined in: packages/electric-db-collection/src/electric.ts:167 Optional asynchronous handler function called before an insert operation @@ -103,7 +103,7 @@ Object containing transaction and collection information `Promise`\<`MatchingStrategy`\> -Promise resolving to { txid } or void +Promise resolving to { txid, timeout? } or void #### Examples @@ -118,6 +118,17 @@ onInsert: async ({ transaction }) => { } ``` +```ts +// Insert handler with custom timeout +onInsert: async ({ transaction }) => { + const newItem = transaction.mutations[0].modified + const result = await api.todos.create({ + data: newItem + }) + return { txid: result.txid, timeout: 10000 } // Wait up to 10 seconds +} +``` + ```ts // Insert handler with multiple items - return array of txids onInsert: async ({ transaction }) => { @@ -150,7 +161,7 @@ onInsert: async ({ transaction, collection }) => { optional onUpdate: (params) => Promise; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:180](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L180) +Defined in: packages/electric-db-collection/src/electric.ts:196 Optional asynchronous handler function called before an update operation @@ -166,7 +177,7 @@ Object containing transaction and collection information `Promise`\<`MatchingStrategy`\> -Promise resolving to { txid } or void +Promise resolving to { txid, timeout? } or void #### Examples @@ -203,7 +214,7 @@ onUpdate: async ({ transaction, collection }) => { shapeOptions: ShapeStreamOptions>; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:112](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L112) +Defined in: packages/electric-db-collection/src/electric.ts:118 Configuration options for the ElectricSQL ShapeStream @@ -215,4 +226,4 @@ Configuration options for the ElectricSQL ShapeStream optional syncMode: ElectricSyncMode; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:113](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L113) +Defined in: packages/electric-db-collection/src/electric.ts:119 diff --git a/docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md b/docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md index 569809ba5..4e7e1b920 100644 --- a/docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md +++ b/docs/reference/electric-db-collection/interfaces/ElectricCollectionUtils.md @@ -5,7 +5,7 @@ title: ElectricCollectionUtils # Interface: ElectricCollectionUtils\ -Defined in: [packages/electric-db-collection/src/electric.ts:260](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L260) +Defined in: packages/electric-db-collection/src/electric.ts:276 Electric collection utilities type @@ -33,7 +33,7 @@ Electric collection utilities type awaitMatch: AwaitMatchFn; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:263](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L263) +Defined in: packages/electric-db-collection/src/electric.ts:279 *** @@ -43,4 +43,4 @@ Defined in: [packages/electric-db-collection/src/electric.ts:263](https://github awaitTxId: AwaitTxIdFn; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:262](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L262) +Defined in: packages/electric-db-collection/src/electric.ts:278 diff --git a/docs/reference/electric-db-collection/type-aliases/AwaitTxIdFn.md b/docs/reference/electric-db-collection/type-aliases/AwaitTxIdFn.md index f2a8589aa..aab4e10a9 100644 --- a/docs/reference/electric-db-collection/type-aliases/AwaitTxIdFn.md +++ b/docs/reference/electric-db-collection/type-aliases/AwaitTxIdFn.md @@ -9,7 +9,7 @@ title: AwaitTxIdFn type AwaitTxIdFn = (txId, timeout?) => Promise; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:247](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L247) +Defined in: packages/electric-db-collection/src/electric.ts:263 Type for the awaitTxId utility function diff --git a/docs/reference/electric-db-collection/type-aliases/Txid.md b/docs/reference/electric-db-collection/type-aliases/Txid.md index 306d044da..ca074cdaf 100644 --- a/docs/reference/electric-db-collection/type-aliases/Txid.md +++ b/docs/reference/electric-db-collection/type-aliases/Txid.md @@ -9,6 +9,6 @@ title: Txid type Txid = number; ``` -Defined in: [packages/electric-db-collection/src/electric.ts:46](https://github.com/TanStack/db/blob/main/packages/electric-db-collection/src/electric.ts#L46) +Defined in: packages/electric-db-collection/src/electric.ts:46 Type representing a transaction ID in ElectricSQL