perf: optimize hot paths in persistence, scheduling, and React hooks #1542
main fromperf·opened Summary#
Optimize hot paths across three packages to reduce unnecessary allocations and improve algorithmic complexity. The headline win is in useLiveQuery — status-only consumers (isReady, isLoading, status) now skip entry materialization entirely, dropping from ~2.3ms to ~0.001ms on 50k-row collections.
Root cause#
Several hot paths used patterns with unnecessary overhead:
- Sorting with inline
JSON.stringify—toStableSerializablecalledJSON.stringifyon both operands in every sort comparison, producing O(n log n) serializations instead of O(n) - Queue flush via
while/shift— repeatedshift()on a long array is O(n²) due to re-indexing - Nested
findIndexloops —KeyScheduler.updateTransactionsandloadPendingTransactionsused O(n×m) lookups where O(n+m) sufficed - Eager entry materialization —
useLiveQuerycalledArray.from(collection.entries())on every snapshot, even when the consumer only read status flags
Approach#
@tanstack/db-sqlite-persistence-core#
- Schwartzian transform for Set/Map sorting: serialize each element once (O(n)), sort on pre-computed keys, then strip decoration. Avoids redundant
JSON.stringifyin the comparator. splice(0)queue flush replaceswhile/shift— detaches the queue atomically in O(n), then iterates. Items arriving during async processing accumulate in the original array for the next flush.
@tanstack/offline-transactions#
- Map-based lookup in
KeyScheduler.updateTransactions— builds a Map from the update array, then single-pass updates. O(n+m) instead of O(n×m). getEarliestRetryTimemoved toKeySchedulerwith a simple loop — avoids spreading intoMath.min(...array)which could stack-overflow on large arrays.- Set-based filtering in
loadPendingTransactionsfor removed transaction detection. - Hoisted
Date.now()inresetRetryDelays— all transactions get the same timestamp.
@tanstack/react-db#
- Lazy property access in
useLiveQuery—stateanddataare now getters that defercollection.entries()until first access. Status flags (isReady,isLoading, etc.) are plain properties that never trigger materialization.
Key invariants#
- Anti-tearing guarantee preserved: both
stateanddataderive from a shared lazygetEntries()snapshot. If a consumer reads both, they see the same point-in-time view of the collection. ThesingleResultpath also usesgetEntries()for consistency, intentionally trading some getter-level speed for correctness. - Queue flush semantics:
splice(0)detaches the queue before iterating. This is safe becauseisHydratingisfalseby the time flush runs, so no new items can be pushed during processing. - FIFO ordering:
KeyScheduler.updateTransactionsre-sorts bycreatedAtafter bulk updates to maintain execution order.
Non-goals#
- Incremental cached updates — the real remaining React perf problem is that any collection change rebuilds a full snapshot when
dataorstateis accessed. Fixing that requires incremental update propagation from change payloads, which is a much larger effort. - Further
singleResultoptimization — an earlier version usedcollection.values().next().valueto avoid full materialization, but this could tear relative tostate. Correctness was chosen over the extra speed.
Benchmarks#
Local runs via pnpm bench:perf on Node v24.11.1 / macOS arm64. Numbers are medians. Baseline numbers are from the pre-change implementation where available; the queue-drain benchmark compares the old shift() strategy to the new cursor/splice-style strategy.
| Area | Benchmark | Before | After | Change |
|---|---|---|---|---|
| React | useLiveQuery status-only, 50k rows | 2.309ms | 0.001ms | ~99.96% faster |
| React | useLiveQuery data access, 50k rows | 2.786ms | 2.711ms | ~2.7% faster / roughly neutral |
| React | useLiveQuery singleResult, 50k rows | 2.561ms | 2.043ms | ~20% faster |
| Offline transactions | KeyScheduler.updateTransactions all pending, 1k | 8.652ms | 6.584ms | ~24% faster |
| Offline transactions | KeyScheduler.updateTransactions all pending, 5k | 209.177ms | 149.484ms | ~29% faster |
| Offline transactions | TransactionExecutor.loadPendingTransactions half filtered, 1k | 5.926ms | 1.627ms | ~73% faster |
| Offline transactions | TransactionExecutor.loadPendingTransactions half filtered, 5k | 95.927ms | 39.506ms | ~59% faster |
| SQLite persistence / queue drain | array queue drain, 10k (shift() → cursor/splice-style) | 0.655ms | 0.309ms | ~53% faster |
Additional after-change benchmark now covered by the harness:
| Area | Benchmark | After | Notes |
|---|---|---|---|
| Offline transactions | KeyScheduler.getEarliestRetryTime with setup, 5k | 150.209ms | Added to guard the new direct scheduler scan and avoid Math.min(...array) argument-spread risk. No pre-change median was captured for this specific case. |
Verification#
pnpm --filter @tanstack/react-db test -- --run
pnpm --filter @tanstack/db-sqlite-persistence-core test -- --run
pnpm --filter @tanstack/offline-transactions test -- --run
Files changed#
| File | Change |
|---|---|
packages/react-db/src/useLiveQuery.ts | Lazy getters for state/data with shared entries snapshot |
packages/react-db/tests/useLiveQuery.test.tsx | Tests for lazy materialization, singleResult, state getter |
packages/db-sqlite-persistence-core/src/persisted.ts | Schwartzian transform + splice-based queue flush |
packages/db-sqlite-persistence-core/tests/persisted.test.ts | Tests for stable serialization + concurrent queue behavior |
packages/offline-transactions/src/executor/KeyScheduler.ts | Map-based updateTransactions + getEarliestRetryTime |
packages/offline-transactions/src/executor/TransactionExecutor.ts | Delegate to scheduler, Set-based filtering, Date.now() hoist |
packages/offline-transactions/tests/KeyScheduler.test.ts | Tests for bulk update, FIFO ordering, earliest retry time |
package.json | Add bench:perf script |
🤖 Generated with Claude Code
Summary by CodeRabbit#
New Features
- Transaction scheduler now exposes earliest retry time computation for improved scheduling visibility.
Performance
- Optimized hot paths in persistence layer via stable serialization sorting and efficient queue processing.
- Enhanced live query performance through lazy property materialization—status reads no longer materialize unnecessary data entries.
Tests
- Added coverage for edge cases in transaction queuing during persistence reloads.
- Added performance-sensitive tests verifying lazy data access patterns in live queries.
- 1
More templates
@tanstack/angular-db
npm i https://pkg.pr.new/@tanstack/angular-db@1542@tanstack/browser-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1542@tanstack/capacitor-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1542@tanstack/cloudflare-durable-objects-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1542@tanstack/db
npm i https://pkg.pr.new/@tanstack/db@1542@tanstack/db-ivm
npm i https://pkg.pr.new/@tanstack/db-ivm@1542@tanstack/db-sqlite-persistence-core
npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1542@tanstack/electric-db-collection
npm i https://pkg.pr.new/@tanstack/electric-db-collection@1542@tanstack/electron-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1542@tanstack/expo-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1542@tanstack/node-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1542@tanstack/offline-transactions
npm i https://pkg.pr.new/@tanstack/offline-transactions@1542@tanstack/powersync-db-collection
npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1542@tanstack/query-db-collection
npm i https://pkg.pr.new/@tanstack/query-db-collection@1542@tanstack/react-db
npm i https://pkg.pr.new/@tanstack/react-db@1542@tanstack/react-native-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1542@tanstack/rxdb-db-collection
npm i https://pkg.pr.new/@tanstack/rxdb-db-collection@1542@tanstack/solid-db
npm i https://pkg.pr.new/@tanstack/solid-db@1542@tanstack/svelte-db
npm i https://pkg.pr.new/@tanstack/svelte-db@1542@tanstack/tauri-db-sqlite-persistence
npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1542@tanstack/trailbase-db-collection
npm i https://pkg.pr.new/@tanstack/trailbase-db-collection@1542@tanstack/vue-db
npm i https://pkg.pr.new/@tanstack/vue-db@1542commit:
6c3326fSize Change: 0 B
Total Size: 117 kB
compressed-size-action::db-package-sizeℹ️ View Unchanged
Filename Size packages/db/dist/esm/collection/change-events.js1.39 kB packages/db/dist/esm/collection/changes.js1.38 kB packages/db/dist/esm/collection/cleanup-queue.js810 B packages/db/dist/esm/collection/events.js434 B packages/db/dist/esm/collection/index.js3.61 kB packages/db/dist/esm/collection/indexes.js1.99 kB packages/db/dist/esm/collection/lifecycle.js1.69 kB packages/db/dist/esm/collection/mutations.js2.47 kB packages/db/dist/esm/collection/state.js5.26 kB packages/db/dist/esm/collection/subscription.js3.74 kB packages/db/dist/esm/collection/sync.js2.88 kB packages/db/dist/esm/collection/transaction-metadata.js144 B packages/db/dist/esm/deferred.js207 B packages/db/dist/esm/errors.js4.92 kB packages/db/dist/esm/event-emitter.js748 B packages/db/dist/esm/index.js3.01 kB packages/db/dist/esm/indexes/auto-index.js830 B packages/db/dist/esm/indexes/base-index.js729 B packages/db/dist/esm/indexes/basic-index.js2.05 kB packages/db/dist/esm/indexes/btree-index.js2.17 kB packages/db/dist/esm/indexes/index-registry.js820 B packages/db/dist/esm/indexes/reverse-index.js538 B packages/db/dist/esm/local-only.js890 B packages/db/dist/esm/local-storage.js2.1 kB packages/db/dist/esm/optimistic-action.js359 B packages/db/dist/esm/paced-mutations.js496 B packages/db/dist/esm/proxy.js3.75 kB packages/db/dist/esm/query/builder/functions.js1.37 kB packages/db/dist/esm/query/builder/index.js5.54 kB packages/db/dist/esm/query/builder/ref-proxy.js1.22 kB packages/db/dist/esm/query/compiler/evaluators.js1.83 kB packages/db/dist/esm/query/compiler/expressions.js430 B packages/db/dist/esm/query/compiler/group-by.js3.54 kB packages/db/dist/esm/query/compiler/index.js4.75 kB packages/db/dist/esm/query/compiler/joins.js2.34 kB packages/db/dist/esm/query/compiler/order-by.js1.72 kB packages/db/dist/esm/query/compiler/select.js1.4 kB packages/db/dist/esm/query/effect.js4.78 kB packages/db/dist/esm/query/expression-helpers.js1.43 kB packages/db/dist/esm/query/ir.js971 B packages/db/dist/esm/query/live-query-collection.js360 B packages/db/dist/esm/query/live/collection-config-builder.js8.01 kB packages/db/dist/esm/query/live/collection-registry.js264 B packages/db/dist/esm/query/live/collection-subscriber.js1.95 kB packages/db/dist/esm/query/live/internal.js145 B packages/db/dist/esm/query/live/utils.js1.75 kB packages/db/dist/esm/query/optimizer.js2.62 kB packages/db/dist/esm/query/predicate-utils.js2.97 kB packages/db/dist/esm/query/query-once.js359 B packages/db/dist/esm/query/subset-dedupe.js960 B packages/db/dist/esm/scheduler.js1.3 kB packages/db/dist/esm/SortedMap.js1.3 kB packages/db/dist/esm/strategies/debounceStrategy.js247 B packages/db/dist/esm/strategies/queueStrategy.js428 B packages/db/dist/esm/strategies/throttleStrategy.js246 B packages/db/dist/esm/transactions.js3.02 kB packages/db/dist/esm/utils.js927 B packages/db/dist/esm/utils/array-utils.js273 B packages/db/dist/esm/utils/browser-polyfills.js304 B packages/db/dist/esm/utils/btree.js5.61 kB packages/db/dist/esm/utils/comparison.js1.05 kB packages/db/dist/esm/utils/cursor.js457 B packages/db/dist/esm/utils/index-optimization.js1.54 kB packages/db/dist/esm/utils/type-guards.js157 B packages/db/dist/esm/virtual-props.js360 B Size Change: 0 B
Total Size: 4.24 kB
compressed-size-action::react-db-package-sizeℹ️ View Unchanged
Filename Size packages/react-db/dist/esm/index.js249 B packages/react-db/dist/esm/useLiveInfiniteQuery.js1.32 kB packages/react-db/dist/esm/useLiveQuery.js1.34 kB packages/react-db/dist/esm/useLiveQueryEffect.js355 B packages/react-db/dist/esm/useLiveSuspenseQuery.js567 B packages/react-db/dist/esm/usePacedMutations.js401 B Thank you for this PR. The goal of lazy React results was correct, and #2043 now applies it to the shared live-query observer.
We are closing this PR for these reasons:
- Point-in-time results. The lazy getter read the live Collection on first access. If a component kept a result without reading it and the Collection then changed, a later read of
dataorstateshowed the new rows instead of the rows from that render. #2043 keeps the entries that the observer captured and buildsstatefrom them on the first read. Its oracle (live-query-observer-snapshot-oracle.property.test.ts) kills the live-read design. - Other parts are done or out of date. #1958 already contains the offline Map/Set lookups. The current scheduler uses the FIFO head's retry time on purpose, so the earliest-retry loop does not apply now.
- Conflicts. All four changed production files conflict with
main, and the branch does not containscripts/perf-bench.ts.
The persistence sort-key and queue-drain changes can return in a new PR if profiling shows a meaningful cost.
- Point-in-time results. The lazy getter read the live Collection on first access. If a component kept a result without reading it and the Collection then changed, a later read of
KyleAMathews(GitHub profile, opens in a new tab) closed this
Sign in to join this conversation.
No actionable comments were generated in the recent review. 🎉
ℹ️ Recent review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID:
1ae91634-25fa-4c63-9595-aaa45e3789da📥 Commits
Reviewing files that changed from the base of the PR and between 4e9ab39241aae3ba17c8bddf744d566de411f9aa and 6c3326f2a40ffbafebb061e40961f1a2daeb04da.
📒 Files selected for processing (9)
.changeset/optimize-hot-paths.mdpackage.jsonpackages/db-sqlite-persistence-core/src/persisted.tspackages/db-sqlite-persistence-core/tests/persisted.test.tspackages/offline-transactions/src/executor/KeyScheduler.tspackages/offline-transactions/src/executor/TransactionExecutor.tspackages/offline-transactions/tests/KeyScheduler.test.tspackages/react-db/src/useLiveQuery.tspackages/react-db/tests/useLiveQuery.test.tsx📝 Walkthrough
Walkthrough#
This PR optimizes hot paths across three packages: stable deterministic ordering and splice-based queue draining in SQLite persistence; Map-based bulk transaction updates and Set-based filtering in offline-transactions; and lazy entry materialization in useLiveQuery to avoid full collection traversal when only status is accessed.
Changes#
Hot-Path Performance Optimizations
packages/db-sqlite-persistence-core/src/persisted.tstoStableSerializablenow uses Schwartzian transform: precomputes JSON representation of each Set/Map entry, sorts by that serialized form, then returns original entries in deterministic order. Hydration and committed-transaction queue flushing switches from repeatedshift()in a loop to snapshot-and-clear viasplice(0), then iteration.packages/db-sqlite-persistence-core/tests/persisted.test.tstx:committedmessages queued during reload flush are applied; and that cursor options with Map/Set values are deduped even when insertion order differs, confirming stable serialization deduplication.packages/offline-transactions/src/executor/KeyScheduler.tsgetEarliestRetryTime()to return minimumnextAttemptAt(ornull). RefactorsupdateTransactions()to build id→transaction map and apply bulk updates in single pass with early-return for empty input, then re-sort bycreatedAtto preserve FIFO.packages/offline-transactions/src/executor/TransactionExecutor.tsfilteredTransactionsIDs for O(1) lookup instead of array check; delegatesgetEarliestRetryTime()entirely to scheduler; cachesDate.now()constant inresetRetryDelaysfor consistent application across all pending transactions.packages/offline-transactions/tests/KeyScheduler.test.tsupdateTransactions()correctness: multiple pending updates, unknown ID filtering, preservation of unchanged entries, deduplication on duplicate IDs, FIFO maintenance, andgetEarliestRetryTime()edge cases (empty/populated).packages/react-db/src/useLiveQuery.tsstateanddatagetters to defer full entry materialization: sharedgetEntries()caches collection entries on first access;databranches intosingleResultCache(findOne) ordataCache(full); status flags (isReady,isError) read from localcollectioninstead of snapshot to avoid forcing entry materialization.packages/react-db/tests/useLiveQuery.test.tsxdata/statereads materialize lazily without forcingvalues()iteration; findOne mode extracts value from shared entries; single-result query returnsundefinedon empty collection.package.json,.changeset/optimize-hot-paths.mdbench:perfnpm script for performance benchmarking; documents patch releases with summary of all hot-path optimizations.🎯 3 (Moderate) | ⏱️ ~25 minutes
🚥 Pre-merge checks | ✅ 4 | ❌ 1
❌ Failed checks (1 warning)#
✅ Passed checks (4 passed)
✨ Finishing Touches
📝 Generate docstrings
🧪 Generate unit tests (beta)
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