docs(query-db): design initial data semantics

[KyleAMathews]

Summary

• define Query cache, normalized row, and server-result authority for initial and placeholder data
• recommend flat eager-only initialData and initialDataUpdatedAt fields while preserving existing cache seeding and hydration behavior
• keep placeholderData observer-local and out of DB materialization, ownership, and persistence
• specify select, direct-write, shared QueryClient, same-key, lifecycle, ownership, and persistence semantics
• propose a test-first sequence of small implementation PRs

Key decisions

• Initial data is ordinary successful Query cache data and materializes through the existing row extraction and ownership pipeline.
• Existing cached or hydrated data wins; initial data only initializes a missing Query document.
• Collections sharing an exact Query key share one Query document, even when they share a QueryClient with many other collections.
• The first public API is eager-only because one initializer cannot establish membership for arbitrary on-demand subsets.
• Placeholder data is UI presentation state and must never become collection-wide normalized rows.
• Wrapped responses require the existing select; direct writes must not fabricate a reverse projection.

Scope

Design and documentation only. No runtime behavior, public option forwarding, persistence format, or tests are changed.

Relates to #1643 and #346.

Verification

• pnpm exec prettier --check docs/collections/query-initial-placeholder-data-design.md
• git diff --check

Summary by CodeRabbit

• Documentation
  • Added design documentation for initialData and placeholderData behavior in query-backed collections.
  • Clarified that initialData is supported for eager collections and treated as stored query data.
  • Documented that placeholder data is not supported in the initial implementation.
  • Defined initialization, freshness, persistence, ownership, projection, and write behavior.

[KyleAMathews]

Closing the design-only PR so this branch can proceed with the approved implementation and tests.

[github-actions]

Size Change: 0 B

Total Size: 125 kB

ℹ️ View Unchanged

Filename	Size
packages/db/dist/esm/collection/change-events.js	1.43 kB
packages/db/dist/esm/collection/changes.js	1.38 kB
packages/db/dist/esm/collection/cleanup-queue.js	810 B
packages/db/dist/esm/collection/events.js	434 B
packages/db/dist/esm/collection/index.js	3.62 kB
packages/db/dist/esm/collection/indexes.js	1.99 kB
packages/db/dist/esm/collection/lifecycle.js	1.69 kB
packages/db/dist/esm/collection/mutations.js	2.47 kB
packages/db/dist/esm/collection/state.js	5.48 kB
packages/db/dist/esm/collection/subscription.js	3.74 kB
packages/db/dist/esm/collection/sync.js	2.88 kB
packages/db/dist/esm/collection/transaction-metadata.js	144 B
packages/db/dist/esm/deferred.js	207 B
packages/db/dist/esm/errors.js	5.1 kB
packages/db/dist/esm/event-emitter.js	748 B
packages/db/dist/esm/index.js	3.16 kB
packages/db/dist/esm/indexes/auto-index.js	829 B
packages/db/dist/esm/indexes/base-index.js	767 B
packages/db/dist/esm/indexes/basic-index.js	2.06 kB
packages/db/dist/esm/indexes/btree-index.js	2.19 kB
packages/db/dist/esm/indexes/index-registry.js	820 B
packages/db/dist/esm/indexes/reverse-index.js	557 B
packages/db/dist/esm/live-query-adapter.js	318 B
packages/db/dist/esm/local-only.js	916 B
packages/db/dist/esm/local-storage.js	2.12 kB
packages/db/dist/esm/optimistic-action.js	359 B
packages/db/dist/esm/paced-mutations.js	496 B
packages/db/dist/esm/proxy.js	3.75 kB
packages/db/dist/esm/query/builder/functions.js	1.47 kB
packages/db/dist/esm/query/builder/index.js	5.84 kB
packages/db/dist/esm/query/builder/ref-proxy.js	1.24 kB
packages/db/dist/esm/query/compiler/evaluators.js	1.89 kB
packages/db/dist/esm/query/compiler/expressions.js	430 B
packages/db/dist/esm/query/compiler/group-by.js	3.56 kB
packages/db/dist/esm/query/compiler/index.js	6.67 kB
packages/db/dist/esm/query/compiler/joins.js	2.5 kB
packages/db/dist/esm/query/compiler/lazy-targets.js	923 B
packages/db/dist/esm/query/compiler/order-by.js	1.74 kB
packages/db/dist/esm/query/compiler/select.js	1.53 kB
packages/db/dist/esm/query/effect.js	4.77 kB
packages/db/dist/esm/query/expression-helpers.js	1.43 kB
packages/db/dist/esm/query/ir.js	1.25 kB
packages/db/dist/esm/query/live-query-collection.js	360 B
packages/db/dist/esm/query/live/collection-config-builder.js	9.1 kB
packages/db/dist/esm/query/live/collection-registry.js	264 B
packages/db/dist/esm/query/live/collection-subscriber.js	1.93 kB
packages/db/dist/esm/query/live/internal.js	145 B
packages/db/dist/esm/query/live/utils.js	1.81 kB
packages/db/dist/esm/query/optimizer.js	2.92 kB
packages/db/dist/esm/query/predicate-utils.js	2.97 kB
packages/db/dist/esm/query/query-once.js	359 B
packages/db/dist/esm/query/subset-dedupe.js	960 B
packages/db/dist/esm/scheduler.js	1.3 kB
packages/db/dist/esm/SortedMap.js	1.3 kB
packages/db/dist/esm/strategies/debounceStrategy.js	247 B
packages/db/dist/esm/strategies/queueStrategy.js	428 B
packages/db/dist/esm/strategies/throttleStrategy.js	246 B
packages/db/dist/esm/transactions.js	3.04 kB
packages/db/dist/esm/utils.js	927 B
packages/db/dist/esm/utils/array-utils.js	273 B
packages/db/dist/esm/utils/browser-polyfills.js	304 B
packages/db/dist/esm/utils/btree.js	5.61 kB
packages/db/dist/esm/utils/comparison.js	1.11 kB
packages/db/dist/esm/utils/cursor.js	457 B
packages/db/dist/esm/utils/index-optimization.js	2.39 kB
packages/db/dist/esm/utils/type-guards.js	157 B
packages/db/dist/esm/utils/uuid.js	449 B
packages/db/dist/esm/virtual-props.js	360 B

