From 1df3e963ebafa5bb287f65ad863202b5daefd57a Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 7 Jul 2026 12:33:30 -0600 Subject: [PATCH 1/6] docs: add write status contract test design --- ...write-status-contract-docs-tests-design.md | 102 ++++++++++++++++++ 1 file changed, 102 insertions(+) create mode 100644 docs/superpowers/specs/2026-07-07-write-status-contract-docs-tests-design.md diff --git a/docs/superpowers/specs/2026-07-07-write-status-contract-docs-tests-design.md b/docs/superpowers/specs/2026-07-07-write-status-contract-docs-tests-design.md new file mode 100644 index 000000000..3f4e3f9bf --- /dev/null +++ b/docs/superpowers/specs/2026-07-07-write-status-contract-docs-tests-design.md @@ -0,0 +1,102 @@ +# Write status contract docs/tests design + +Date: 2026-07-07 +Branch: `docs-tests-write-status-contract` + +## Goal + +Create a small, feature-freeze-friendly PR that clarifies TanStack DB's existing local write status semantics and locks the pending optimistic write / sync contract with core collection tests. + +This PR does not add public APIs and does not change sync reconciliation behavior unless a contract test exposes a small existing bug. + +## Background + +The mutation reconciliation RFC issue clarified two important boundaries: + +1. Core cannot generically apply all sync immediately while optimistic mutation functions are pending, because temp-key optimistic inserts can later appear as server-key synced rows. Without explicit identity mapping or mutation receipts, core cannot know whether the server row replaces the temp row or is unrelated. +2. Existing status names are easy to misread. `$synced` and `tx.isPersisted.promise` describe local TanStack DB write/projection state, not necessarily backend upload or read-path observation. + +The first follow-up PR should therefore be documentation and tests only. Public write status APIs such as `$writeStatus`, key-scoped pending write helpers, or `awaitPersisted(key)` belong in a separate PR. + +## Scope + +### In scope + +- Update source JSDoc/TSDoc that feeds generated docs. +- Clarify `$synced` in `packages/db/src/virtual-props.ts`: + - means the row currently has no pending local optimistic mutation in the collection's visible projection; + - does not mean backend upload/read-path confirmation; + - adapters that need stronger backend observation semantics must encode that in their mutation function / adapter layer. +- Clarify `tx.isPersisted.promise` in `packages/db/src/transactions.ts`: + - resolves when the transaction's `mutationFn` settles successfully; + - rejects when the mutation function fails; + - is a promise-bearing deferred, so callers should await `.promise`, not the deferred object itself; + - does not inherently mean the backend sync/read path has observed the write unless the mutation function waits for that observation. +- Add core collection tests only. +- Test the current contract for ambiguous temp/server identity: + - while an optimistic temp-key insert's mutation function is pending, a possible server-key echo should remain queued / not visible; + - visible state should not show both the temp row and server-key row at the same time; + - after the mutation function settles, the optimistic temp row leaves the visible projection and queued sync can apply through the normal path. + +### Out of scope + +- New public APIs (`$writeStatus`, `hasPendingWrites`, `$pendingOperation`, `awaitPersisted(key)`). +- Framework adapter tests (React/Solid/Vue/Svelte). +- Mutation log rewrite. +- Generic immediate sync while mutation functions are pending. +- Temp-key to server-key mapping. +- Mutation receipts. +- Electric txid semantics in core. +- `needs-resolution` transaction state. +- Offline transaction behavior changes. + +## Test design + +Add tests in core collection tests, likely `packages/db/tests/collection.test.ts`, because the behavior is about core collection state and pending sync application. + +Primary test scenario: + +1. Create a collection with an async `onInsert` that remains pending until the test releases it. +2. Insert an optimistic row with a temporary client key, e.g. `{ id: 'temp-1', text: 'A' }`. +3. Assert the temp row is visible immediately. +4. During the pending mutation function, send a sync transaction containing a different key with similar data, e.g. `{ id: 'real-1', text: 'A' }`. +5. Assert the server-key row is not visible while the mutation function is still pending, and the collection does not contain both rows. +6. Resolve the mutation function and await `tx.isPersisted.promise`. +7. Assert the temp row is no longer visible and the queued server-key row is visible after pending sync replay. + +If current main already has equivalent coverage, prefer tightening/renaming existing tests over adding duplicate coverage. + +Secondary docs-oriented test, only if easy and not redundant: + +- Verify `tx.isPersisted.promise` remains pending while the mutation function is pending and resolves only after the mutation function resolves. +- This should be skipped if existing transaction tests already cover it clearly. + +## Implementation notes + +- Do not edit generated `docs/reference` directly unless the repository docs workflow expects generated files to be checked in for source comment changes. +- First update source comments. Then run the relevant docs generation command only if project scripts indicate generated reference docs are part of normal PR output. +- Keep test assertions focused on behavior, not private internals, unless public state cannot express queued sync state. Prefer visible collection state assertions. +- If a test fails because main currently violates the clarified contract, make the smallest code fix possible. Do not expand into mutation-log or identity-mapping work. + +## Verification + +Minimum verification: + +```bash +pnpm --filter @tanstack/db exec vitest run tests/collection.test.ts --pool-options.threads.maxThreads=2 +pnpm --filter @tanstack/db exec tsc --noEmit +``` + +If generated docs are updated, run the repository's docs generation/check command if available. + +## PR framing + +Suggested PR title: + +> Clarify local write status docs and pending sync contract + +Suggested PR body points: + +- Clarifies `$synced` and `isPersisted.promise` source docs so generated references do not imply backend/read-path confirmation. +- Adds core collection coverage for ambiguous temp-key optimistic insert plus possible server-key sync echo. +- Does not add new public write status APIs; those are reserved for a follow-up PR. From e8ae6e72220f9f4c0563662786e576baa0364fe6 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 7 Jul 2026 13:14:49 -0600 Subject: [PATCH 2/6] docs: clarify local write status contract --- docs/reference/interfaces/Transaction.md | 11 +++++++++++ docs/reference/interfaces/VirtualRowProps.md | 16 +++++++++++----- packages/db/src/collection/state.ts | 2 +- packages/db/src/transactions.ts | 12 ++++++++++++ packages/db/src/virtual-props.ts | 16 +++++++++++----- packages/db/tests/collection.test.ts | 7 ++++++- 6 files changed, 52 insertions(+), 12 deletions(-) diff --git a/docs/reference/interfaces/Transaction.md b/docs/reference/interfaces/Transaction.md index b5f6c3b4d..2a47d462a 100644 --- a/docs/reference/interfaces/Transaction.md +++ b/docs/reference/interfaces/Transaction.md @@ -75,6 +75,17 @@ isPersisted: Deferred>; Defined in: [packages/db/src/transactions.ts:214](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L214) +Deferred that settles when this transaction's mutation function settles. + +Await `isPersisted.promise`, not `isPersisted` itself. The promise resolves +after the mutation function completes successfully and rejects if the +mutation function fails. + +This is TanStack DB's local transaction settlement boundary. It does not +inherently prove that a backend has uploaded, confirmed, or read back the +write unless the mutation function waits for that backend observation +before returning. + *** ### metadata diff --git a/docs/reference/interfaces/VirtualRowProps.md b/docs/reference/interfaces/VirtualRowProps.md index c4719d188..accd9a12c 100644 --- a/docs/reference/interfaces/VirtualRowProps.md +++ b/docs/reference/interfaces/VirtualRowProps.md @@ -21,7 +21,7 @@ These properties are: // Accessing virtual properties on a row const user = collection.get('user-1') if (user.$synced) { - console.log('Confirmed by backend') + console.log('No pending local optimistic writes for this row') } if (user.$origin === 'local') { console.log('Created/modified locally') @@ -30,7 +30,7 @@ if (user.$origin === 'local') { ```typescript // Using virtual properties in queries -const confirmedOrders = createLiveQueryCollection({ +const ordersWithoutLocalWrites = createLiveQueryCollection({ query: (q) => q .from({ order: orders }) .where(({ order }) => eq(order.$synced, true)) @@ -103,10 +103,16 @@ readonly $synced: boolean; Defined in: [packages/db/src/virtual-props.ts:69](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L69) -Whether this row reflects confirmed state from the backend. +Whether this row currently has no pending local optimistic mutations in +this collection's visible projection. -- `true`: Row is confirmed by the backend (no pending optimistic mutations) -- `false`: Row has pending optimistic mutations that haven't been confirmed +- `true`: No pending local optimistic mutation currently affects this row +- `false`: One or more pending local optimistic mutations affect this row + +This is a local write/projection status. It does not prove that a backend +has uploaded, confirmed, or read back the row. Adapters that need stronger +backend observation semantics should keep their mutation function pending +until that observation has happened, or expose adapter-specific status. For local-only collections (no sync), this is always `true`. For live query collections, this is passed through from the source collection. diff --git a/packages/db/src/collection/state.ts b/packages/db/src/collection/state.ts index 5f4449c3b..23c40758b 100644 --- a/packages/db/src/collection/state.ts +++ b/packages/db/src/collection/state.ts @@ -154,7 +154,7 @@ export class CollectionStateManager< } /** - * Checks if a row has pending optimistic mutations (not yet confirmed by sync). + * Checks if a row has pending local optimistic mutations in the visible projection. * Used to compute the $synced virtual property. */ public isRowSynced(key: TKey): boolean { diff --git a/packages/db/src/transactions.ts b/packages/db/src/transactions.ts index 84cbbcfe5..fd79773d1 100644 --- a/packages/db/src/transactions.ts +++ b/packages/db/src/transactions.ts @@ -211,6 +211,18 @@ class Transaction> { public state: TransactionState public mutationFn: MutationFn public mutations: Array> + /** + * Deferred that settles when this transaction's mutation function settles. + * + * Await `isPersisted.promise`, not `isPersisted` itself. The promise resolves + * after the mutation function completes successfully and rejects if the + * mutation function fails. + * + * This is TanStack DB's local transaction settlement boundary. It does not + * inherently prove that a backend has uploaded, confirmed, or read back the + * write unless the mutation function waits for that backend observation + * before returning. + */ public isPersisted: Deferred> public autoCommit: boolean public createdAt: Date diff --git a/packages/db/src/virtual-props.ts b/packages/db/src/virtual-props.ts index 3205d31c2..2bb7274fd 100644 --- a/packages/db/src/virtual-props.ts +++ b/packages/db/src/virtual-props.ts @@ -37,7 +37,7 @@ export type VirtualOrigin = 'local' | 'remote' * // Accessing virtual properties on a row * const user = collection.get('user-1') * if (user.$synced) { - * console.log('Confirmed by backend') + * console.log('No pending local optimistic writes for this row') * } * if (user.$origin === 'local') { * console.log('Created/modified locally') @@ -47,7 +47,7 @@ export type VirtualOrigin = 'local' | 'remote' * @example * ```typescript * // Using virtual properties in queries - * const confirmedOrders = createLiveQueryCollection({ + * const ordersWithoutLocalWrites = createLiveQueryCollection({ * query: (q) => q * .from({ order: orders }) * .where(({ order }) => eq(order.$synced, true)) @@ -58,10 +58,16 @@ export interface VirtualRowProps< TKey extends string | number = string | number, > { /** - * Whether this row reflects confirmed state from the backend. + * Whether this row currently has no pending local optimistic mutations in + * this collection's visible projection. * - * - `true`: Row is confirmed by the backend (no pending optimistic mutations) - * - `false`: Row has pending optimistic mutations that haven't been confirmed + * - `true`: No pending local optimistic mutation currently affects this row + * - `false`: One or more pending local optimistic mutations affect this row + * + * This is a local write/projection status. It does not prove that a backend + * has uploaded, confirmed, or read back the row. Adapters that need stronger + * backend observation semantics should keep their mutation function pending + * until that observation has happened, or expose adapter-specific status. * * For local-only collections (no sync), this is always `true`. * For live query collections, this is passed through from the source collection. diff --git a/packages/db/tests/collection.test.ts b/packages/db/tests/collection.test.ts index c204b89af..e96994db6 100644 --- a/packages/db/tests/collection.test.ts +++ b/packages/db/tests/collection.test.ts @@ -77,7 +77,7 @@ describe(`Collection`, () => { ).toThrow(DuplicateKeySyncError) }) - it(`removes optimistic insert when sync confirms with a different server-generated key`, async () => { + it(`keeps ambiguous server-key sync queued while a temp-key optimistic insert is pending`, async () => { const options = mockSyncCollectionOptionsNoInitialState<{ id: number text: string @@ -102,6 +102,11 @@ describe(`Collection`, () => { options.utils.commit() // The sync commit is held while the local insert transaction is persisting. + // Without an explicit temp-key -> server-key mapping, core cannot know + // whether key 24 is this optimistic insert's server echo or an unrelated + // row, so it must not expose both rows at the same time. + expect(tx.isPersisted.isPending()).toBe(true) + expect(collection.has(24)).toBe(false) expect(getStateEntries(collection)).toEqual([ [4733, { id: 4733, text: `two` }], ]) From 0fea2aa26af15e372d33e5e70dbb0b2f0471688d Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 7 Jul 2026 13:28:50 -0600 Subject: [PATCH 3/6] docs: tighten transaction settlement wording --- docs/reference/interfaces/Transaction.md | 11 ----------- docs/reference/interfaces/VirtualRowProps.md | 16 +++++----------- packages/db/src/transactions.ts | 14 +++++++------- 3 files changed, 12 insertions(+), 29 deletions(-) diff --git a/docs/reference/interfaces/Transaction.md b/docs/reference/interfaces/Transaction.md index 2a47d462a..b5f6c3b4d 100644 --- a/docs/reference/interfaces/Transaction.md +++ b/docs/reference/interfaces/Transaction.md @@ -75,17 +75,6 @@ isPersisted: Deferred>; Defined in: [packages/db/src/transactions.ts:214](https://github.com/TanStack/db/blob/main/packages/db/src/transactions.ts#L214) -Deferred that settles when this transaction's mutation function settles. - -Await `isPersisted.promise`, not `isPersisted` itself. The promise resolves -after the mutation function completes successfully and rejects if the -mutation function fails. - -This is TanStack DB's local transaction settlement boundary. It does not -inherently prove that a backend has uploaded, confirmed, or read back the -write unless the mutation function waits for that backend observation -before returning. - *** ### metadata diff --git a/docs/reference/interfaces/VirtualRowProps.md b/docs/reference/interfaces/VirtualRowProps.md index accd9a12c..c4719d188 100644 --- a/docs/reference/interfaces/VirtualRowProps.md +++ b/docs/reference/interfaces/VirtualRowProps.md @@ -21,7 +21,7 @@ These properties are: // Accessing virtual properties on a row const user = collection.get('user-1') if (user.$synced) { - console.log('No pending local optimistic writes for this row') + console.log('Confirmed by backend') } if (user.$origin === 'local') { console.log('Created/modified locally') @@ -30,7 +30,7 @@ if (user.$origin === 'local') { ```typescript // Using virtual properties in queries -const ordersWithoutLocalWrites = createLiveQueryCollection({ +const confirmedOrders = createLiveQueryCollection({ query: (q) => q .from({ order: orders }) .where(({ order }) => eq(order.$synced, true)) @@ -103,16 +103,10 @@ readonly $synced: boolean; Defined in: [packages/db/src/virtual-props.ts:69](https://github.com/TanStack/db/blob/main/packages/db/src/virtual-props.ts#L69) -Whether this row currently has no pending local optimistic mutations in -this collection's visible projection. +Whether this row reflects confirmed state from the backend. -- `true`: No pending local optimistic mutation currently affects this row -- `false`: One or more pending local optimistic mutations affect this row - -This is a local write/projection status. It does not prove that a backend -has uploaded, confirmed, or read back the row. Adapters that need stronger -backend observation semantics should keep their mutation function pending -until that observation has happened, or expose adapter-specific status. +- `true`: Row is confirmed by the backend (no pending optimistic mutations) +- `false`: Row has pending optimistic mutations that haven't been confirmed For local-only collections (no sync), this is always `true`. For live query collections, this is passed through from the source collection. diff --git a/packages/db/src/transactions.ts b/packages/db/src/transactions.ts index fd79773d1..4a3e2f80f 100644 --- a/packages/db/src/transactions.ts +++ b/packages/db/src/transactions.ts @@ -212,16 +212,16 @@ class Transaction> { public mutationFn: MutationFn public mutations: Array> /** - * Deferred that settles when this transaction's mutation function settles. + * Deferred that settles when this transaction settles. * * Await `isPersisted.promise`, not `isPersisted` itself. The promise resolves - * after the mutation function completes successfully and rejects if the - * mutation function fails. + * when the transaction completes successfully and rejects if the transaction + * fails or is rolled back. * - * This is TanStack DB's local transaction settlement boundary. It does not - * inherently prove that a backend has uploaded, confirmed, or read back the - * write unless the mutation function waits for that backend observation - * before returning. + * For non-empty commits, the mutation function is the normal settlement + * boundary. This does not inherently prove that a backend has uploaded, + * confirmed, or read back the write unless the mutation function waits for + * that backend observation before returning. */ public isPersisted: Deferred> public autoCommit: boolean From ab7464b108ca72642d8bc8e11013597ffb2dcaae Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 7 Jul 2026 13:30:05 -0600 Subject: [PATCH 4/6] chore: remove planning spec from PR --- ...write-status-contract-docs-tests-design.md | 102 ------------------ 1 file changed, 102 deletions(-) delete mode 100644 docs/superpowers/specs/2026-07-07-write-status-contract-docs-tests-design.md diff --git a/docs/superpowers/specs/2026-07-07-write-status-contract-docs-tests-design.md b/docs/superpowers/specs/2026-07-07-write-status-contract-docs-tests-design.md deleted file mode 100644 index 3f4e3f9bf..000000000 --- a/docs/superpowers/specs/2026-07-07-write-status-contract-docs-tests-design.md +++ /dev/null @@ -1,102 +0,0 @@ -# Write status contract docs/tests design - -Date: 2026-07-07 -Branch: `docs-tests-write-status-contract` - -## Goal - -Create a small, feature-freeze-friendly PR that clarifies TanStack DB's existing local write status semantics and locks the pending optimistic write / sync contract with core collection tests. - -This PR does not add public APIs and does not change sync reconciliation behavior unless a contract test exposes a small existing bug. - -## Background - -The mutation reconciliation RFC issue clarified two important boundaries: - -1. Core cannot generically apply all sync immediately while optimistic mutation functions are pending, because temp-key optimistic inserts can later appear as server-key synced rows. Without explicit identity mapping or mutation receipts, core cannot know whether the server row replaces the temp row or is unrelated. -2. Existing status names are easy to misread. `$synced` and `tx.isPersisted.promise` describe local TanStack DB write/projection state, not necessarily backend upload or read-path observation. - -The first follow-up PR should therefore be documentation and tests only. Public write status APIs such as `$writeStatus`, key-scoped pending write helpers, or `awaitPersisted(key)` belong in a separate PR. - -## Scope - -### In scope - -- Update source JSDoc/TSDoc that feeds generated docs. -- Clarify `$synced` in `packages/db/src/virtual-props.ts`: - - means the row currently has no pending local optimistic mutation in the collection's visible projection; - - does not mean backend upload/read-path confirmation; - - adapters that need stronger backend observation semantics must encode that in their mutation function / adapter layer. -- Clarify `tx.isPersisted.promise` in `packages/db/src/transactions.ts`: - - resolves when the transaction's `mutationFn` settles successfully; - - rejects when the mutation function fails; - - is a promise-bearing deferred, so callers should await `.promise`, not the deferred object itself; - - does not inherently mean the backend sync/read path has observed the write unless the mutation function waits for that observation. -- Add core collection tests only. -- Test the current contract for ambiguous temp/server identity: - - while an optimistic temp-key insert's mutation function is pending, a possible server-key echo should remain queued / not visible; - - visible state should not show both the temp row and server-key row at the same time; - - after the mutation function settles, the optimistic temp row leaves the visible projection and queued sync can apply through the normal path. - -### Out of scope - -- New public APIs (`$writeStatus`, `hasPendingWrites`, `$pendingOperation`, `awaitPersisted(key)`). -- Framework adapter tests (React/Solid/Vue/Svelte). -- Mutation log rewrite. -- Generic immediate sync while mutation functions are pending. -- Temp-key to server-key mapping. -- Mutation receipts. -- Electric txid semantics in core. -- `needs-resolution` transaction state. -- Offline transaction behavior changes. - -## Test design - -Add tests in core collection tests, likely `packages/db/tests/collection.test.ts`, because the behavior is about core collection state and pending sync application. - -Primary test scenario: - -1. Create a collection with an async `onInsert` that remains pending until the test releases it. -2. Insert an optimistic row with a temporary client key, e.g. `{ id: 'temp-1', text: 'A' }`. -3. Assert the temp row is visible immediately. -4. During the pending mutation function, send a sync transaction containing a different key with similar data, e.g. `{ id: 'real-1', text: 'A' }`. -5. Assert the server-key row is not visible while the mutation function is still pending, and the collection does not contain both rows. -6. Resolve the mutation function and await `tx.isPersisted.promise`. -7. Assert the temp row is no longer visible and the queued server-key row is visible after pending sync replay. - -If current main already has equivalent coverage, prefer tightening/renaming existing tests over adding duplicate coverage. - -Secondary docs-oriented test, only if easy and not redundant: - -- Verify `tx.isPersisted.promise` remains pending while the mutation function is pending and resolves only after the mutation function resolves. -- This should be skipped if existing transaction tests already cover it clearly. - -## Implementation notes - -- Do not edit generated `docs/reference` directly unless the repository docs workflow expects generated files to be checked in for source comment changes. -- First update source comments. Then run the relevant docs generation command only if project scripts indicate generated reference docs are part of normal PR output. -- Keep test assertions focused on behavior, not private internals, unless public state cannot express queued sync state. Prefer visible collection state assertions. -- If a test fails because main currently violates the clarified contract, make the smallest code fix possible. Do not expand into mutation-log or identity-mapping work. - -## Verification - -Minimum verification: - -```bash -pnpm --filter @tanstack/db exec vitest run tests/collection.test.ts --pool-options.threads.maxThreads=2 -pnpm --filter @tanstack/db exec tsc --noEmit -``` - -If generated docs are updated, run the repository's docs generation/check command if available. - -## PR framing - -Suggested PR title: - -> Clarify local write status docs and pending sync contract - -Suggested PR body points: - -- Clarifies `$synced` and `isPersisted.promise` source docs so generated references do not imply backend/read-path confirmation. -- Adds core collection coverage for ambiguous temp-key optimistic insert plus possible server-key sync echo. -- Does not add new public write status APIs; those are reserved for a follow-up PR. From b5e76e0574511ae042484c4e60023bfd7f7baea7 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Tue, 7 Jul 2026 13:31:32 -0600 Subject: [PATCH 5/6] chore: add changeset --- .changeset/clarify-local-write-status.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/clarify-local-write-status.md diff --git a/.changeset/clarify-local-write-status.md b/.changeset/clarify-local-write-status.md new file mode 100644 index 000000000..2eb8087e4 --- /dev/null +++ b/.changeset/clarify-local-write-status.md @@ -0,0 +1,5 @@ +--- +'@tanstack/db': patch +--- + +Clarify local write status documentation for `$synced` and `isPersisted.promise`, and add core coverage for queued ambiguous server-key sync while optimistic temp-key inserts are pending. From 4bbc2689995ec9719237acefb79db1c38caf6fe1 Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Thu, 9 Jul 2026 09:25:03 -0600 Subject: [PATCH 6/6] docs: clarify synced write status wording --- packages/db/src/collection/state.ts | 7 ++++++- packages/db/src/virtual-props.ts | 13 ++++++------- 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/packages/db/src/collection/state.ts b/packages/db/src/collection/state.ts index 23c40758b..0f7b3b868 100644 --- a/packages/db/src/collection/state.ts +++ b/packages/db/src/collection/state.ts @@ -154,7 +154,12 @@ export class CollectionStateManager< } /** - * Checks if a row has pending local optimistic mutations in the visible projection. + * Checks whether this row currently has no pending local optimistic writes. + * + * This is local mutation status, not backend confirmation: `true` means the + * row is not currently affected by an optimistic transaction in this + * collection's visible state. + * * Used to compute the $synced virtual property. */ public isRowSynced(key: TKey): boolean { diff --git a/packages/db/src/virtual-props.ts b/packages/db/src/virtual-props.ts index 2bb7274fd..ef285821f 100644 --- a/packages/db/src/virtual-props.ts +++ b/packages/db/src/virtual-props.ts @@ -58,16 +58,15 @@ export interface VirtualRowProps< TKey extends string | number = string | number, > { /** - * Whether this row currently has no pending local optimistic mutations in - * this collection's visible projection. + * Whether this row currently has no pending local optimistic writes. * * - `true`: No pending local optimistic mutation currently affects this row - * - `false`: One or more pending local optimistic mutations affect this row + * - `false`: One or more pending local optimistic mutations currently affect this row * - * This is a local write/projection status. It does not prove that a backend - * has uploaded, confirmed, or read back the row. Adapters that need stronger - * backend observation semantics should keep their mutation function pending - * until that observation has happened, or expose adapter-specific status. + * This is local mutation status. It does not prove that a backend has uploaded, + * confirmed, or read back the row. If you need backend-confirmed status, keep + * your mutation function pending until that backend observation has happened, + * or expose adapter-specific status. * * For local-only collections (no sync), this is always `true`. * For live query collections, this is passed through from the source collection.