fix(db): require exact Collection.update keys

[KyleAMathews]

Summary

Collection.update now requires every key to match the collection's declared TKey across single, bulk, config, and no-config overloads. Wrong key domains and erased branded keys are rejected at compile time instead of compiling and then missing the exact runtime lookup; runtime behavior is unchanged.

Root Cause

The public overloads and matching internal signatures used TKey | unknown. A union with unknown collapses to unknown, so a numeric-key collection accepted calls such as collection.update('1', ...) even though get, delete, mutation-handler keys, and the runtime state lookup all preserve the exact key type.

Approach

• Narrow the four public overloads from TKey | unknown to TKey, including their array forms.
• Carry TKey | Array<TKey> through the implementation and mutation manager without changing execution.
• Add a dedicated type oracle covering numeric, string, and branded keys; single and bulk updates; config and no-config overloads; direct calls and optimistic-action-owned calls.
• Keep get, delete, callback draft types, and handler mutation keys as independent controls.
• Mark the known bulk-test fixture elements as present now that undefined is no longer admitted accidentally.
• Add a minor changeset for @tanstack/db.

Key Invariants

• Every update admission path preserves the collection's exact TKey.
• Bulk keys have the same element type as single keys.
• Update callbacks remain WritableDeep<TInput> and overload selection remains unchanged.
• Calls inside createOptimisticAction have the same key contract as direct calls.
• Runtime JavaScript and mutation behavior remain unchanged.

Non-goals

• No runtime key coercion or lookup changes.
• No action-only mutation enforcement.
• No changes to async onMutate typing.
• No field-guard or key-field mutation design.
• No unrelated public API changes.

Trade-offs

This is a public type narrowing, so code that previously passed a sibling key domain or plain string in place of a branded key will now fail compilation. Those calls could not address the intended row under the existing exact runtime lookup, so the narrow correction aligns update with the rest of the collection API without adding runtime complexity.

Consumers passing possibly undefined keys (including unchecked indexed access) or plain strings to branded-key collections must narrow or assert those values to the declared key type before calling update.

Verification

pnpm --dir packages/db exec vitest run tests/collection-update-key-types.test-d.ts --coverage.enabled=false --maxWorkers=2
pnpm --dir packages/db exec vitest run --coverage.enabled=false --maxWorkers=2
pnpm --filter @tanstack/db-ivm build
pnpm --filter @tanstack/db build
pnpm run build

• Focused owner suite: 9 files / 223 tests passed with no type errors.
• Full DB suite: 208 files / 6,266 tests passed with no type errors.
• Workspace build, changed-file ESLint, Prettier, and git diff --check passed.
• Reverting to TKey | unknown made all 18 wrong-update controls fail as unused @ts-expect-error directives.
• Widening to string | number was also killed by the numeric, string, and branded-key controls.
• Baseline-vs-change artifact comparison found every ESM/CJS runtime file byte-identical; only the expected collection declarations changed.

Files changed

• packages/db/src/collection/index.ts: narrows the four public update overloads and implementation key parameter.
• packages/db/src/collection/mutations.ts: narrows the matching internal manager key parameter.
• packages/db/tests/collection-update-key-types.test-d.ts: adds the exact-key contract oracle and hostile-widening controls.
• packages/db/tests/collection.test.ts: marks known bulk fixture positions as present for the exact key signature.
• .changeset/fix-collection-update-key-types.md: records the @tanstack/db minor changeset.

Summary by CodeRabbit

• Bug Fixes

  • Collection updates now require keys matching the collection’s declared key type.
  • Improved type safety for single-item, bulk, and configured updates.
  • Invalid key types, including numeric, string, and branded keys, are detected during compilation.
  • Values that may be undefined must be narrowed or asserted before being used as update keys.

• Tests

  • Added coverage for key-type enforcement across collection operations and optimistic updates.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Advanced

Run ID: b017a3d4-e806-4ac1-90eb-556e9837487c

📥 Commits

Reviewing files that changed from the base of the PR and between 630bd5d and 7adbbd5.

📒 Files selected for processing (1)

• .changeset/fix-collection-update-key-types.md

Included review availability: Your plan provides up to 8 included reviews per hour; 5 remain after this review.

---

📝 Walkthrough

Walkthrough

