doc: v3 tanstack-query docs #502

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged

ymc9 merged 1 commit into main from doc/wip-tanstack

Nov 5, 2025

.gitmodules

-Original file line number
+Diff line change
@@ Expand Up / @@ -25,3 +25,6 @@ @@
     [submodule "code-repos/zenstackhq/v3-doc-server-adapter"]
     	path = code-repos/zenstackhq/v3-doc-server-adapter
     	url = https://github.com/zenstackhq/v3-doc-server-adapter
+    [submodule "code-repos/zenstackhq/v3-doc-tanstack-query"]
+    	path = code-repos/zenstackhq/v3-doc-tanstack-query
+    	url = https://github.com/zenstackhq/v3-doc-tanstack-query

code-repos/zenstackhq/v3-doc-tanstack-query

Submodule v3-doc-tanstack-query added at 00ced0

docs/reference/plugins/swr.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -5,7 +5,7 @@ sidebar_position: 5
  
    import Invalidation from './_invalidation.md';

    import OptimisticBehavior from './_optimistic-behavior.md';

    import OptmisticLimitation from './_optimistic-limitation.md';

    import OptimisticLimitation from './_optimistic-limitation.md';

    import FineGrainedOptimistic from './_fine-grained-optimistic.md';

    # @zenstackhq/swr

    @@ -201,7 +201,7 @@ When `create` executes, if there are active queries like `useFindManyPost()`, th
  
    #### Limitations

    <OptmisticLimitation />

    <OptimisticLimitation />

    #### Opt-out

docs/reference/plugins/tanstack-query.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -7,7 +7,7 @@ import Tabs from '@theme/Tabs';
  
    import TabItem from '@theme/TabItem';

    import Invalidation from './_invalidation.md';

    import OptimisticBehavior from './_optimistic-behavior.md';

    import OptmisticLimitation from './_optimistic-limitation.md';

    import OptimisticLimitation from './_optimistic-limitation.md';

    import FineGrainedOptimistic from './_fine-grained-optimistic.md';

    # @zenstackhq/tanstack-query

    @@ -662,7 +662,7 @@ When `mutate` executes, if there are active queries like `useFindManyPost()`, th
  
    #### Limitations

    <OptmisticLimitation />

    <OptimisticLimitation />

    #### Opt-out

docusaurus.config.js

