feat: improve writeBatch API to use callback pattern

[KyleAMathews]

Overview

This PR improves the writeBatch API in @tanstack/query-db-collection by changing it from accepting an array of operations to accepting a callback function. This provides a more intuitive API similar to database transactions.

Changes

API Improvement

• Changed writeBatch to accept a callback function instead of an array of operations
• Write operations called within the callback are automatically batched together
• This follows the same pattern as getActiveTransaction() in the core DB package

Before

collection.utils.writeBatch([
  { type: 'insert', data: { id: '1', name: 'Item 1' } },
  { type: 'update', data: { id: '2', name: 'Updated' } }
])

After

collection.utils.writeBatch(() => {
  collection.utils.writeInsert({ id: '1', name: 'Item 1' })
  collection.utils.writeUpdate({ id: '2', name: 'Updated' })
})

Documentation

• Added comprehensive documentation for Query Collections in a new "Collections" section
• Documented direct writes as an advanced/escape hatch API
• Included documentation for the meta support feature from feat(query-db-collection): add meta support to QueryCollectionConfig #363
• Explained important behaviors like empty array handling and full state sync

Related Issues

• Addresses feedback from feat(query-db-collection): add manual write methods for direct state updates #303
• Documents behavior discussed in Add Manual Sync Updates API to @tanstack/query-db-collection #294

🤖 Generated with Claude Code

[changeset-bot]

🦋 Changeset detected

Latest commit: 8ce177a

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

This PR includes changesets to release 2 packages

Name	Type
@tanstack/query-db-collection	Minor
@tanstack/db-example-react-todo	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

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

@tanstack/db

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

@tanstack/db-ivm

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

@tanstack/electric-db-collection

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

@tanstack/query-db-collection

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

@tanstack/react-db

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

@tanstack/solid-db

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

@tanstack/svelte-db

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

@tanstack/trailbase-db-collection

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

@tanstack/vue-db

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

commit: 8ce177a

[github-actions]

Size Change: 0 B

Total Size: 58.2 kB

ℹ️ View Unchanged

Filename	Size
./packages/db/dist/esm/change-events.js	1.13 kB
./packages/db/dist/esm/collection.js	9.85 kB
./packages/db/dist/esm/deferred.js	230 B
./packages/db/dist/esm/errors.js	2.98 kB
./packages/db/dist/esm/index.js	1.51 kB
./packages/db/dist/esm/indexes/auto-index.js	689 B
./packages/db/dist/esm/indexes/base-index.js	605 B
./packages/db/dist/esm/indexes/btree-index.js	1.47 kB
./packages/db/dist/esm/indexes/lazy-index.js	1.25 kB
./packages/db/dist/esm/local-only.js	827 B
./packages/db/dist/esm/local-storage.js	2.03 kB
./packages/db/dist/esm/optimistic-action.js	294 B
./packages/db/dist/esm/proxy.js	4.19 kB
./packages/db/dist/esm/query/builder/functions.js	575 B
./packages/db/dist/esm/query/builder/index.js	3.67 kB
./packages/db/dist/esm/query/builder/ref-proxy.js	890 B
./packages/db/dist/esm/query/compiler/evaluators.js	1.48 kB
./packages/db/dist/esm/query/compiler/expressions.js	631 B
./packages/db/dist/esm/query/compiler/group-by.js	2.03 kB
./packages/db/dist/esm/query/compiler/index.js	1.74 kB
./packages/db/dist/esm/query/compiler/joins.js	1.56 kB
./packages/db/dist/esm/query/compiler/order-by.js	703 B
./packages/db/dist/esm/query/compiler/select.js	655 B
./packages/db/dist/esm/query/ir.js	318 B
./packages/db/dist/esm/query/live-query-collection.js	2.45 kB
./packages/db/dist/esm/query/optimizer.js	2.44 kB
./packages/db/dist/esm/SortedMap.js	1.24 kB
./packages/db/dist/esm/transactions.js	2.29 kB
./packages/db/dist/esm/utils.js	419 B
./packages/db/dist/esm/utils/btree.js	5.93 kB
./packages/db/dist/esm/utils/comparison.js	539 B
./packages/db/dist/esm/utils/index-optimization.js	1.62 kB

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

[github-actions]

Size Change: 0 B

Total Size: 1.05 kB

ℹ️ View Unchanged

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

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

[samwillis]

This looks great, very clear api design. Great update to the docs too