localStorageCollectionOptions collection that persists to localStorage and syncs between tabs

[samwillis]

This is a localStorageCollectionOptions to implement a collection that persists to localStorage (or sessionStorate) and syncs between tabs.

---

A localStorageCollectionOptions function was created in packages/db-collections/src/local-storage.ts to provide a collection type backed by browser storage.

• The storage option now uses Pick<Storage, 'getItem' | 'setItem' | 'removeItem'> for direct DOM compatibility, defaulting to window.localStorage.
• The storageEventApi option was refined to a type alias matching Window's event methods for 'storage' events, defaulting to window, ensuring pluggable cross-tab synchronization.
• Collection items are stored in a single key, each with a versionKey (UUID) for efficient change detection, replacing JSON.stringify comparisons.
• onInsert, onUpdate, and onDelete handlers now directly perform storage operations and manually trigger local syncs, as storage events do not fire for the current tab.
• The collection id defaults to local-collection:{storageKey} for predictable naming.
• Files were renamed to local-storage.ts and local-storage.test.ts.
• Linting errors were resolved, and unnecessary await keywords were removed from synchronous collection methods in local-storage.test.ts.
• A local-storage.test-d.ts file was added to validate type compatibility with createCollection.

[changeset-bot]

🦋 Changeset detected

Latest commit: f509b2b

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

This PR includes changesets to release 2 packages

Name	Type
@tanstack/db-collections	Patch
@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]

@tanstack/db-example-react-todo

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

npm i https://pkg.pr.new/@tanstack/db-collections@203

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

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

commit: f509b2b

[github-actions]

Size Change: 0 B

Total Size: 29 kB

ℹ️ View Unchanged

Filename	Size
./packages/db/dist/esm/collection.js	7.87 kB
./packages/db/dist/esm/deferred.js	230 B
./packages/db/dist/esm/errors.js	150 B
./packages/db/dist/esm/index.js	432 B
./packages/db/dist/esm/optimistic-action.js	294 B
./packages/db/dist/esm/proxy.js	3.75 kB
./packages/db/dist/esm/query/compiled-query.js	1.49 kB
./packages/db/dist/esm/query/evaluators.js	1.06 kB
./packages/db/dist/esm/query/extractors.js	870 B
./packages/db/dist/esm/query/functions.js	1.28 kB
./packages/db/dist/esm/query/group-by.js	976 B
./packages/db/dist/esm/query/joins.js	1.14 kB
./packages/db/dist/esm/query/order-by.js	1.42 kB
./packages/db/dist/esm/query/pipeline-compiler.js	878 B
./packages/db/dist/esm/query/query-builder.js	2.14 kB
./packages/db/dist/esm/query/select.js	1.1 kB
./packages/db/dist/esm/query/utils.js	1.13 kB
./packages/db/dist/esm/SortedMap.js	1.24 kB
./packages/db/dist/esm/transactions.js	1.33 kB
./packages/db/dist/esm/utils.js	219 B

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

[github-actions]

Size Change: 0 B

Total Size: 561 B

ℹ️ View Unchanged

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

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

[samwillis]

This is intended to be used for persisting a small amount of state (auth, UI prefs etc), and so it stores it all under one key in local storage.

One thing we should consider is adding some metadata to the JSON blob about the way it was stored. I've currently implanted a versionKey on each key with a uuid, this is used to quickly work out what keys have changed on load. If we change this scheme in future it would be good to know the storage version that is used for auto upgrades. So maybe we need a storageVersion=1.

[KyleAMathews]

Looks great!

Only missing thing is some docs