Collection.update now requires keys to match the collection's declared key type. Type-level tests cover numeric, string, and branded keys across update overloads, optimistic actions, and related operations. Test calls add non-null assertions where needed.

Changes

Collection update key type enforcement

Layer / File(s)	Summary
Narrow update key contracts packages/db/src/collection/index.ts, packages/db/src/collection/mutations.ts, .changeset/fix-collection-update-key-types.md	Collection.update and the mutation manager now accept TKey or Array<TKey>. The changeset records a minor release for @tanstack/db.
Validate key type preservation packages/db/tests/collection-update-key-types.test-d.ts, packages/db/tests/collection.test.ts, packages/trailbase-db-collection/tests/trailbase.test.ts	Type-level tests cover numeric, string, and branded keys across update overloads, optimistic actions, and related operations. Runtime test calls add non-null assertions without changing behavior.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~15 minutes

Change: Bug fix

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 5…
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Title check	✅ Passed	The title clearly and concisely describes the main change: requiring exact key types for Collection.update.
Description check	✅ Passed	The description is detailed and covers the change, motivation, implementation, non-goals, trade-offs, verification, and changeset. It does not use the template headings or checklist format, but it pro…

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Commit to this branch
• Create a new PR

---

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.}

[pkg-pr-new]

More templates

• todos
• @tanstack/db-example-react-next-ssr-e2e
• tanstack-start-example-basic
• @tanstack/db-example-paced-mutations-demo
• tanstack-start-db-projects-example
• @tanstack/db-example-react-start-ssr-e2e
• @tanstack/db-example-react-todo
• offline-first-electron
• offline-transactions-react-native
• shopping-list-react-native
• @tanstack/db-example-solid-todo

@tanstack/angular-db

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

@tanstack/browser-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/browser-db-sqlite-persistence@1851

@tanstack/capacitor-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/capacitor-db-sqlite-persistence@1851

@tanstack/cloudflare-durable-objects-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/cloudflare-durable-objects-db-sqlite-persistence@1851

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/db-sqlite-persistence-core

npm i https://pkg.pr.new/@tanstack/db-sqlite-persistence-core@1851

@tanstack/electric-db-collection

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

@tanstack/electron-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/electron-db-sqlite-persistence@1851

@tanstack/expo-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/expo-db-sqlite-persistence@1851

@tanstack/node-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/node-db-sqlite-persistence@1851

@tanstack/offline-transactions

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

@tanstack/powersync-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

@tanstack/react-native-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/react-native-db-sqlite-persistence@1851

@tanstack/react-router-with-db

npm i https://pkg.pr.new/@tanstack/react-router-with-db@1851

@tanstack/rxdb-db-collection

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/tauri-db-sqlite-persistence

npm i https://pkg.pr.new/@tanstack/tauri-db-sqlite-persistence@1851

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 7adbbd5

[github-actions]

Size Change: 0 B

Total Size: 165 kB

ℹ️ View Unchanged

