eagerly run live queries while collections are loading

[samwillis]

Summary

Refactors the live query execution model to support eager materialization. Live queries now process and display data as it arrives from source collections during sync, rather than waiting for all source collections to reach a "ready" state before executing.

Key Changes

• Eager Execution: Live queries now run immediately when triggered via .preload() or .startSync(), processing data as it arrives from source collections
• Separated Status & Data Management: Status updates now use on('status:change') event listeners, while subscribeChanges is used solely for data updates
• Error Propagation: Live queries automatically transition to error state when source collections error or are manually cleaned up
• Optimistic Transactions: Local optimistic mutations are immediately visible in live queries even while source collections are still in "loading" state, with proper rollback behavior when mutations aren't persisted via sync
• Lifecycle Simplification: Removed initialCommit status from collection lifecycle across entire codebase
• Auto-indexing: Enabled auto-indexing during loading state to support eager query execution
• Public API: Made _lifecycle property public on Collection interface for internal library use
• Framework Updates: Updated all framework adapters (React, Vue, Solid, Svelte, Angular) to remove initialCommit references and validate eager execution behavior

Testing

Core Package (@tanstack/db):

• Added comprehensive test suite for eager execution in query-while-syncing.test.ts (24 tests covering basic queries, joins, multiple sources, error handling, and both .startSync() and .preload() patterns)
• Added test validating optimistic transaction visibility and rollback behavior during loading state
• Added tests validating multiple sync transactions before markReady() in collection tests
• Added tests for change event emission during multiple sync transactions
• Refactored tests to use modern vitest describe.each pattern for parameterized testing with both autoIndex: 'off' and autoIndex: 'eager'
• All tests use fake timers for faster, more deterministic execution

Framework Packages:

• Added eager execution tests to all framework packages validating that live queries show data while isLoading == true:
  • React (@tanstack/react-db): 4 new tests (33 total)
  • Vue (@tanstack/vue-db): 4 new tests (23 total)
  • Solid (@tanstack/solid-db): 4 new tests (20 total)
  • Svelte (@tanstack/svelte-db): 4 new tests (22 total)
  • Angular (@tanstack/angular-db): 3 new tests (18 total)
• Each framework package now validates:
  • State visibility during sync while isLoading == true
  • Filtered query results during sync
  • Join query results during sync (where applicable)
  • Status updates when source is marked ready with no data
• Fixed all initialCommit references in framework adapter implementations

Test Coverage:

• Total: 1,531 tests pass across all packages (up from 1,281)
• Added 19 framework-specific tests validating eager execution
• Added 24 core package tests for eager execution scenarios

User-Facing Impact

Users will see live query results update in real-time as data loads, providing immediate feedback during sync operations. This includes both synced data and local optimistic updates, creating a more responsive user experience even before the underlying data is fully loaded. They can use the collection status to show loading state while the data streams in. This behavior is consistent across all framework adapters (React, Vue, Solid, Svelte, Angular).

[changeset-bot]

🦋 Changeset detected

Latest commit: 2816a73

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 12 packages

Name	Type
@tanstack/react-db	Patch
@tanstack/db	Patch
@tanstack/db-example-react-todo	Patch
@tanstack/angular-db	Patch
@tanstack/electric-db-collection	Patch
@tanstack/query-db-collection	Patch
@tanstack/rxdb-db-collection	Patch
@tanstack/solid-db	Patch
@tanstack/svelte-db	Patch
@tanstack/trailbase-db-collection	Patch
@tanstack/vue-db	Patch
todos	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[pkg-pr-new]

More templates

• todos
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• @tanstack/db-example-solid-todo

@tanstack/angular-db

npm i https://pkg.pr.new/@tanstack/angular-db@658

@tanstack/db

npm i https://pkg.pr.new/@tanstack/db@658

@tanstack/db-ivm

npm i https://pkg.pr.new/@tanstack/db-ivm@658

@tanstack/electric-db-collection

npm i https://pkg.pr.new/@tanstack/electric-db-collection@658

@tanstack/query-db-collection

npm i https://pkg.pr.new/@tanstack/query-db-collection@658

@tanstack/react-db

npm i https://pkg.pr.new/@tanstack/react-db@658

@tanstack/rxdb-db-collection

npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@658

@tanstack/solid-db

npm i https://pkg.pr.new/@tanstack/solid-db@658

@tanstack/svelte-db

npm i https://pkg.pr.new/@tanstack/svelte-db@658

@tanstack/trailbase-db-collection

npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@658

@tanstack/vue-db

npm i https://pkg.pr.new/@tanstack/vue-db@658

commit: 2816a73

[github-actions]

Size Change: +222 B (+0.29%)

Total Size: 76.3 kB

Filename	Size	Change
./packages/db/dist/esm/collection/lifecycle.js	1.8 kB	-22 B (-1.21%)
./packages/db/dist/esm/collection/state.js	3.78 kB	-43 B (-1.12%)
./packages/db/dist/esm/collection/sync.js	1.63 kB	-21 B (-1.27%)
./packages/db/dist/esm/indexes/auto-index.js	794 B	-34 B (-4.11%)
./packages/db/dist/esm/query/live/collection-config-builder.js	3.03 kB	+342 B (+12.74%)	⚠️

ℹ️ View Unchanged

Filename	Size
./packages/db/dist/esm/collection/change-events.js	963 B
./packages/db/dist/esm/collection/changes.js	1.01 kB
./packages/db/dist/esm/collection/events.js	660 B
./packages/db/dist/esm/collection/index.js	3.31 kB
./packages/db/dist/esm/collection/indexes.js	1.16 kB
./packages/db/dist/esm/collection/mutations.js	2.52 kB
./packages/db/dist/esm/collection/subscription.js	1.83 kB
./packages/db/dist/esm/deferred.js	230 B
./packages/db/dist/esm/errors.js	3.1 kB
./packages/db/dist/esm/index.js	1.58 kB
./packages/db/dist/esm/indexes/base-index.js	835 B
./packages/db/dist/esm/indexes/btree-index.js	2 kB
./packages/db/dist/esm/indexes/lazy-index.js	1.21 kB
./packages/db/dist/esm/indexes/reverse-index.js	577 B
./packages/db/dist/esm/local-only.js	827 B
./packages/db/dist/esm/local-storage.js	2.02 kB
./packages/db/dist/esm/optimistic-action.js	294 B
./packages/db/dist/esm/proxy.js	3.86 kB
./packages/db/dist/esm/query/builder/functions.js	615 B
./packages/db/dist/esm/query/builder/index.js	4.04 kB
./packages/db/dist/esm/query/builder/ref-proxy.js	938 B
./packages/db/dist/esm/query/compiler/evaluators.js	1.55 kB
./packages/db/dist/esm/query/compiler/expressions.js	760 B
./packages/db/dist/esm/query/compiler/group-by.js	2.04 kB
./packages/db/dist/esm/query/compiler/index.js	2.04 kB
./packages/db/dist/esm/query/compiler/joins.js	2.52 kB
./packages/db/dist/esm/query/compiler/order-by.js	1.21 kB
./packages/db/dist/esm/query/compiler/select.js	1.28 kB
./packages/db/dist/esm/query/ir.js	785 B
./packages/db/dist/esm/query/live-query-collection.js	340 B
./packages/db/dist/esm/query/live/collection-subscriber.js	1.92 kB
./packages/db/dist/esm/query/optimizer.js	3.08 kB
./packages/db/dist/esm/SortedMap.js	1.24 kB
./packages/db/dist/esm/transactions.js	3 kB
./packages/db/dist/esm/utils.js	1.01 kB
./packages/db/dist/esm/utils/browser-polyfills.js	365 B
./packages/db/dist/esm/utils/btree.js	6.01 kB
./packages/db/dist/esm/utils/comparison.js	754 B
./packages/db/dist/esm/utils/index-optimization.js	1.73 kB

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

[github-actions]

Size Change: 0 B

Total Size: 1.47 kB

ℹ️ View Unchanged

Filename	Size
./packages/react-db/dist/esm/index.js	152 B
./packages/react-db/dist/esm/useLiveQuery.js	1.32 kB

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

[KyleAMathews]

Great stuff! I don't think this would show up as improvement in our current benchmarks but for anything that does chunked loading like electric, this should be quite a bit faster.

[marbemac]

❤️ works like a charm - closing #641