@zenstackhq/tanstack-query

info

If you're looking for generating hooks for SWR, please checkout the @zenstackhq/swr plugin.

The @zenstackhq/tanstack-query plugin generates Tanstack Query hooks that call into the CRUD services provided by the server adapters. The plugin currently supports React and Svelte. Vue support is coming soon.

The hooks syntactically mirror the APIs of a standard Prisma client, including the function names and shapes of parameters (hooks directly use types generated by Prisma).

To use the generated hooks, you need to install "tanstack-query" for the target framework with version 4.0.0 or above.

Installation

npm install --save-dev @zenstackhq/tanstack-query

Options

Name	Type	Description	Required	Default
output	String	Output directory (relative to the path of ZModel)	Yes
target	String	Target framework to generate for. Choose from "react", "vue", and "svelte".	Yes
version	String	Version of TanStack Query to generate for. Choose from "v4" and "v5".	No	v4

Context Provider

The generated hooks allow you to control their behavior by setting up context. The following options are available on the context:

• endpoint

  The endpoint to use for the queries. Defaults to "/api/model".

• fetch

  A custom fetch function to use for the queries. Defaults to using cross-fetch.

Example for using the context provider:

React

_app.tsx

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { Provider as ZenStackHooksProvider } from '../lib/hooks';
import type { FetchFn } from '@zenstackhq/tanstack-query/runtime';

// custom fetch function that adds a custom header
const myFetch: FetchFn = (url, options) => {
    options = options ?? {};
    options.headers = {
        ...options.headers,
        'x-my-custom-header': 'hello world',
    };
    return fetch(url, options);
};

const queryClient = new QueryClient();

function MyApp({ Component, pageProps: { session, ...pageProps } }: AppProps) {
    return (
        <QueryClientProvider client={queryClient}>
            <ZenStackHooksProvider value={{ endpoint: '/api/model', fetch: myFetch }}>
                <AppContent />
            </ZenStackHooksProvider>
        </QueryClientProvider>
    );
}

export default MyApp;

Vue

App.vue

<script setup lang="ts">
import { provideHooksContext } from '@/lib/hooks';
import type { FetchFn } from '@zenstackhq/tanstack-query/runtime';

const myFetch: FetchFn = (url, options) => {
    options = options ?? {};
    options.headers = {
        ...options.headers,
        'x-my-custom-header': 'hello world',
    };
    return fetch(url, options);
};

provideHooksContext({
    endpoint: 'http://localhost:3000/api/model',
    fetch: myFetch
});
</script>

<template>
    <!-- App Content -->
</template>

Svelte

+layout.svelte

<script lang="ts">
    import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query';
    import { setHooksContext } from '$lib/hooks';
    import type { FetchFn } from '@zenstackhq/tanstack-query/runtime';

    // custom fetch function that adds a custom header
    const myFetch: FetchFn = (url, options) => {
        options = options ?? {};
        options.headers = {
            ...options.headers,
            'x-my-custom-header': 'hello world',
        };
        return fetch(url, options);
    };

    setHooksContext({
        endpoint: '/api/model',
        fetch: myFetch,
    });

    const queryClient = new QueryClient();
</script>

<div>
    <QueryClientProvider client={queryClient}>
        <slot />
    </QueryClientProvider>
</div>

Example

Here's a quick example with a ReactJs blogging app. You can find a fully functional Todo app example here.

Schema

/schema.zmodel

plugin hooks {
  provider = '@zenstackhq/tanstack-query'
  output = "./src/lib/hooks"
  target = "react"
}

model User {
  id            String    @id @default(cuid())
  email         String
  posts         Post[]

  // everyone can signup, and user profile is also publicly readable
  @@allow('create,read', true)
}

model Post {
  id        String @id @default(cuid())
  title     String
  published Boolean @default(false)
  author    User @relation(fields: [authorId], references: [id])
  authorId  String

  // author has full access
  @@allow('all', auth() == author)

  // logged-in users can view published posts
  @@allow('read', auth() != null && published)
}

