Tanstack DB

[Yorizel]

Describe the feature

Support for tanstack db collection integrated with tanstack query

Additional information

• Would you be willing to help implement this feature?

[dinwwwh]

Can you help me draft what the API would look like and how the integration would be useful?

[Yorizel]

sure

[Yorizel]

I think the useful API would be a very small helper, similar in spirit to @orpc/tanstack-query, but scoped only to TanStack DB collection setup.

The goal would not be to create a new sync engine. TanStack DB already has Query Collection, Electric Collection, LocalStorage, RxDB, PowerSync, live queries, schemas, optimistic mutations, error handling, etc.

The oRPC helper would only make it easier to wire typed oRPC procedures into TanStack DB.

Possible API:

import { createORPCTanstackDBUtils } from '@orpc/tanstack-db'
import { createCollection } from '@tanstack/db'

const db = createORPCTanstackDBUtils(orpc)

const todosCollection = createCollection(
  db.todos.list.collectionOptions({
    input: { projectId },
    queryClient,
    getKey: todo => todo.id,
    schema: todoSchema,

    onInsert: db.todos.create.mutationHandler({
      input: mutation => mutation.modified,
    }),

    onUpdate: db.todos.update.mutationHandler({
      input: mutation => ({
        id: mutation.key,
        data: mutation.changes,
      }),
    }),

    onDelete: db.todos.delete.mutationHandler({
      input: mutation => ({ id: mutation.key }),
    }),
  })
)

collectionOptions would be built on top of queryCollectionOptions from @tanstack/query-db-collection.

mutationHandler would return a standard TanStack DB persistence handler. This means it could also be used with other collection option creators when their expected handler return shape is supported.

For example, with Electric-style sync matching, the handler may need to map the oRPC output to the return value expected by the collection:

const todosCollection = createCollection(
  electricCollectionOptions({
    shapeOptions: { url: '/api/todos' },
    getKey: todo => todo.id,
    schema: todoSchema,

    onInsert: db.todos.create.mutationHandler({
      input: mutation => mutation.modified,
      output: result => ({ txid: result.txid }),
    }),

    onUpdate: db.todos.update.mutationHandler({
      input: mutation => ({
        id: mutation.key,
        data: mutation.changes,
      }),
      output: result => ({ txid: result.txid }),
    }),
  })
)

Then live queries stay fully native to TanStack DB:

const { data: openTodos } = useLiveQuery((q) =>
  q
    .from({ todo: todosCollection })
    .where(({ todo }) => eq(todo.status, 'open'))
)

[dinwwwh]

Thanks for the draft, @Yorizel - it actually looks really promise. I'll work on this after v2.0.