Tanstack DB in action

The team at TanStack, makers of TanStack Query (aka react-query), partnered with the ElectricSQL team to give us something truly awesome.

This library excites me for two reasons:

Why it excites me

Joining data from multiple sources

Anything you can express as a collection can be joined to another collection with SQL-like semantics, and the library automatically handles mitigating against N+1 queries.

typescript

1// Left join - all users, even without posts
2const allUsers = createLiveQueryCollection((q) =>
3  q
4    .from({ user: usersCollection })
5    .leftJoin({ post: postsCollection }, ({ user, post }) => eq(user.id, post.userId)),
6);

Basic local-first functionality

The library shipped persistence in its latest version, backed by SQLite with Web and React Native adapters, enabling true local-first approaches—all while remaining provider- and backend-agnostic.

In my usage of the library, I have discovered a few cool approaches that make life with this library better.

The Basics

TanStack DB comes with adapters for many local-first providers, but in our case, we'll be using the TanStack Query adapter since it lets us progressively enhance.

From useQuery to a collection

Let's take the example of a movie app:

tsx

1import { useQuery } from "@tanstack/react-query";
2
3export function MovieListWithUseQuery() {
4  // TODO: add filters from url search params
5  const filters = {
6    page: 1,
7    perPage: 10,
8    q: "",
9    sortBy: "vote_average",
10    sortDirection: "desc",
11    includeTotal: true,
12  } as const;
13  const { data, isLoading } = useQuery({
14    queryKey: ["movies-with-use-query"],
15    queryFn: () =>
16      getPaginatedFakeMoviesFn({
17        data: filters,
18      }),
19  });
20
21  return (
22    <div className="w-full flex flex-col">
23      <h1 className="text-2xl font-bold">Movies</h1>
24      {isLoading ? (
25        <div>Loading...</div>
26      ) : (
27        <div>
28          {data?.items.map((movie) => (
29            <div key={movie.id}>{movie.title}</div>
30          ))}
31        </div>
32      )}
33    </div>
34  );
35}

This is a nice starting point for us to port. We start by creating the collection definition:

typescript

1export const moviesCollection = createCollection(
2  queryCollectionOptions({
3    queryKey: [PAGINATED_MOVIES_COLLECTION_QUERY_KEY],
4    queryFn: async (ctx) => {
5      const filters = {
6        page: 1,
7        perPage: 10,
8        q: "",
9        sortBy: "vote_average",
10        sortDirection: "desc",
11        includeTotal: true,
12      } as const;
13      const response = await getPaginatedFakeMoviesFn({
14        data: filters,
15      });
16      return response;
17    },
18    select: (data) => data.items,
19    queryClient: getQueryClient(),
20    getKey: (item) => item.id,
21    autoIndex: "eager",
22    defaultIndexType: BasicIndex,
23    staleTime: 1000 * 60 * 60,
24  }),
25);

1import { useQueryClient } from "@tanstack/react-query";

3export type MetaObject<T = unknown> = {

4 items: T[];

5 page?: number | undefined;

6 perPage?: number | undefined;

7 q?: string | undefined;

8 totalItems?: number | undefined;

9 totalPages?: number | undefined;

10};

12export type DBQueryMetaObject<T> = {

13 queryKey: readonly unknown[] | undefined;

14 meta: MetaObject<T> | undefined;

15};

17export type TSDBQueryMetaMatch = {

18 page?: number;

19 q?: string;

20};

22export function useTSDBQueryMeta(queryKey: string, match?: TSDBQueryMetaMatch) {

23 const qc = useQueryClient();

24 const queriesData = qc.getQueriesData({ queryKey: [queryKey] });

26 const metaObject = parseAndFindMetaObject(queriesData, queryKey, match);

27 return metaObject;

28}

30export function parseAndFindMetaObject<T>(

31 queryData: [readonly unknown[], unknown][],

32 queryKey: string,

33 match?: TSDBQueryMetaMatch,

34) {

35 const candidates = queryData.filter(([, data]) => isMetaObject(data));

37 const keyed = candidates.filter(([key]) =>

38 key.some((part) => typeof part === "string" && part.includes(queryKey)),

39 );

41 const pool = keyed.length > 0 ? keyed : candidates;

43 const matched = match

44 ? pool.find(([, data]) => metaMatches(data as MetaObject, match))

45 : undefined;

47 const metaObject = matched ?? pool.at(-1);

49 if (!metaObject) {

50 return {

51 queryKey: undefined,

52 meta: undefined,

53 };

54 }

56 return {

57 queryKey: metaObject[0],

58 meta: metaObject[1] as MetaObject<T>,

59 } satisfies DBQueryMetaObject<T>;

60}

62function isMetaObject(data: unknown): data is MetaObject {

63 return (

64 !!data &&

65 typeof data === "object" &&

66 "items" in data &&

67 Array.isArray((data as MetaObject).items)

68 );

69}

