Virtual props RFC implementation

[samwillis]

🎯 Changes

This PR implements the virtual properties system as described in the RFC. This introduces computed, read-only metadata fields prefixed with $ to every row, providing information about its sync status, origin, key, and source collection ID.

Key aspects of this implementation:

• $synced: Indicates whether a row reflects confirmed state from the backend (true) or has pending optimistic mutations (false).
• $origin: Specifies if the last confirmed change originated from the local client ('local') or was received via sync ('remote').
• $key: The primary identifier of the row.
• $collectionId: The ID of the collection the row originated from.
• Pass-through semantics: Virtual properties are preserved and passed through in live queries and nested collections using an "add-if-missing" pattern.
• Queryability: Virtual properties are available for use in query builder expressions (e.g., where(({ item }) => eq(item.$synced, true))).
• Type Integration: Updated RefProxy and Ref types to include virtual properties, ensuring type safety and discoverability.

This feature enhances data visibility and enables more sophisticated UI logic based on the state and origin of data.

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.
• This change is docs/CI/dev-only (no release).

---

 

[cursor]

Cursor Agent can help with this pull request. Just @cursor in comments and I'll start working on changes in this branch.
_{Learn more about Cursor Agents}

[changeset-bot]

⚠️ No Changeset found

Latest commit: 955beed

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[pkg-pr-new]

More templates

• todos
• tanstack-start-example-basic
• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @tanstack/db-example-react-todo
• offline-transactions-react-native
• @tanstack/db-example-solid-todo

@tanstack/angular-db

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

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/electric-db-collection

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

@tanstack/offline-transactions

npm i https://pkg.pr.new/@tanstack/offline-transactions@1213

@tanstack/powersync-db-collection

npm i https://pkg.pr.new/@tanstack/powersync-db-collection@1213

@tanstack/query-db-collection

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

@tanstack/react-db

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

@tanstack/rxdb-db-collection

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 955beed

[github-actions]

Size Change: +1.06 kB (+1.15%)

Total Size: 93 kB

Filename	Size	Change
./packages/db/dist/esm/collection/changes.js	1.38 kB	+159 B (+12.99%)	⚠️
./packages/db/dist/esm/collection/index.js	3.35 kB	+24 B (+0.72%)
./packages/db/dist/esm/collection/state.js	4.01 kB	+523 B (+15%)	⚠️
./packages/db/dist/esm/index.js	2.72 kB	+25 B (+0.93%)
./packages/db/dist/esm/local-only.js	904 B	+67 B (+8%)	🔍
./packages/db/dist/esm/virtual-props.js	258 B	+258 B (new file)	🆕

ℹ️ View Unchanged

Filename	Size
./packages/db/dist/esm/collection/change-events.js	1.39 kB
./packages/db/dist/esm/collection/events.js	388 B
./packages/db/dist/esm/collection/indexes.js	1.1 kB
./packages/db/dist/esm/collection/lifecycle.js	1.75 kB
./packages/db/dist/esm/collection/mutations.js	2.34 kB
./packages/db/dist/esm/collection/subscription.js	3.71 kB
./packages/db/dist/esm/collection/sync.js	2.41 kB
./packages/db/dist/esm/deferred.js	207 B
./packages/db/dist/esm/errors.js	4.7 kB
./packages/db/dist/esm/event-emitter.js	748 B
./packages/db/dist/esm/indexes/auto-index.js	742 B
./packages/db/dist/esm/indexes/base-index.js	766 B
./packages/db/dist/esm/indexes/btree-index.js	2.17 kB
./packages/db/dist/esm/indexes/lazy-index.js	1.1 kB
./packages/db/dist/esm/indexes/reverse-index.js	538 B
./packages/db/dist/esm/local-storage.js	2.1 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	733 B
./packages/db/dist/esm/query/builder/index.js	4.09 kB
./packages/db/dist/esm/query/builder/ref-proxy.js	1.05 kB
./packages/db/dist/esm/query/compiler/evaluators.js	1.42 kB
./packages/db/dist/esm/query/compiler/expressions.js	430 B
./packages/db/dist/esm/query/compiler/group-by.js	1.81 kB
./packages/db/dist/esm/query/compiler/index.js	2.02 kB
./packages/db/dist/esm/query/compiler/joins.js	2.07 kB
./packages/db/dist/esm/query/compiler/order-by.js	1.45 kB
./packages/db/dist/esm/query/compiler/select.js	1.06 kB
./packages/db/dist/esm/query/expression-helpers.js	1.43 kB
./packages/db/dist/esm/query/ir.js	673 B
./packages/db/dist/esm/query/live-query-collection.js	360 B
./packages/db/dist/esm/query/live/collection-config-builder.js	5.43 kB
./packages/db/dist/esm/query/live/collection-registry.js	264 B
./packages/db/dist/esm/query/live/collection-subscriber.js	2.42 kB
./packages/db/dist/esm/query/live/internal.js	145 B
./packages/db/dist/esm/query/optimizer.js	2.56 kB
./packages/db/dist/esm/query/predicate-utils.js	2.97 kB
./packages/db/dist/esm/query/subset-dedupe.js	921 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	2.9 kB
./packages/db/dist/esm/utils.js	924 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	952 B
./packages/db/dist/esm/utils/cursor.js	457 B
./packages/db/dist/esm/utils/index-optimization.js	1.51 kB
./packages/db/dist/esm/utils/type-guards.js	157 B

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

[github-actions]

Size Change: 0 B

Total Size: 3.7 kB

ℹ️ View Unchanged

Filename	Size
./packages/react-db/dist/esm/index.js	225 B
./packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.17 kB
./packages/react-db/dist/esm/useLiveQuery.js	1.34 kB
./packages/react-db/dist/esm/useLiveSuspenseQuery.js	559 B
./packages/react-db/dist/esm/usePacedMutations.js	401 B

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