Filename	Size
packages/db/dist/esm/client.js	3.66 kB
packages/db/dist/esm/collection-options.js	236 B
packages/db/dist/esm/collection/change-events.js	1.44 kB
packages/db/dist/esm/collection/changes.js	2.25 kB
packages/db/dist/esm/collection/cleanup-queue.js	794 B
packages/db/dist/esm/collection/events.js	481 B
packages/db/dist/esm/collection/index.js	4.63 kB
packages/db/dist/esm/collection/indexes.js	1.99 kB
packages/db/dist/esm/collection/lifecycle.js	2.15 kB
packages/db/dist/esm/collection/mutations.js	2.61 kB
packages/db/dist/esm/collection/state.js	6.51 kB
packages/db/dist/esm/collection/subscription.js	8.72 kB
packages/db/dist/esm/collection/sync.js	4.62 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.26 kB
packages/db/dist/esm/event-emitter.js	964 B
packages/db/dist/esm/index.js	3.71 kB
packages/db/dist/esm/indexes/auto-index.js	829 B
packages/db/dist/esm/indexes/base-index.js	1.14 kB
packages/db/dist/esm/indexes/basic-index.js	2.07 kB
packages/db/dist/esm/indexes/btree-index.js	2.26 kB
packages/db/dist/esm/indexes/index-registry.js	820 B
packages/db/dist/esm/indexes/reverse-index.js	376 B
packages/db/dist/esm/live-query-adapter.js	318 B
packages/db/dist/esm/live-query-observer.js	3.69 kB
packages/db/dist/esm/live-query-options.js	702 B
packages/db/dist/esm/live-query-window-controller.js	4.36 kB
packages/db/dist/esm/local-only.js	989 B
packages/db/dist/esm/local-storage.js	2.17 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.32 kB
packages/db/dist/esm/query/builder/functions.js	1.47 kB
packages/db/dist/esm/query/builder/index.js	6.69 kB
packages/db/dist/esm/query/builder/query-ir.js	116 B
packages/db/dist/esm/query/builder/ref-proxy.js	1.24 kB
packages/db/dist/esm/query/compiler/evaluators.js	1.92 kB
packages/db/dist/esm/query/compiler/expressions.js	560 B
packages/db/dist/esm/query/compiler/group-by.js	4.13 kB
packages/db/dist/esm/query/compiler/index.js	9.06 kB
packages/db/dist/esm/query/compiler/joins.js	2.95 kB
packages/db/dist/esm/query/compiler/lazy-targets.js	1.1 kB
packages/db/dist/esm/query/compiler/order-by.js	1.91 kB
packages/db/dist/esm/query/compiler/parent-routes.js	319 B
packages/db/dist/esm/query/compiler/route-metadata.js	1.24 kB
packages/db/dist/esm/query/compiler/select.js	1.58 kB
packages/db/dist/esm/query/effect.js	4.6 kB
packages/db/dist/esm/query/equality-value-identity.js	591 B
packages/db/dist/esm/query/expression-helpers.js	1.43 kB
packages/db/dist/esm/query/ir-stable-identity.js	4.04 kB
packages/db/dist/esm/query/ir.js	1.59 kB
packages/db/dist/esm/query/live-query-collection.js	391 B
packages/db/dist/esm/query/live/bucket-facade-adapter.js	2.73 kB
packages/db/dist/esm/query/live/collection-config-builder.js	6.97 kB
packages/db/dist/esm/query/live/collection-registry.js	264 B
packages/db/dist/esm/query/live/collection-subscriber.js	2.25 kB
packages/db/dist/esm/query/live/internal.js	145 B
packages/db/dist/esm/query/live/materialized-pipeline.js	2.32 kB
packages/db/dist/esm/query/live/ordered-source-loader.js	3.14 kB
packages/db/dist/esm/query/live/subset-demand-controller.js	1.26 kB
packages/db/dist/esm/query/live/utils.js	1.14 kB
packages/db/dist/esm/query/optimizer.js	2.91 kB
packages/db/dist/esm/query/query-once.js	359 B
packages/db/dist/esm/query/runtime-reference-identity.js	572 B
packages/db/dist/esm/query/subset-dedupe.js	486 B
packages/db/dist/esm/scheduler.js	1.34 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.71 kB
packages/db/dist/esm/utils.js	1.08 kB
packages/db/dist/esm/utils/array-utils.js	270 B
packages/db/dist/esm/utils/browser-polyfills.js	304 B
packages/db/dist/esm/utils/btree.js	4.51 kB
packages/db/dist/esm/utils/callbacks.js	174 B
packages/db/dist/esm/utils/comparison.js	1.49 kB
packages/db/dist/esm/utils/cursor.js	676 B
packages/db/dist/esm/utils/error.js	167 B
packages/db/dist/esm/utils/get-or-create.js	155 B
packages/db/dist/esm/utils/index-optimization.js	2.42 kB
packages/db/dist/esm/utils/type-guards.js	230 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: 7.34 kB

ℹ️ View Unchanged

Filename	Size
packages/react-db/dist/esm/DbProvider.js	317 B
packages/react-db/dist/esm/HydrationBoundary.js	263 B
packages/react-db/dist/esm/index.js	330 B
packages/react-db/dist/esm/live-query-internals.js	282 B
packages/react-db/dist/esm/useLiveInfiniteQuery.js	1.9 kB
packages/react-db/dist/esm/useLiveQuery.js	2.68 kB
packages/react-db/dist/esm/useLiveQueryEffect.js	355 B
packages/react-db/dist/esm/useLiveSuspenseQuery.js	812 B
packages/react-db/dist/esm/usePacedMutations.js	401 B

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