doc: v3 tanstack-query docs (#502)

ymc9 · web-flow · commit fbf6940caa89 · 2025-11-05T12:49:22.000-08:00
diff --git a/.gitmodules b/.gitmodules
@@ -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
diff --git a/code-repos/zenstackhq/v3-doc-tanstack-query b/code-repos/zenstackhq/v3-doc-tanstack-query
@@ -0,0 +1 @@
+Subproject commit 00ced0d2badfee3bb5e0bac819a0ae062dce8e68
diff --git a/docs/reference/plugins/swr.mdx b/docs/reference/plugins/swr.mdx
@@ -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
 
diff --git a/docs/reference/plugins/tanstack-query.mdx b/docs/reference/plugins/tanstack-query.mdx
@@ -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
 
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -234,7 +234,7 @@ const config = {
             prism: {
                 theme: prismThemes.github,
                 darkTheme: prismThemes.dracula,
-                additionalLanguages: ['json'],
+                additionalLanguages: ['json', 'tsx'],
             },
 
             zoom: {
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/src/components/GithubCodeBlock.tsx b/src/components/GithubCodeBlock.tsx
@@ -11,6 +11,8 @@ const GithubCodeBlock: React.FC<GithubCodeBlockProps> = ({ repoPath, file }) =>
     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 {
diff --git a/tsconfig.json b/tsconfig.json
@@ -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": "."
+    }
 }
diff --git a/versioned_docs/version-1.x/reference/plugins/swr.mdx b/versioned_docs/version-1.x/reference/plugins/swr.mdx
@@ -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
 
diff --git a/versioned_docs/version-1.x/reference/plugins/tanstack-query.mdx b/versioned_docs/version-1.x/reference/plugins/tanstack-query.mdx
@@ -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
 
diff --git a/versioned_docs/version-3.x/reference/cli.md b/versioned_docs/version-3.x/reference/cli.md
@@ -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
 ```
diff --git a/versioned_docs/version-3.x/reference/package.md b/versioned_docs/version-3.x/reference/package.md
diff --git a/versioned_docs/version-3.x/service/client-sdk.md b/versioned_docs/version-3.x/service/client-sdk.md
diff --git a/versioned_docs/version-3.x/service/client-sdk/_category_.yml b/versioned_docs/version-3.x/service/client-sdk/_category_.yml
@@ -0,0 +1,4 @@
+position: 3
+label: Client SDK
+collapsible: true
+collapsed: true
diff --git a/versioned_docs/version-3.x/service/client-sdk/index.md b/versioned_docs/version-3.x/service/client-sdk/index.md
@@ -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.
diff --git a/versioned_docs/version-3.x/service/client-sdk/tanstack-query/_category_.yml b/versioned_docs/version-3.x/service/client-sdk/tanstack-query/_category_.yml
@@ -0,0 +1,3 @@
+position: 1
+collapsible: true
+collapsed: true
diff --git a/versioned_docs/version-3.x/service/client-sdk/tanstack-query/_fine-grained-optimistic.md b/versioned_docs/version-3.x/service/client-sdk/tanstack-query/_fine-grained-optimistic.md
@@ -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`.
diff --git a/versioned_docs/version-3.x/service/client-sdk/tanstack-query/_invalidation.md b/versioned_docs/version-3.x/service/client-sdk/tanstack-query/_invalidation.md
@@ -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.
diff --git a/versioned_docs/version-3.x/service/client-sdk/tanstack-query/_optimistic-behavior.md b/versioned_docs/version-3.x/service/client-sdk/tanstack-query/_optimistic-behavior.md
@@ -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.
diff --git a/versioned_docs/version-3.x/service/client-sdk/tanstack-query/_optimistic-limitation.md b/versioned_docs/version-3.x/service/client-sdk/tanstack-query/_optimistic-limitation.md
@@ -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.
diff --git a/versioned_docs/version-3.x/service/client-sdk/tanstack-query/index.md b/versioned_docs/version-3.x/service/client-sdk/tanstack-query/index.md

Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`		`- // This file is not used in compilation. It is here just for a nice editor experience.`
`3`		`- "extends": "@tsconfig/docusaurus/tsconfig.json",`
`4`		`- "compilerOptions": {`
`5`		`- "baseUrl": "."`
`6`		`- }`
	`2`	`+ // This file is not used in compilation. It is here just for a nice editor experience.`
	`3`	`+ "extends": "@tsconfig/docusaurus/tsconfig.json",`
	`4`	`+ "compilerOptions": {`
	`5`	`+ "baseUrl": "."`
	`6`	`+ }`
`7`	`7`	`}`