diff --git a/.changeset/export-with-publication-context.md b/.changeset/export-with-publication-context.md new file mode 100644 index 0000000000..52e0dfb8b9 --- /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 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 f362cea00c..e1c79d2f8e 100644 --- a/docs/guides/collection-options-creator.md +++ b/docs/guides/collection-options-creator.md @@ -178,6 +178,31 @@ 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, 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. 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' + +const collectionsInCheckpoint = await receiveCheckpoint() +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, 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 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..3c5077e488 100644 --- a/packages/db/src/scheduler.ts +++ b/packages/db/src/scheduler.ts @@ -184,6 +184,34 @@ 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 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 + * 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`. + * + * `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 76a82bee8e..839fd51862 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,200 @@ 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([]) + }) + + 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() + }) + + 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`, () => { 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)