71function metaMatches(data: MetaObject, match: TSDBQueryMetaMatch) {

72 if (match.page != null && data.page != null && data.page !== match.page) {

73 return false;

74 }

76 const wantedQ = (match.q ?? "").trim();

77 const cachedQ = (data.q ?? "").trim();

78 if (wantedQ !== cachedQ) {

79 return false;

80 }

82 return true;

83}

85// usage

86const { meta } = useTSDBQueryMeta(PAGINATED_MOVIES_COLLECTION_QUERY_KEY, {

87 page,

88 q,

89});

90// meta.page

91// meta.totalItems

92// meta.totalPages...

1import { parseWhereWithHandlers } from "@/lib/tanstack/db/utils";

2import { BasicIndex, createCollection, parseLoadSubsetOptions } from "@tanstack/db";

3import { queryCollectionOptions } from "@tanstack/query-db-collection";

5export const PAGINATED_MOVIES_COLLECTION_QUERY_KEY = "query-driven-movies";

6export const WATCHLIST_COLLECTION_QUERY_KEY = "query-driven-watchlist";

8const MOVIE_SORT_KEYS = [

9 "title",

10 "overview",

11 "vote_average",

12 "release_date",

13 "popularity",

14] as const;

16type MoviesWhereClause = {

17 page?: { _eq: number };

18 q?: { _eq?: string; _ilike?: string };

19};

21function parseSearchQ(where: MoviesWhereClause | null | undefined) {

22 const raw = where?.q?._eq ?? where?.q?._ilike;

23 if (!raw) return undefined;

24 const stripped = raw.replace(/^%|%$/g, "").trim();

25 return stripped || undefined;

26}

28export const queryDrivenMoviesCollection = createCollection(

29 queryCollectionOptions({

30 queryKey: [PAGINATED_MOVIES_COLLECTION_QUERY_KEY],

31 queryFn: async (ctx) => {

32 const where = parseWhereWithHandlers<MoviesWhereClause>(ctx.meta?.loadSubsetOptions?.where); //this will now be available

33 const { sorts } = parseLoadSubsetOptions(ctx.meta?.loadSubsetOptions);

34 const page = where?.page?._eq ?? 1;

35 const q = parseSearchQ(where);

36 const primarySort = sorts[0];

37 const { sortBy, sortOrder: sortDirection } = resolveSortOrder({

38 sortBy: primarySort ? String(primarySort.field.at(-1)) : undefined,

39 sortOrder: primarySort?.direction,

40 allowedKeys: MOVIE_SORT_KEYS,

41 defaultSortBy: "vote_average",

42 defaultSortOrder: "desc",

43 });

44 const response = await getPaginatedFakeMoviesFn({

45 data: { page, perPage: 10, q, sortBy, sortDirection, includeTotal: true },

46 });

47 return response;

48 },

49 select: (data) => data.items,

50 queryClient: getQueryClient(),

51 getKey: (item) => item.id,

52 autoIndex: "eager",

53 defaultIndexType: BasicIndex,

54 syncMode: "on-demand",

55 staleTime: 1000 * 60 * 60,

56 }),

57);

Tanstack DB in action

Reasons to Still Use Next.js from a TanStack Start Enjoyer

🎨 TanStack Start SSR-Friendly Theme Provider

React devs KE 🇰🇪 Meetup February 2025 | Crafting Reusable Code with React & TypeScript: From Design to NPM

Tanstack DB in action

Reasons to Still Use Next.js from a TanStack Start Enjoyer

🎨 TanStack Start SSR-Friendly Theme Provider

React devs KE 🇰🇪 Meetup February 2025 | Crafting Reusable Code with React & TypeScript: From Design to NPM

Why it excites me

Joining data from multiple sources

Basic local-first functionality

The Basics

From `useQuery` to a collection

Querying with `useLiveQuery`

Joining with another collection

Handling non-array responses

Client-side infinite query

Query-driven sync

Persistence

Conclusions

Wishlist

A meta object from `useLiveQuery` into the collection

`placeholderData` and `isRefetching`

References

More posts

Reasons to Still Use Next.js from a TanStack Start Enjoyer

🎨 TanStack Start SSR-Friendly Theme Provider

React devs KE 🇰🇪 Meetup February 2025 | Crafting Reusable Code with React & TypeScript: From Design to NPM

More posts

Reasons to Still Use Next.js from a TanStack Start Enjoyer

🎨 TanStack Start SSR-Friendly Theme Provider

React devs KE 🇰🇪 Meetup February 2025 | Crafting Reusable Code with React & TypeScript: From Design to NPM

Why it excites me

Joining data from multiple sources

Basic local-first functionality

The Basics

From useQuery to a collection

Querying with useLiveQuery

Joining with another collection

Handling non-array responses

Reading pagination metadata from the query store

Pagination

Client-side infinite query

Query-driven sync

Persistence

Conclusions

Wishlist

A meta object from useLiveQuery into the collection

placeholderData and isRefetching

References

From `useQuery` to a collection

Querying with `useLiveQuery`

A meta object from `useLiveQuery` into the collection

`placeholderData` and `isRefetching`