App Setup

React

_app.tsx

import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { Provider as ZenStackHooksProvider } from '../lib/hooks';

const queryClient = new QueryClient();

function App({ Component, pageProps: { session, ...pageProps } }: AppProps) {
    return (
        <QueryClientProvider client={queryClient}>
            <ZenStackHooksProvider value={{ endpoint: '/api/model' }}>
                <AppContent />
            </ZenStackHooksProvider>
        </QueryClientProvider>
    );
}

Vue

main.ts

import { createApp } from 'vue';
import App from './App.vue';
import { QueryClient, VueQueryPlugin } from '@tanstack/vue-query';

createApp(App)
    .use(VueQueryPlugin, { queryClient: new QueryClient() })
    .mount('#app');

App.vue

<script setup lang="ts">
import { provideHooksContext } from '@/lib/hooks';

provideHooksContext({
    endpoint: 'http://localhost:3000/api/model'
});
</script>

<template>
    <!-- App Content -->
</template>

Svelte

+layout.svelte

<script lang="ts">
    import { setHooksContext } from '$lib/hooks';
    import { QueryClient, QueryClientProvider } from '@tanstack/svelte-query';

    const queryClient = new QueryClient();
    setHooksContext({ endpoint: '/api/model' });
</script>

<div>
    <QueryClientProvider client={queryClient}>
        <slot />
    </QueryClientProvider>
</div>

tip

If you're using SvelteKit, you need to make sure the package @zenstackhq/tanstack-query is not treated as an external dependency by Vite, otherwise you'll encounter errors when the SvelteKit server renders the app. To do this, add the following section into vite.config.js:

/vite.config.js

const config = {
    ...
    ssr: {
        noExternal: ['@zenstackhq/tanstack-query'],
    },
};

export default config;

Using Query and Mutation Hooks

React

/src/components/Posts.tsx

import { useFindManyPost, useCreatePost } from '../lib/hooks';

// post list component
const Posts = ({ userId }: { userId: string }) => {
    const create = useCreatePost();

    // list all posts that're visible to the current user, together with their authors
    const { data: posts } = useFindManyPost({
        include: { author: true },
        orderBy: { createdAt: 'desc' },
    });

    async function onCreatePost() {
        create.mutate({
            data: {
                title: 'My awesome post',
                authorId: userId,
            },
        });
    }

    return (
        <>
            <button onClick={onCreatePost}>Create</button>
            <ul>
                {posts?.map((post) => (
                    <li key={post.id}>
                        {post.title} by {post.author.email}
                    </li>
                ))}
            </ul>
        </>
    );
};

Vue

/src/components/Posts.vue

<script setup lang="ts">
import { useFindManyPost, useCreatePost } from '@/lib/hooks';

const props = defineProps({
    userId: String
});

// list all posts that're visible to the current user, together with their authors
const { data: posts } = useFindManyPost({
    include: { author: true },
    orderBy: { createdAt: 'desc' },
});

const onCreate = () => {
    create.mutate({
        data: {
            title: 'My awesome post',
            authorId: userId,
        }
    });
};
</script>

<template>
    <div>
        <button @click="onCreatePost">Create</button>
        <ul v-if="posts">
            <li v-for="post in posts" :key="post.id">
                {{ post.title }} by {{ post.author.email }}
            </li>
        </ul>
    </div>
</template>

Svelte

/src/components/Posts.svelte

<script lang="ts">
    import { useFindManyPost, useCreatePost } from '../lib/hooks';

    export let userId: string;

    // list all posts that're visible to the current user, together with their authors
    const query = useFindManyPost({
        include: { author: true },
        orderBy: { createdAt: 'desc' },
    });

    const create = useCreatePost();

    function onCreatePost() {
        $create.mutate({
            data: {
                title: 'My awesome post',
                authorId: userId,
            },
        });
    }
