tanstack-db

概要

TanStack DB は差分データフローに基づいて構築されたクライアント側の組み込みデータベースレイヤーです。正規化されたコレクションを維持し、ライブクエリのための増分計算を使用し、自動的な楽観的ミューテーションを提供し、データフェッチのために TanStack Query と統合します。100k 行以上であっても 1 ミリ秒未満の更新を実現します。

パッケージ: @tanstack/react-db クエリ統合: @tanstack/query-db-collection ステータス: ベータ版 (v0.5)

インストール

npm install @tanstack/react-db @tanstack/query-db-collection

コア概念

• Collections: データソース (TanStack Query、Electric など) をラップした正規化データストア
• Live Queries: SQL ライクなクエリビルダーによるリアクティブなサブスクリプション
• Optimistic Mutations: 自動的なインスタント UI 更新と失敗時のロールバック
• Differential Dataflow: 変更時に影響を受けるクエリ結果のみを再計算

コレクション

コレクションの作成

import { createCollection } from '@tanstack/react-db'
import { queryCollectionOptions } from '@tanstack/query-db-collection'

const todoCollection = createCollection(
  queryCollectionOptions({
    queryKey: ['todos'],
    queryFn: async () => api.todos.getAll(),
    getKey: (item) => item.id,
    schema: todoSchema,
    onInsert: async ({ transaction }) => {
      await Promise.all(
        transaction.mutations.map((mutation) =>
          api.todos.create(mutation.modified)
        )
      )
    },
    onUpdate: async ({ transaction }) => {
      await Promise.all(
        transaction.mutations.map((mutation) =>
          api.todos.update(mutation.modified)
        )
      )
    },
    onDelete: async ({ transaction }) => {
      await Promise.all(
        transaction.mutations.map((mutation) =>
          api.todos.delete(mutation.original.id)
        )
      )
    },
  })
)

シンクモード

// Eager (デフォルト): コレクション全体を事前にロード。10k 行未満の場合に最適。
const smallCollection = createCollection(
  queryCollectionOptions({ syncMode: 'eager', /* ... */ })
)

// On-Demand: クエリがリクエストしたものだけをロード。50k 行以上、検索に最適。
const largeCollection = createCollection(
  queryCollectionOptions({
    syncMode: 'on-demand',
    queryFn: async (ctx) => {
      const params = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions)
      return api.getProducts(params)
    },
  })
)

// Progressive: クエリサブセットを即座にロード、フルシンクはバックグラウンドで実行。
const collaborativeCollection = createCollection(
  queryCollectionOptions({ syncMode: 'progressive', /* ... */ })
)

ライブクエリ

基本的なクエリ

import { useLiveQuery } from '@tanstack/react-db'
import { eq } from '@tanstack/db'

function TodoList() {
  const { data: todos } = useLiveQuery((query) =>
    query
      .from({ todos: todoCollection })
      .where(({ todos }) => eq(todos.completed, false))
  )

  return <ul>{todos.map(todo => <li key={todo.id}>{todo.text}</li>)}</ul>
}

クエリビルダー API

const { data } = useLiveQuery((q) =>
  q
    .from({ t: todoCollection })
    .where(({ t }) => eq(t.status, 'active'))
    .orderBy(({ t }) => t.createdAt, 'desc')
    .limit(10)
)

ジョイン

const { data } = useLiveQuery((q) =>
  q
    .from({ t: todoCollection })
    .innerJoin(
      { u: userCollection },
      ({ t, u }) => eq(t.userId, u.id)
    )
    .innerJoin(
      { p: projectCollection },
      ({ u, p }) => eq(u.projectId, p.id)
    )
    .where(({ p }) => eq(p.id, currentProject.id))
)

フィルタオペレータ

import { eq, lt, and } from '@tanstack/db'

// 等価比較
eq(field, value)

// より小さい
lt(field, value)

// AND
and(eq(product.category, 'electronics'), lt(product.price, 100))

