Exploring a Dexie-native collection integration for TanStack DB

[dfahlander]

Hi! I’m David Fahlander, author of Dexie.js.

I’ve been exploring what a first-class integration between Dexie and TanStack DB could look like. I’m interested in building a small PoC, but I would first like to make sure that its ownership model aligns with TanStack DB’s intended extension points.

Existing work

I’m aware of the earlier work in #575 and #576 and the existing tanstack-dexie-db-collection community package.

I don’t want to disregard or unnecessarily duplicate that work, and I would be happy to collaborate with @HimanshuKumarDutt094.

TanStack DB already provides a capable SQLite/OPFS persistence stack through #865 and #1358. For browser-focused applications, a Dexie-backed persistence implementation could potentially offer a lighter, browser-native alternative that does not require SQLite/WASM and a dedicated SQL worker.

My primary interest, however, goes beyond providing another persistence backend. The integration should preserve Dexie as an application-facing database that can be queried and mutated directly and extended through addons such as Dexie Cloud and y-dexie.

I would therefore like to understand whether TanStack DB’s persistence contract can support an independently mutable, application-facing database, or whether that ownership model requires a custom collection adapter.

Intended ownership model

The goal is for Dexie to remain the authoritative local database and public mutation API, while TanStack DB provides a normalized, reactive, relational in-memory view over selected subsets of that database.

In this model:

• Applications can supply an existing Dexie instance and existing tables.
• Dexie continues to own local storage, schema upgrades and transactions.
• Applications can continue using the full Dexie API, including table.put(), bulkPut(), db.transaction(), where(...).modify() and where(...).delete().
• Mutations may originate outside TanStack DB: through direct Dexie calls, another browser tab, a worker, Dexie Cloud, or another Dexie addon.
• Existing addons such as dexie-export-import, y-dexie and dexie-cloud-addon continue operating on the same database and tables.
• TanStack DB materializes only the subsets required by its active queries.
• Mutations initiated through TanStack DB can delegate to Dexie, but direct Dexie mutations must remain fully supported.
• The integration should not create a second independently owned persisted copy of the same local data.

TanStack DB would not need to reproduce every Dexie API or understand Yjs documents.

For example, an application could use TanStack DB to query documents and relationships while obtaining the actual Y.Doc through y-dexie. Similarly, where(...).modify() could remain a Dexie operation as long as the resulting changes are reflected in the relevant TanStack DB collections.

The important point is that Dexie remains visible and directly usable as the application’s local database rather than becoming only an internal storage driver for TanStack DB.

Possible PoC

A first PoC could expose something along these lines:

const todos = createCollection(
  dexieCollectionOptions(db.todos)
)

Internally, it could:

1. Use on-demand loadSubset() calls to translate TanStack DB predicates, ordering and limits into one-shot Dexie queries.
2. Load the resulting rows into the TanStack DB collection through its sync interface.
3. Delegate TanStack DB mutations to Dexie.
4. Observe mutations made directly through Dexie or its addons.
5. Listen to Dexie’s cross-context storagemutated event for changes made in other tabs or workers.
6. Initially invalidate at table level and reload the subsets required by active TanStack DB queries.
7. Potentially use Dexie’s mutation ranges for more selective invalidation later.

This would allow TanStack DB to provide joins, incremental view maintenance and framework reactivity without requiring an application to abandon its existing Dexie data model or mutation APIs.

Questions about the appropriate integration point

Before choosing between the persistence API and a custom collection adapter, I would appreciate guidance on the following.

1. Which extension point matches this ownership model?

Can persistedCollectionOptions and its persistence contract represent an externally owned and independently mutable local database with its own transaction model and change feed?

If the persistence contract can preserve this ownership model, I’m open to building on it. Otherwise, would this be better implemented as composed collection options or a custom collection adapter whose sync layer materializes data from Dexie into TanStack DB?

2. How should external mutations be propagated?

When a row is changed directly through Dexie, what is the preferred supported way to reflect that change in a TanStack DB collection?

Can an adapter safely emit insert, update and delete messages through the collection sync interface? For coarse invalidation, is truncate() followed by reissuing active subset demands an intended and stable mechanism?

3. Which subset responsibilities belong to TanStack DB core?

Ideally, TanStack DB would own active query demand, request deduplication, subset lifetimes and eviction from the in-memory collection.

The Dexie adapter would translate loadSubset() into a database query and report subsequent changes, without independently maintaining a second query cache. Is that consistent with the current adapter contract?

Next step

If this ownership model makes sense, I would be happy to build a focused PoC covering:

• on-demand filtered and limited subset loading;
• direct Dexie writes;
• TanStack DB mutations delegated to Dexie;
• same-tab and cross-tab insert, update and delete propagation;
• table-level invalidation and active subset reload;
• coexistence with Dexie addons such as dexie-export-import, y-dexie and dexie-cloud-addon;
• tests clarifying which lifecycle responsibilities belong to the adapter and which belong to TanStack DB.

I would also be interested in contributing adapter conformance tests if there is a preferred test contract for collection implementations.

Does this sound like a useful integration direction, and which TanStack DB abstraction would you recommend for preserving this ownership model?