_{compressed-size-action::db-package-size}

[github-actions]

Size Change: 0 B

Total Size: 4.22 kB

ℹ️ View Unchanged

Filename	Size
packages/react-db/dist/esm/index.js	249 B
packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.32 kB
packages/react-db/dist/esm/useLiveQuery.js	1.33 kB
packages/react-db/dist/esm/useLiveQueryEffect.js	355 B
packages/react-db/dist/esm/useLiveSuspenseQuery.js	567 B
packages/react-db/dist/esm/usePacedMutations.js	401 B

_{compressed-size-action::react-db-package-size}

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b8cb3f9a-c8c5-4001-93c0-c196e075aed7

📥 Commits

Reviewing files that changed from the base of the PR and between 7f0fa36 and db1662d.

📒 Files selected for processing (1)

• docs/collections/query-initial-placeholder-data-design.md

---

📝 Walkthrough

Walkthrough

The design document defines eager initialData support at the Query Collection boundary, excludes placeholderData materialization, and specifies extraction, authority, ownership, persistence, default handling, lifecycle behavior, rejected designs, and an implementation/test sequence.

Changes

Query initial and placeholder data

Layer / File(s)	Summary
Initial data contract docs/collections/query-initial-placeholder-data-design.md	Defines initialData as stored Query-success data for eager mode, excludes placeholderData, and preserves Query-owned freshness controls.
Materialization and lifecycle rules docs/collections/query-initial-placeholder-data-design.md	Specifies row extraction, direct-write constraints, authority transitions, ownership, persistence, cleanup, and lifecycle behavior.
Compatibility guard and implementation plan docs/collections/query-initial-placeholder-data-design.md	Defines guards for defaults and subset observers, rejects unsupported designs, and outlines staged tests and implementation work.

Estimated code review effort: 1 (Trivial) | ~4 minutes

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch query-initial-placeholder-data-design

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}