並べ替えと制限付き

const { data } = useLiveQuery((q) =>
  q
    .from({ product: productsCollection })
    .where(({ product }) =>
      and(eq(product.category, 'electronics'), lt(product.price, 100))
    )
    .orderBy(({ product }) => product.price, 'asc')
    .limit(10)
)

楽観的ミューテーション

挿入

todoCollection.insert({
  id: uuid(),
  text: 'New todo',
  completed: false,
})
// 即座: このコレクションを参照するすべてのライブクエリを更新
// バックグラウンド: onInsert ハンドラを呼び出してサーバーと同期
// 失敗時: 自動ロールバック

手動ボイラープレートなし

Before (TanStack Query のみ)	After (TanStack DB)
楽観的状態の手動 onMutate	自動
手動 onError ロールバックロジック	自動
ミューテーションごとのキャッシュ無効化	すべてのライブクエリが自動更新

クエリドリブンシンク (On-Demand)

ライブクエリは自動的に最適化されたネットワークリクエストを生成します:

// このライブクエリ...
useLiveQuery((q) =>
  q.from({ product: productsCollection })
    .where(({ product }) => and(eq(product.category, 'electronics'), lt(product.price, 100)))
    .orderBy(({ product }) => product.price, 'asc')
    .limit(10)
)

// ...自動的に生成:
// GET /api/products?category=electronics&price_lt=100&sort=price:asc&limit=10

述語マッピング

queryFn: async (ctx) => {
  const { filters, sorts, limit } = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions)

  const params = new URLSearchParams()
  filters.forEach(({ field, operator, value }) => {
    if (operator === 'eq') params.set(field.join('.'), String(value))
    else if (operator === 'lt') params.set(`${field.join('.')}_lt`, String(value))
  })
  if (limit) params.set('limit', String(limit))

  return fetch(`/api/products?${params}`).then(r => r.json())
}

パフォーマンス

操作	レイテンシ
単一行の更新 (100k ソート済みコレクション)	~0.7 ms
後続クエリ (シンク後)	<1 ms
コレクション間のジョイン	1 ミリ秒未満

サポートされているコレクションタイプ

• Query Collection - TanStack Query 統合
• Electric Collection - Electric SQL リアルタイムシンク
• TrailBase Collection - TrailBase バックエンド
• RxDB Collection - RxDB 統合
• PowerSync Collection - PowerSync シンク
• LocalStorage Collection - ブラウザ永続化
• LocalOnly Collection - メモリ内のみ

API サマリー

import { createCollection, useLiveQuery } from '@tanstack/react-db'
import { queryCollectionOptions } from '@tanstack/query-db-collection'
import { eq, lt, and, parseLoadSubsetOptions } from '@tanstack/db'

ベストプラクティス

1. モジュールレベルでコレクションを定義する - シングルトンです
2. 適切なシンクモードを選択する: eager (<10k)、on-demand (>50k)、progressive (コラボレーティブ)
3. ビュー固有の API の代わりにジョインを使用する - 正規化されたコレクションを一度ロード
4. TanStack Query にフェッチを処理させる - DB は Query を拡張し、置き換えません
5. parseLoadSubsetOptions を使用する - ライブクエリ述語を API パラメータにマップ
6. 自動楽観的更新に頼る - 楽観的状態を手動で管理しない
7. スキーマを使用する - ランタイムバリデーションと TypeScript の推論のため
8. 増分計算を活用する - 手動 .filter() の代わりにエンジンにフィルタリングを処理させる

一般的な落とし穴

• コンポーネント内でコレクションを作成する (モジュールレベルである必要があります)
• TanStack Query を完全に置き換えようとする (DB はその上に構築されています)
• レンダリング時に手動 .filter() を使用する (ライブクエリの where 句を使用)
• 適切な正規化のために getKey を指定しない
• サーバーシンクのためのミューテーションハンドラ (onInsert、onUpdate、onDelete) を忘れる