</script>

<div>
    <button on:click={onCreatePost}>Create</button>
    <ul>
        {#each $query.data as post (post.id)}
            <li>{post.title} by {post.author.email}</li>
        {/each}
    </ul>
</div>

Automatic Optimistic Update (Preview)

Optimistic update is a technique that allows you to update the data cache immediately when a mutation executes while waiting for the server response. It helps achieve a more responsive UI. TanStack Query provides the infrastructure for implementing it.

The ZenStack-generated mutation hooks allow you to opt-in to "automatic optimistic update" by passing an extra optimisticUpdate argument when calling the hook. When the mutation executes, it analyzes the current queries in the cache and tries to find the ones that need to be updated. When the mutation settles (either succeeded or failed), the queries are invalidated to trigger a re-fetch.

Here's an example:

// arguments are mutation options, invalidate, and optimisticUpdate
const create = useCreatePost(undefined, true, true);

function onCreatePost() {
    create.mutate({ ... })
}

When mutate executes, if there are active queries like useFindManyPost(), the data of the mutation call will be optimistically inserted into the head of the query result.

Details of the optimistic behavior

• create mutation inserts item to the head of the query results of the corresponding useFindMany queries.
• update mutation updates the item in the query results of useFindXXX queries and their nested reads by matching the item's ID.
• delete mutation removes the item from the query results of the corresponding useFindMany queries and sets null to useFindUnique and useFindFirst query results, by matching the item's ID.

Limitations

• The automatic optimistic update relies on ID matching. It only works for queries that select the ID field(s).
• Non-entity-fetching queries like count, aggregate, and groupBy are not affected.
• Infinite queries are not affected.
• It doesn't respect filter conditions or access policies that potentially affect the queries under update. For example, for query useFindManyPost({ where: { published: true }}), when a non-published Post is created, it'll still be inserted into the query result.

Opt-out

By default, all queries opt into automatic optimistic update. You can opt-out on a per-query basis by passing false to the optimisticUpdate argument.

// arguments are query args, query options, and optimisticUpdate
const { data } = useFindManyPost({ where: { published: true } }, undefined, false);

When a query opts out, it won't be updated by a mutation, even if the mutation is set to update optimistically.

Using Infinite Query

React

Here's a quick example of using infinite query to load a list of posts with infinite pagination. See Tanstack Query documentation for more details.

/src/components/Posts.tsx

import { useInfiniteFindManyPost } from '../lib/hooks';

// post list component with infinite loading
const Posts = () => {
    const PAGE_SIZE = 10;

    const fetchArgs = {
        include: { author: true },
        orderBy: { createdAt: 'desc' as const },
        take: PAGE_SIZE,
    };

    const { data, fetchNextPage, hasNextPage } = useInfiniteFindManyPost(fetchArgs, {
        getNextPageParam: (lastPage, pages) => {
            if (lastPage.length < PAGE_SIZE) {
                return undefined;
            }
            const fetched = pages.flatMap((item) => item).length;
            return {
                ...fetchArgs,
                skip: fetched,
            };
        },
    });    

    return (
        <>
            <ul>
                {data?.pages.map((posts, i) => (
                    <React.Fragment key={i}>
                        {posts?.map((post) => (
                            <li key={post.id}>
                                {post.title} by {post.author.email}
                            </li>
                        ))}
                    </React.Fragment>
                ))}
            </ul>
            {hasNextPage && (
                <button onClick={() => fetchNextPage()}>
                    Load more
                </button>
            )}
        </>
    );
};

Vue

Here's a quick example of using infinite query to load a list of posts with infinite pagination. See Tanstack Query documentation for more details.

/src/components/Posts.vue

<script setup lang="ts">
// post list component with infinite loading

import { useInfiniteFindManyPost } from '@/lib/hooks';

const PAGE_SIZE = 10;

const fetchArgs = {
    include: { author: true },
    orderBy: { createdAt: 'desc' as const },
    take: PAGE_SIZE,
};

const { data, hasNextPage, fetchNextPage } = useInfiniteFindManyPost(
    fetchArgs,
    {
        getNextPageParam: (lastPage, pages) => {
            if (lastPage.length < PAGE_SIZE) {
                return undefined;
            }
            const fetched = pages.flatMap((item) => item).length;
            return {
                ...fetchArgs,
                skip: fetched,
            };
        },
    }
);
</script>

<template>
    <div>
        <ul v-if="data">
            <template v-for="(posts, i) in data.pages" :key="i">
                <li v-for="post in posts" :key="post.id">
                    {{ post.title }} by {{ post.author.email }}
                </li>
            </template>
        </ul>
    </div>

    <button v-if="hasNextPage" @click="() => fetchNextPage()">Load More</button>
</template>

Svelte

Here's a quick example of using infinite query to load a list of posts with infinite pagination. See Tanstack Query documentation for more details.

/src/components/Posts.svelte

<script lang="ts">
    // post list component with infinite loading

    import { useInfiniteFindManyPost } from '../lib/hooks';

    const PAGE_SIZE = 10;

    const fetchArgs = {
        include: { author: true },
        orderBy: { createdAt: 'desc' as const },
        take: PAGE_SIZE,
    };

    const query = useInfiniteFindManyPost(fetchArgs, {
        getNextPageParam: (lastPage, pages) => {
            if (lastPage.length < PAGE_SIZE) {
                return undefined;
            }
            const fetched = pages.flatMap((item) => item).length;
            return {
                ...fetchArgs,
                skip: fetched,
            };
        },
    });    
</script>

<div>
    <ul>
        <div>
            {#if $query.data}
                {#each $query.data.pages as posts, i (i)}
                    {#each posts as post (post.id)}
                        <li>{post.title} by {post.author.email}</li>
                    {/each}
                {/each}
            {/if}
        </div>
    </ul>
    {#if $query.hasNextPage}
        <button on:click={() => $query.fetchNextPage()}>
            Load more
        </button>
    {/if}
</div>

Advanced

Query Invalidation

The mutation hooks generated by ZenStack automatically invalidates the queries that are potentially affected by the changes. For example, if you create a Post, the useFindManyPost query will be automatically invalidated when the mutation succeeds. Invalidation causes cache to be purged and fresh data to be refetched.

The automatic invalidation takes care of nested read, write, and delete cascading.

1. Nested Read

Nested reads are also subject to automatic invalidation. For example, if you create a Post, the query made by

useFindUniqueUser({ where: { id: userId }, include: { posts: true } });

will be invalidated.

2. Nested Write

Similarly, nested writes also trigger automatic invalidation. For example, if you create a Post in a nested update to User like:

updateUser({ where: { id: userId }, posts: { create: { title: 'post1' } } });

The mutation will cause queries like useFindManyPost() to be invalidated.

3. Delete Cascade

In ZModel, relations can be configured to cascade delete, e.g.:

model User {
    ...
    posts Post[]
}

model Post {
    ...
    user User @relation(fields: [userId], references: [id], onDelete: Cascade)
    userId Int
}

When a User is deleted, the Post entities it owns will be deleted automatically. The generated hooks takes cascade delete into account. For example, if you delete a User, Post model will be considered as affected and queries like useFindManyPost() will be invalidated.

info

The automatic invalidation is enabled by default, and you can use the invalidateQueries argument to opt-out and handle revalidation by yourself.

// arguments are mutation options and invalidateQueries
useCreatePost(undefined, false);

Query Key

Query keys serve as unique identifiers for organizing the query cache. The generated hooks use the following query key scheme:

['zenstack', model, operation, args, flags]

For example, the query key for

useFindUniqueUser({ where: { id: '1' } })

will be:

['zenstack', 'User', 'findUnique', { where: { id: '1' } }, { infinite: false }]

You can use the generated getQueryKey function to compute it.