From d9a0c6ce01a544911fb76bb26eaa6c3053a77a69 Mon Sep 17 00:00:00 2001 From: Jaime Resano Date: Fri, 13 Nov 2026 23:33:43 +0100 Subject: [PATCH 1/4] feat(db): export withPublicationContext for sync sources A sync source that commits sync transactions to several Collections for one source state can commit them inside one publication, so live queries that read them run after the last commit and publish one batch. Documents what it does not promise (atomic publication across the Collections) and that a throwing callback discards the queued live-query work. Adds tests through the package export and a benchmark of both ways to commit. Co-Authored-By: Claude Opus 5.5 --- .changeset/export-with-publication-context.md | 5 + docs/guides/collection-options-creator.md | 22 ++ packages/db/src/index.ts | 1 + packages/db/src/scheduler.ts | 14 + packages/db/tests/query/scheduler.test.ts | 139 ++++++++- scripts/bench/multi-collection-sync.ts | 263 ++++++++++++++++++ 6 files changed, 443 insertions(+), 1 deletion(-) create mode 100644 .changeset/export-with-publication-context.md create mode 100644 scripts/bench/multi-collection-sync.ts diff --git a/.changeset/export-with-publication-context.md b/.changeset/export-with-publication-context.md new file mode 100644 index 0000000000..5e42243701 --- /dev/null +++ b/.changeset/export-with-publication-context.md @@ -0,0 +1,5 @@ +--- +'@tanstack/db': minor +--- + +Export `withPublicationContext`. A sync source that commits sync transactions to several Collections for one source state, such as one server checkpoint, can commit them inside one call: every live query that reads those Collections then runs after the last commit and publishes one batch, instead of running and publishing an intermediate result after each commit. Each Collection still notifies its own change subscribers when it commits, so this is not an atomic publication across the Collections. diff --git a/docs/guides/collection-options-creator.md b/docs/guides/collection-options-creator.md index f362cea00c..5a63267460 100644 --- a/docs/guides/collection-options-creator.md +++ b/docs/guides/collection-options-creator.md @@ -178,6 +178,28 @@ The sync process follows this lifecycle: 6. **reportError(error)** - After the Collection is ready, report a sync problem while you keep trying. It sets the node's `failureReason` without changing its status or rows 7. **reportHealthy()** - After the Collection is ready, report that sync works again. It clears the `failureReason`, and does nothing when nothing is wrong +### Committing several Collections together + +A source that syncs several Collections over one connection often receives one source state for all of them, such as one server checkpoint. Committed one by one, every live query that joins those Collections runs after each commit and publishes a result over Collections that only some of the commits have reached. Commit them inside one `withPublicationContext` call instead: + +```typescript +import { withPublicationContext } from '@tanstack/db' + +withPublicationContext(() => { + for (const { sync, changes } of collectionsInCheckpoint) { + try { + sync.begin() + for (const change of changes) sync.write(change) + sync.commit() + } catch (error) { + sync.fail(error) + } + } +}) +``` + +Live queries then run after the last commit and publish one batch. Each Collection still notifies its own change subscribers when it commits, so this is not an atomic publication across the Collections. Catch each commit's failure inside the callback: if the callback throws, the live-query work of the commits it already made is discarded, and those live queries miss them until their sources change again. + ### Reporting failures Users see two separate signals: whether data can be shown, and whether it is diff --git a/packages/db/src/index.ts b/packages/db/src/index.ts index dbea33cfad..8f8ede2af7 100644 --- a/packages/db/src/index.ts +++ b/packages/db/src/index.ts @@ -46,6 +46,7 @@ export { deleteDatabase, } from './indexed-db-wrapper' export * from './errors' +export { withPublicationContext } from './scheduler' /** @internal Unstable protocol for persistence-aware collection adapters. */ export * from './sync-persistence' export * from './sync-receipt' diff --git a/packages/db/src/scheduler.ts b/packages/db/src/scheduler.ts index 9fb1a08493..deb452728f 100644 --- a/packages/db/src/scheduler.ts +++ b/packages/db/src/scheduler.ts @@ -184,6 +184,20 @@ export function recordPublicationError(error: unknown): void { * Runs one synchronous Collection publication inside a scheduler context. * Nested publications share the outer context, so downstream live queries run * only after every subscriber to the original committed batch has observed it. + * + * A sync source that commits sync transactions to several Collections for one + * source state, such as one server checkpoint, can commit them inside one call. + * Every live query that observes those Collections then runs after `publish` + * returns, with every commit applied, and publishes one batch. Committed one by + * one, a live query that joins them runs and publishes after each commit, over + * Collections that only some of the commits have reached. + * + * Each Collection still applies its sync transaction and notifies its own + * change subscribers when it commits, so this is not an atomic publication + * across the Collections. A failure that a change subscriber reports is thrown + * from this call after the graphs ran. When `publish` itself throws, the queued + * graph work is discarded, so live queries miss the commits that `publish` + * already made: catch each commit's own failure inside `publish`. */ export function withPublicationContext(publish: () => T): T { if (activePublicationContext !== undefined) return publish() diff --git a/packages/db/tests/query/scheduler.test.ts b/packages/db/tests/query/scheduler.test.ts index 76a82bee8e..f40a37c249 100644 --- a/packages/db/tests/query/scheduler.test.ts +++ b/packages/db/tests/query/scheduler.test.ts @@ -19,7 +19,11 @@ import { import { CollectionConfigBuilder } from '../../src/query/live/collection-config-builder.js' import { getCollectionBuilder } from '../../src/query/live/collection-registry.js' import { CollectionSubscriber } from '../../src/query/live/collection-subscriber.js' -import { Query, createEffect } from '../../src/index.js' +import { + Query, + createEffect, + withPublicationContext as publicWithPublicationContext, +} from '../../src/index.js' import { flushPromises, mockSyncCollectionOptions, @@ -341,6 +345,139 @@ describe(`Collection publication scheduler context`, () => { ) }) +describe(`sync transactions of several Collections in one publication`, () => { + type SyncOperations = Parameters[`sync`]>[0] + + // A left join shows a row for a user whose tasks have not arrived, so a live + // query that runs between the two commits publishes that intermediate row + async function setupJoinedSources(id: string) { + let usersSync!: SyncOperations + let tasksSync!: SyncOperations + const users = createCollection({ + id: `${id}-users`, + getKey: (user) => user.id, + startSync: true, + sync: { + sync: (operations) => { + usersSync = operations + operations.markReady() + }, + }, + }) + const tasks = createCollection({ + id: `${id}-tasks`, + getKey: (task) => task.id, + startSync: true, + sync: { + sync: (operations) => { + tasksSync = operations + operations.markReady() + }, + }, + }) + const assignments = createLiveQueryCollection({ + id: `${id}-assignments`, + startSync: true, + query: (q) => + q + .from({ user: users }) + .join( + { task: tasks }, + ({ user, task }) => eq(user.id, task.userId), + `left`, + ) + .select(({ user, task }) => ({ + name: user.name, + title: task.title, + })), + }) + await assignments.preload() + const commitUser = (user: User) => { + usersSync.begin() + usersSync.write({ type: `insert`, value: user }) + usersSync.commit() + } + const commitTask = (task: Task) => { + tasksSync.begin() + tasksSync.write({ type: `insert`, value: task }) + tasksSync.commit() + } + const rows = () => assignments.toArray.map((row) => stripVirtualProps(row)) + return { users, tasks, assignments, commitUser, commitTask, rows } + } + + it(`publishes a joining live query once, after every commit applied`, async () => { + const { users, tasks, assignments, commitUser, commitTask, rows } = + await setupJoinedSources(`publication-batch`) + const order: Array = [] + const subscriptions = [ + users.subscribeChanges(() => order.push(`users`)), + tasks.subscribeChanges(() => order.push(`tasks`)), + assignments.subscribeChanges((changes) => + order.push( + `assignments ${JSON.stringify(changes.map(({ type }) => type))}`, + ), + ), + ] + + publicWithPublicationContext(() => { + commitUser({ id: 1, name: `Ada` }) + commitTask({ id: 1, userId: 1, title: `Review` }) + expect(rows()).toEqual([]) + }) + + expect(rows()).toEqual([{ name: `Ada`, title: `Review` }]) + // Not an atomic publication: each Collection notifies its own subscribers + // when it commits + expect(order).toEqual([`users`, `tasks`, `assignments ["insert"]`]) + for (const subscription of subscriptions) subscription.unsubscribe() + }) + + it(`publishes the intermediate join of each commit without one`, async () => { + const { assignments, commitUser, commitTask, rows } = + await setupJoinedSources(`publication-per-commit`) + const published: Array = [] + const subscription = assignments.subscribeChanges((changes) => + published.push( + changes.map(({ type, value }) => ({ + type, + ...stripVirtualProps(value), + })), + ), + ) + + commitUser({ id: 1, name: `Ada` }) + commitTask({ id: 1, userId: 1, title: `Review` }) + + expect(published).toEqual([ + [{ type: `insert`, name: `Ada`, title: undefined }], + [ + { type: `insert`, name: `Ada`, title: `Review` }, + { type: `delete`, name: `Ada`, title: undefined }, + ], + ]) + expect(rows()).toEqual([{ name: `Ada`, title: `Review` }]) + subscription.unsubscribe() + }) + + it(`discards the live-query work of earlier commits when publish throws`, async () => { + const { users, commitUser, commitTask, rows } = + await setupJoinedSources(`publication-throws`) + const failure = new Error(`source failed after a commit`) + + expect(() => + publicWithPublicationContext(() => { + commitUser({ id: 1, name: `Ada` }) + commitTask({ id: 1, userId: 1, title: `Review` }) + throw failure + }), + ).toThrow(failure) + + expect(users.size).toBe(1) + expect(rows()).toEqual([]) + }) +}) + describe(`live query scheduler`, () => { it(`does not deliver a source batch after a snapshotted listener unsubscribes`, async () => { let begin!: () => void diff --git a/scripts/bench/multi-collection-sync.ts b/scripts/bench/multi-collection-sync.ts new file mode 100644 index 0000000000..417bcc0ed4 --- /dev/null +++ b/scripts/bench/multi-collection-sync.ts @@ -0,0 +1,263 @@ +// Measures a sync source that applies one source state to several Collections, +// such as one server checkpoint: each Collection's sync transaction committed on +// its own, or all of them inside one withPublicationContext call. Run it through +// the production runner after building db and db-ivm: +// +// pnpm --filter @tanstack/db-ivm --filter @tanstack/db build +// node --expose-gc scripts/bench/production.mjs scripts/bench/multi-collection-sync.ts \ +// --repetitions=7 --warmup=2 +// +// One fact Collection joins every dimension Collection, with inner or left +// joins, on Collections that index the joined columns automatically (as +// incremental-update.ts's `auto` mode) or not at all. A case applies a +// checkpoint with every row (startup), then one that +// updates 1% of every Collection's rows. The source commits the fact Collection +// first or last: which one a source does decides how much an intermediate join +// costs. Both modes run on the same bundle, on fresh fixtures built from the +// same seed, in an order that alternates per repetition. Each repetition +// asserts that both modes end with the same live-query rows. +import assert from 'node:assert/strict' +import { + BTreeIndex, + createCollection, + createLiveQueryCollection, + eq, + withPublicationContext, +} from '../../packages/db/src/index.js' +import type { + ChangeMessageOrDeleteKeyMessage, + SyncConfig, +} from '../../packages/db/src/index.js' + +type Row = { id: number; value: number } & Record<`fk${number}`, number> +type SyncOperations = Parameters[`sync`]>[0] +type Mode = `one commit at a time` | `withPublicationContext` +type Join = `inner` | `left` +type FactOrder = `fact first` | `fact last` +type IndexMode = `auto` | `off` +type Case = { + collections: number + factRows: number + join: Join + factOrder: FactOrder + indexMode: IndexMode +} +type Checkpoint = Array>> +type Result = { + startupMs: number + startupBatches: number + updateMs: number + updateBatches: number + rows: string +} + +const argument = (name: string, fallback: number) => { + const match = process.argv.find((value) => value.startsWith(`--${name}=`)) + return match === undefined ? fallback : Number(match.split(`=`)[1]) +} +const repetitions = argument(`repetitions`, 7) +const warmup = argument(`warmup`, 2) +const modes: Array = [`one commit at a time`, `withPublicationContext`] +const FACT_ROWS = 10_000 +const cases: Array = ([`auto`, `off`] as const).flatMap((indexMode) => + [2, 4, 8].flatMap((collections) => + ([`inner`, `left`] as const).flatMap((join) => + ([`fact first`, `fact last`] as const).map((factOrder) => ({ + collections, + factRows: FACT_ROWS, + join, + factOrder, + indexMode, + })), + ), + ), +) +const DIMENSION_ROWS_PER_FACT_ROW = 0.1 +const UPDATED_SHARE = 0.01 + +// Deterministic, so every mode and repetition gets the same rows +function random(seed: number) { + let state = seed + return () => { + state = (state * 1_103_515_245 + 12_345) % 2_147_483_648 + return state / 2_147_483_648 + } +} + +function createFixture({ collections, factRows, join, indexMode }: Case) { + const dimensionRows = Math.max( + 1, + Math.round(factRows * DIMENSION_ROWS_PER_FACT_ROW), + ) + const syncs: Array = [] + const sources = Array.from({ length: collections }, (_, index) => + createCollection({ + id: `source-${index}-${Math.random()}`, + getKey: (row) => row.id, + autoIndex: indexMode === `auto` ? `eager` : `off`, + defaultIndexType: BTreeIndex, + startSync: true, + sync: { + sync: (operations) => { + syncs[index] = operations + operations.markReady() + }, + }, + }), + ) + const [fact, ...dimensions] = sources + const live = createLiveQueryCollection({ + startSync: true, + query: (q) => { + let query: any = q.from({ fact: fact! }) + dimensions.forEach((dimension, index) => { + query = query.join( + { [`d${index}`]: dimension }, + (refs: any) => eq(refs.fact[`fk${index}`], refs[`d${index}`].id), + join, + ) + }) + return query.select((refs: any) => ({ + id: refs.fact.id, + value: refs.fact.value, + ...Object.fromEntries( + dimensions.map((_, index) => [`d${index}`, refs[`d${index}`].value]), + ), + })) + }, + }) + + const next = random(collections * 1_000_003 + factRows) + const factRow = (id: number): Row => { + const row: Row = { id, value: Math.floor(next() * 1000) } + for (let index = 0; index < dimensions.length; index++) + row[`fk${index}`] = Math.floor(next() * dimensionRows) + return row + } + const startup: Checkpoint = sources.map((_, index) => + Array.from( + { length: index === 0 ? factRows : dimensionRows }, + (__, id) => ({ + type: `insert` as const, + value: + index === 0 ? factRow(id) : { id, value: Math.floor(next() * 1000) }, + }), + ), + ) + const update: Checkpoint = startup.map((changes) => + changes + .filter(() => next() < UPDATED_SHARE) + .map(({ value }) => ({ + type: `update` as const, + value: { ...value, value: value.value + 1 }, + })), + ) + return { syncs, sources, live, startup, update } +} + +function apply( + syncs: Array, + checkpoint: Checkpoint, + factOrder: FactOrder, + mode: Mode, +) { + const indexes = checkpoint.map((_, index) => index) + if (factOrder === `fact last`) indexes.push(indexes.shift()!) + const commitAll = () => { + for (const index of indexes) { + const sync = syncs[index]! + sync.begin() + for (const change of checkpoint[index]!) sync.write(change) + sync.commit() + } + } + if (mode === `withPublicationContext`) withPublicationContext(commitAll) + else commitAll() +} + +const collectGarbage = () => (globalThis as { gc?: () => void }).gc?.() + +async function measure(benchmarkCase: Case, mode: Mode): Promise { + const fixture = createFixture(benchmarkCase) + await fixture.live.preload() + let batches = 0 + const subscription = fixture.live.subscribeChanges(() => batches++) + + collectGarbage() + let start = performance.now() + apply(fixture.syncs, fixture.startup, benchmarkCase.factOrder, mode) + const startupMs = performance.now() - start + const startupBatches = batches + if (benchmarkCase.join === `left`) + assert.equal(fixture.live.size, benchmarkCase.factRows) + + batches = 0 + collectGarbage() + start = performance.now() + apply(fixture.syncs, fixture.update, benchmarkCase.factOrder, mode) + const updateMs = performance.now() - start + const updateBatches = batches + + const rows = JSON.stringify( + fixture.live.toArray + // Virtual props name each fixture's own live query + .map((row) => + Object.fromEntries( + Object.entries(row).filter(([key]) => !key.startsWith(`$`)), + ), + ) + .sort((a, b) => (a.id as number) - (b.id as number)), + ) + subscription.unsubscribe() + await fixture.live.cleanup() + await Promise.all(fixture.sources.map((source) => source.cleanup())) + return { startupMs, startupBatches, updateMs, updateBatches, rows } +} + +const median = (values: Array) => { + const sorted = [...values].sort((a, b) => a - b) + const middle = Math.floor(sorted.length / 2) + return sorted.length % 2 === 1 + ? sorted[middle]! + : (sorted[middle - 1]! + sorted[middle]!) / 2 +} + +console.log( + `node ${process.version}, ${FACT_ROWS} fact rows, ${repetitions} repetitions after ${warmup} warmups, medians`, +) +const table: Array> = [] +for (const benchmarkCase of cases) { + const samples = new Map(modes.map((mode) => [mode, [] as Array])) + for (let repetition = 0; repetition < warmup + repetitions; repetition++) { + const order = repetition % 2 === 0 ? modes : [...modes].reverse() + const results = new Map() + for (const mode of order) + results.set(mode, await measure(benchmarkCase, mode)) + assert.equal( + results.get(modes[0])!.rows, + results.get(modes[1])!.rows, + `Both modes must end with the same live-query rows`, + ) + if (repetition >= warmup) + for (const [mode, result] of results) samples.get(mode)!.push(result) + } + const [separate, together] = modes.map((mode) => samples.get(mode)!) + const startup = modes.map((mode) => + median(samples.get(mode)!.map((result) => result.startupMs)), + ) + const update = modes.map((mode) => + median(samples.get(mode)!.map((result) => result.updateMs)), + ) + table.push({ + collections: benchmarkCase.collections, + join: benchmarkCase.join, + order: benchmarkCase.factOrder, + index: benchmarkCase.indexMode, + 'startup ms': `${startup[0]!.toFixed(0)} → ${startup[1]!.toFixed(0)}`, + 'startup ×': +(startup[0]! / startup[1]!).toFixed(2), + 'update ms': `${update[0]!.toFixed(1)} → ${update[1]!.toFixed(1)}`, + 'update ×': +(update[0]! / update[1]!).toFixed(2), + batches: `${median(separate!.map((r) => r.startupBatches))}+${median(separate!.map((r) => r.updateBatches))} → ${median(together!.map((r) => r.startupBatches))}+${median(together!.map((r) => r.updateBatches))}`, + }) +} +console.table(table) From d36dd1d46ad7dd8ad3516e2c9478b8d41b7f5056 Mon Sep 17 00:00:00 2001 From: Jaime Resano Date: Sat, 14 Nov 2026 15:04:19 +0100 Subject: [PATCH 2/4] docs(db): state that a held sync commit publishes later A commit made while an optimistic transaction is persisting applies when that transaction settles, so withPublicationContext does not publish it with the other commits. Say so in the doc comment, the guide and the changeset, and cover it with a test. Committed one by one, a live query runs after each commit but publishes only when its result changes. Co-Authored-By: Claude Opus 5.5 --- .changeset/export-with-publication-context.md | 2 +- docs/guides/collection-options-creator.md | 4 +-- packages/db/src/scheduler.ts | 12 +++++-- packages/db/tests/query/scheduler.test.ts | 33 +++++++++++++++++++ 4 files changed, 45 insertions(+), 6 deletions(-) diff --git a/.changeset/export-with-publication-context.md b/.changeset/export-with-publication-context.md index 5e42243701..52e0dfb8b9 100644 --- a/.changeset/export-with-publication-context.md +++ b/.changeset/export-with-publication-context.md @@ -2,4 +2,4 @@ '@tanstack/db': minor --- -Export `withPublicationContext`. A sync source that commits sync transactions to several Collections for one source state, such as one server checkpoint, can commit them inside one call: every live query that reads those Collections then runs after the last commit and publishes one batch, instead of running and publishing an intermediate result after each commit. Each Collection still notifies its own change subscribers when it commits, so this is not an atomic publication across the Collections. +Export `withPublicationContext`. A sync source that commits sync transactions to several Collections for one source state, such as one server checkpoint, can commit them inside one call: every live query that reads those Collections then runs after the last commit and publishes one batch, instead of running after each commit and possibly publishing intermediate results. A commit made while an optimistic transaction is persisting still applies when that transaction settles, in a later publication. Each Collection still notifies its own change subscribers when it commits, so this is not an atomic publication across the Collections. diff --git a/docs/guides/collection-options-creator.md b/docs/guides/collection-options-creator.md index 5a63267460..e51ee042c6 100644 --- a/docs/guides/collection-options-creator.md +++ b/docs/guides/collection-options-creator.md @@ -180,7 +180,7 @@ The sync process follows this lifecycle: ### Committing several Collections together -A source that syncs several Collections over one connection often receives one source state for all of them, such as one server checkpoint. Committed one by one, every live query that joins those Collections runs after each commit and publishes a result over Collections that only some of the commits have reached. Commit them inside one `withPublicationContext` call instead: +A source that syncs several Collections over one connection often receives one source state for all of them, such as one server checkpoint. Committed one by one, every live query that joins those Collections runs after each commit, over Collections that only some of the commits have reached, and can publish those intermediate results. Commit them inside one `withPublicationContext` call instead: ```typescript import { withPublicationContext } from '@tanstack/db' @@ -198,7 +198,7 @@ withPublicationContext(() => { }) ``` -Live queries then run after the last commit and publish one batch. Each Collection still notifies its own change subscribers when it commits, so this is not an atomic publication across the Collections. Catch each commit's failure inside the callback: if the callback throws, the live-query work of the commits it already made is discarded, and those live queries miss them until their sources change again. +Live queries then run after the last commit and publish one batch, with every commit that applied at once. A commit made while an optimistic transaction is persisting applies when that transaction settles, in a later publication: `commit()` returns a receipt instead of `true`, and the call does not wait for it. Each Collection still notifies its own change subscribers when it commits, so this is not an atomic publication across the Collections. Catch each commit's failure inside the callback: if the callback throws, the live-query work of the commits it already made is discarded, and those live queries miss them until their sources change again. ### Reporting failures diff --git a/packages/db/src/scheduler.ts b/packages/db/src/scheduler.ts index deb452728f..321a783731 100644 --- a/packages/db/src/scheduler.ts +++ b/packages/db/src/scheduler.ts @@ -188,9 +188,15 @@ export function recordPublicationError(error: unknown): void { * A sync source that commits sync transactions to several Collections for one * source state, such as one server checkpoint, can commit them inside one call. * Every live query that observes those Collections then runs after `publish` - * returns, with every commit applied, and publishes one batch. Committed one by - * one, a live query that joins them runs and publishes after each commit, over - * Collections that only some of the commits have reached. + * returns, with every commit that applied at once, and publishes one batch. + * Committed one by one, a live query that joins them runs after each commit, + * over Collections that only some of the commits have reached, and can publish + * those intermediate results. + * + * A commit that does not apply at once, because an optimistic transaction is + * persisting, applies when that transaction settles, in a later publication. + * This call does not wait for it, so live queries that read its Collection can + * publish without it first. * * Each Collection still applies its sync transaction and notifies its own * change subscribers when it commits, so this is not an atomic publication diff --git a/packages/db/tests/query/scheduler.test.ts b/packages/db/tests/query/scheduler.test.ts index f40a37c249..a67f918fdb 100644 --- a/packages/db/tests/query/scheduler.test.ts +++ b/packages/db/tests/query/scheduler.test.ts @@ -476,6 +476,39 @@ describe(`sync transactions of several Collections in one publication`, () => { expect(users.size).toBe(1) expect(rows()).toEqual([]) }) + + it(`publishes a commit held behind a persisting transaction in a later batch`, async () => { + const { tasks, assignments, commitUser, commitTask, rows } = + await setupJoinedSources(`publication-held`) + const persisting = createDeferred() + const transaction = createTransaction({ + mutationFn: () => persisting.promise, + }) + transaction.mutate(() => + tasks.insert({ id: 99, userId: 99, title: `optimistic` }), + ) + const published: Array> = [] + const subscription = assignments.subscribeChanges((changes) => + published.push( + changes.map(({ type, value }) => `${type} ${value.title}`), + ), + ) + + publicWithPublicationContext(() => { + commitUser({ id: 1, name: `Ada` }) + commitTask({ id: 1, userId: 1, title: `Review` }) + }) + expect(published).toEqual([[`insert undefined`]]) + + persisting.resolve() + await transaction.when(`settled`) + expect(published).toEqual([ + [`insert undefined`], + [`insert Review`, `delete undefined`], + ]) + expect(rows()).toEqual([{ name: `Ada`, title: `Review` }]) + subscription.unsubscribe() + }) }) describe(`live query scheduler`, () => { From 86cb5d254fdc45bebd2cbf62fd3a60c6736d02f4 Mon Sep 17 00:00:00 2001 From: Jaime Resano Date: Sat, 14 Nov 2026 15:11:09 +0100 Subject: [PATCH 3/4] docs(db): require a synchronous withPublicationContext callback The publication ends when the callback returns, so a commit after an await in it publishes on its own, and a rejected Promise is not handled as a throw. Tell sources to await their input before the call. Co-Authored-By: Claude Opus 5.5 --- docs/guides/collection-options-creator.md | 5 ++++- packages/db/src/scheduler.ts | 4 ++++ 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/docs/guides/collection-options-creator.md b/docs/guides/collection-options-creator.md index e51ee042c6..db2499c781 100644 --- a/docs/guides/collection-options-creator.md +++ b/docs/guides/collection-options-creator.md @@ -180,11 +180,14 @@ The sync process follows this lifecycle: ### Committing several Collections together -A source that syncs several Collections over one connection often receives one source state for all of them, such as one server checkpoint. Committed one by one, every live query that joins those Collections runs after each commit, over Collections that only some of the commits have reached, and can publish those intermediate results. Commit them inside one `withPublicationContext` call instead: +A source that syncs several Collections over one connection often receives one source state for all of them, such as one server checkpoint. Committed one by one, every live query that joins those Collections runs after each commit, over Collections that only some of the commits have reached, and can publish those intermediate results. Commit them inside one `withPublicationContext` call instead. + +The callback must be synchronous: the publication ends when it returns, so a commit after an `await` in it publishes on its own, and a rejected Promise is not handled as a throw. Await the source's input first, then commit inside the call: ```typescript import { withPublicationContext } from '@tanstack/db' +const collectionsInCheckpoint = await receiveCheckpoint() withPublicationContext(() => { for (const { sync, changes } of collectionsInCheckpoint) { try { diff --git a/packages/db/src/scheduler.ts b/packages/db/src/scheduler.ts index 321a783731..092b6d3f84 100644 --- a/packages/db/src/scheduler.ts +++ b/packages/db/src/scheduler.ts @@ -204,6 +204,10 @@ export function recordPublicationError(error: unknown): void { * from this call after the graphs ran. When `publish` itself throws, the queued * graph work is discarded, so live queries miss the commits that `publish` * already made: catch each commit's own failure inside `publish`. + * + * `publish` must be synchronous. The publication ends when it returns, so a + * commit after an `await` in it publishes on its own, and a rejected Promise is + * not handled as a throw. Await the source's input before this call. */ export function withPublicationContext(publish: () => T): T { if (activePublicationContext !== undefined) return publish() From 7f3a7236d3f10a6b900e5f509b43c68a7b2bbef8 Mon Sep 17 00:00:00 2001 From: Jaime Resano Date: Sat, 14 Nov 2026 15:31:56 +0100 Subject: [PATCH 4/4] docs(db): a commit inside transaction.mutate publishes when mutate returns Live-query work inside mutate belongs to the transaction, so a commit made in a mutate callback inside withPublicationContext publishes before the commits after it. State it in the doc comment and the guide, and cover it with a test. Co-Authored-By: Claude Opus 5.5 --- docs/guides/collection-options-creator.md | 2 +- packages/db/src/scheduler.ts | 4 ++++ packages/db/tests/query/scheduler.test.ts | 28 +++++++++++++++++++++++ 3 files changed, 33 insertions(+), 1 deletion(-) diff --git a/docs/guides/collection-options-creator.md b/docs/guides/collection-options-creator.md index db2499c781..e1c79d2f8e 100644 --- a/docs/guides/collection-options-creator.md +++ b/docs/guides/collection-options-creator.md @@ -182,7 +182,7 @@ The sync process follows this lifecycle: A source that syncs several Collections over one connection often receives one source state for all of them, such as one server checkpoint. Committed one by one, every live query that joins those Collections runs after each commit, over Collections that only some of the commits have reached, and can publish those intermediate results. Commit them inside one `withPublicationContext` call instead. -The callback must be synchronous: the publication ends when it returns, so a commit after an `await` in it publishes on its own, and a rejected Promise is not handled as a throw. Await the source's input first, then commit inside the call: +The callback must be synchronous: the publication ends when it returns, so a commit after an `await` in it publishes on its own, and a rejected Promise is not handled as a throw. Do not commit inside a `transaction.mutate` callback within it either: live-query work inside `mutate` belongs to the transaction and publishes when `mutate` returns, before the commits after it. Await the source's input first, then commit inside the call: ```typescript import { withPublicationContext } from '@tanstack/db' diff --git a/packages/db/src/scheduler.ts b/packages/db/src/scheduler.ts index 092b6d3f84..3c5077e488 100644 --- a/packages/db/src/scheduler.ts +++ b/packages/db/src/scheduler.ts @@ -208,6 +208,10 @@ export function recordPublicationError(error: unknown): void { * `publish` must be synchronous. The publication ends when it returns, so a * commit after an `await` in it publishes on its own, and a rejected Promise is * not handled as a throw. Await the source's input before this call. + * + * Inside `transaction.mutate`, live-query work belongs to the transaction and + * publishes when `mutate` returns. A commit made in a `mutate` callback inside + * `publish` therefore publishes before the commits after it. */ export function withPublicationContext(publish: () => T): T { if (activePublicationContext !== undefined) return publish() diff --git a/packages/db/tests/query/scheduler.test.ts b/packages/db/tests/query/scheduler.test.ts index a67f918fdb..839fd51862 100644 --- a/packages/db/tests/query/scheduler.test.ts +++ b/packages/db/tests/query/scheduler.test.ts @@ -509,6 +509,34 @@ describe(`sync transactions of several Collections in one publication`, () => { expect(rows()).toEqual([{ name: `Ada`, title: `Review` }]) subscription.unsubscribe() }) + + it(`publishes a commit made inside transaction.mutate before the commits after it`, async () => { + const { assignments, commitUser, commitTask, rows } = + await setupJoinedSources(`publication-in-mutate`) + const transaction = createTransaction({ + mutationFn: async () => {}, + autoCommit: false, + }) + const published: Array> = [] + const subscription = assignments.subscribeChanges((changes) => + published.push( + changes.map(({ type, value }) => `${type} ${value.title}`), + ), + ) + + publicWithPublicationContext(() => { + transaction.mutate(() => commitUser({ id: 1, name: `Ada` })) + commitTask({ id: 1, userId: 1, title: `Review` }) + }) + + expect(published).toEqual([ + [`insert undefined`], + [`insert Review`, `delete undefined`], + ]) + expect(rows()).toEqual([{ name: `Ada`, title: `Review` }]) + subscription.unsubscribe() + transaction.rollback() + }) }) describe(`live query scheduler`, () => {