-Original file line number
+Diff line change
@@ Expand Up / @@ -234,7 +234,7 @@ const config = { @@
                 prism: {
                     theme: prismThemes.github,
                     darkTheme: prismThemes.dracula,
-                    additionalLanguages: ['json'],
+                    additionalLanguages: ['json', 'tsx'],
                 },
                 zoom: {
@@ Expand Down @@

pnpm-lock.yaml

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

src/components/GithubCodeBlock.tsx

-Original file line number
+Diff line change
@@ Expand Up @@
         const getLanguage = (file: string): string => {
             if (file.endsWith('.ts')) {
                 return 'typescript';
+            } else if (file.endsWith('.tsx')) {
+                return 'tsx';
             } else if (file.endsWith('.zmodel')) {
                 return 'zmodel';
             } else {
@@ Expand Down @@

tsconfig.json

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -1,7 +1,7 @@
  
    {

      // This file is not used in compilation. It is here just for a nice editor experience.

      "extends": "@tsconfig/docusaurus/tsconfig.json",

      "compilerOptions": {

        "baseUrl": "."

      }

        // This file is not used in compilation. It is here just for a nice editor experience.

        "extends": "@tsconfig/docusaurus/tsconfig.json",

        "compilerOptions": {

            "baseUrl": "."

        }

    }

versioned_docs/version-1.x/reference/plugins/swr.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -5,7 +5,7 @@ sidebar_position: 5
  
    import Invalidation from './_invalidation.md';

    import OptimisticBehavior from './_optimistic-behavior.md';

    import OptmisticLimitation from './_optimistic-limitation.md';

    import OptimisticLimitation from './_optimistic-limitation.md';

    # @zenstackhq/swr

    @@ -170,7 +170,7 @@ When `create` executes, if there are active queries like `useFindManyPost()`, th
  
    #### Limitations

    <OptmisticLimitation />

    <OptimisticLimitation />

    #### Opt-out

versioned_docs/version-1.x/reference/plugins/tanstack-query.mdx

            
                      Original file line number
                      Diff line number
                      Diff line change
                  
    @@ -7,7 +7,7 @@ import Tabs from '@theme/Tabs';
  
    import TabItem from '@theme/TabItem';

    import Invalidation from './_invalidation.md';

    import OptimisticBehavior from './_optimistic-behavior.md';

    import OptmisticLimitation from './_optimistic-limitation.md';

    import OptimisticLimitation from './_optimistic-limitation.md';

    # @zenstackhq/tanstack-query

    @@ -430,7 +430,7 @@ When `mutate` executes, if there are active queries like `useFindManyPost()`, th
  
    #### Limitations

    <OptmisticLimitation />

    <OptimisticLimitation />

    #### Opt-out

versioned_docs/version-3.x/reference/cli.md

-Original file line number
+Diff line change
@@ Expand Up / @@ -44,6 +44,8 @@ Options: @@
       --schema <file>      schema file (with extension .zmodel). Defaults to "zenstack/schema.zmodel" unless
                            specified in package.json.
       -o, --output <path>  default output directory for code generation
+      --lite               also generate a lite version of schema without attributes
+      --lite-only          only generate lite version of schema without attributes
       --silent             suppress all output except errors (default: false)
       -h, --help           display help for command
     ```
@@ Expand Down @@

versioned_docs/version-3.x/reference/package.md

This file was deleted.

versioned_docs/version-3.x/service/client-sdk.md

This file was deleted.

versioned_docs/version-3.x/service/client-sdk/_category_.yml

-Original file line number
+Diff line change
@@ -0,0 +1,4 @@
+    position: 3
+    label: Client SDK
+    collapsible: true
+    collapsed: true

versioned_docs/version-3.x/service/client-sdk/index.md

-Original file line number
+Diff line change
@@ -0,0 +1,5 @@
+    # Client SDK
+    You can consume the query services by writing HTTP calls directly, but it's time consuming and error prone. Just as with deriving the CRUD service from the data model, we can derive client SDKs automatically, too.
+    Today, ZenStack provides an [TanStack Query](./tanstack-query) integration that gives you a fully typed and feature-rich query client. Other types of client will be added in the future.

versioned_docs/version-3.x/service/client-sdk/tanstack-query/_category_.yml

-Original file line number
+Diff line change
@@ -0,0 +1,3 @@
+    position: 1
+    collapsible: true
+    collapsed: true

..._docs/version-3.x/service/client-sdk/tanstack-query/_fine-grained-optimistic.md

-Original file line number
+Diff line change
@@ -0,0 +1,25 @@
+    Automatic optimistic update is convenient, but there might be cases where you want to explicitly control how the update happens. You can use the `optimisticUpdateProvider` callback to fully customize how each query cache entry should be optimistically updated. When the callback is set, it takes precedence over the automatic optimistic logic.
+    ```ts
+    client.post.useCreate({
+      optimisticUpdateProvider: ({ queryModel, queryOperation, queryArgs, currentData, mutationArgs }) => {
+        return { kind: 'Update', data: ... /* computed result */ };
+      }
+    });
+    ```
+    The callback is invoked for each query cache entry and receives the following arguments in a property bag:
+    - `queryModel`: The model of the query, e.g., `Post`.
+    - `queryOperation`: The operation of the query, e.g., `findMany`, `count`.
+    - `queryArgs`: The arguments of the query, e.g., `{ where: { published: true } }`.
+    - `currentData`: The current cache data.
+    - `mutationArgs`: The arguments of the mutation, e.g., `{ data: { title: 'My awesome post' } }`.
+    It should return a result object with the following fields:
+    - `kind`: The kind of the optimistic update.
+        - `Update`: update the cache using the computed data
+        - `Skip`: skip the update
+        - `ProceedDefault`: use the default automatic optimistic behavior.
+    - `data`: The computed data to update the cache with. Only used when `kind` is `Update`.

versioned_docs/version-3.x/service/client-sdk/tanstack-query/_invalidation.md

-Original file line number
+Diff line change
@@ -0,0 +1,42 @@
+    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 `client.post.useFindMany()` 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
+    ```ts
+    client.user.useFindUnique({ 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:
+    ```ts
+    updateUser.mutate({ where: { id: userId }, posts: { create: { title: 'post1' } } });
+    ```
+    The mutation will cause queries like ```client.post.useFindMany()``` to be invalidated.
+    **3. Delete Cascade**
+    In ZModel, relations can be configured to cascade delete, e.g.:
+    ```zmodel
+    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 ```client.post.useFindMany()``` will be invalidated.

...oned_docs/version-3.x/service/client-sdk/tanstack-query/_optimistic-behavior.md

-Original file line number
+Diff line change
@@ -0,0 +1,4 @@
+    - `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.
+    - `upsert` mutation first tries to update the item in the query results of `useFindXXX` queries and their nested reads by matching the item's ID. If the item is not found, it inserts the item to the head of the query results.
+    - `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.

...ed_docs/version-3.x/service/client-sdk/tanstack-query/_optimistic-limitation.md

-Original file line number
+Diff line change
@@ -0,0 +1,4 @@
+    - 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 `client.post.useFindMany({ where: { published: true }})`, when a non-published `Post` is created, it'll still be inserted into the query result.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

doc: v3 tanstack-query docs #502

Uh oh!

Diff view

Diff view

There are no files selected for viewing

Uh oh!

Uh oh!

Uh oh!

Uh oh!