doc: custom procedures (#548)

* doc: custom procedures

* Fix typo: change "URL encoded" to "URL-encoded" (#549)

* Add AvailableSince component to custom procedures documentation (#550)

* Add anchor link to Custom Procedures section in TanStack Query documentation (#551)

* Update docs/service/api-handler/rest.md

Co-authored-by: Copilot <[email protected]>

* Update docs/service/api-handler/rest.md

Co-authored-by: Copilot <[email protected]>

* Update docs/modeling/custom-proc.md

Co-authored-by: Copilot <[email protected]>

* Update docs/orm/custom-proc.md

Co-authored-by: Copilot <[email protected]>

---------

Co-authored-by: Copilot <[email protected]>
Co-authored-by: Copilot <[email protected]>

Author: 3 people

docs/modeling/custom-proc.md

@@ -0,0 +1,46 @@
+---
+sidebar_position: 12
+description: ZenStack custom procedures
+---
+
+import ZModelVsPSL from '../_components/ZModelVsPSL';
+import PreviewFeature from '../_components/PreviewFeature';
+import AvailableSince from '../_components/AvailableSince';
+
+# Custom Procedure
+
+<PreviewFeature name="Custom procedure" />
+
+<AvailableSince version="v3.2.0" />
+
+<ZModelVsPSL>
+Custom procedure is a ZModel feature and doesn't exist in PSL.
+</ZModelVsPSL>
+
+Custom procedures are like database stored procedures that allow you to define reusable routines encapsulating complex logic.
+
+Use the `procedure` keyword to define a custom procedure in ZModel. Here's an example for a query procedure:
+
+```zmodel title="schema.zmodel"
+procedure getUserFeeds(userId: Int, limit: Int?) : Post[] 
+```
+
+Mutation procedures (that write to the database) should be defined with `mutation procedure`:
+
+```zmodel title="schema.zmodel"
+mutation procedure signUp(email: String) : User
+```
+
+You can use all types supported by ZModel to define procedure parameters and return types, including:
+
+  - Primitive types like `Int`, `String`
+  - Models
+  - Enums
+  - Custom types
+  - Array of the types above
+
+Parameter types can be marked optional with a `?` suffix. If a procedure doesn't return anything, use `Void` as the return type.
+
+Custom procedures are implemented with TypeScript when constructing the ORM client, and can be invoked via the ORM client in backend code. See [Custom Procedures](../orm/custom-proc.md) in the ORM part for more details.
+
+They are also accessible via Query-as-a-Service (via [RPC-style](../service/api-handler/rpc.md#endpoints) or [RESTful-style](../service/api-handler/rest.md#calling-custom-procedures) API), plus consumable via Client SDKs like [TanStack Query Client](../service/client-sdk/tanstack-query/#custom-procedures).

docs/modeling/plugin.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 12
+sidebar_position: 13
 description: ZenStack plugins
 ---
 

docs/orm/custom-proc.md

@@ -0,0 +1,95 @@
+---
+sidebar_position: 13
+description: ORM custom procedures
+---
+
+import PreviewFeature from '../_components/PreviewFeature';
+import AvailableSince from '../_components/AvailableSince';
+
+# Custom Procedures
+
+<PreviewFeature name="Custom procedure" />
+
+<AvailableSince version="v3.2.0" />
+
+:::info
+Please refer to the [Modeling](../modeling/custom-proc.md) part for how to define custom procedures in ZModel.
+:::
+
+The ORM's CRUD API is very flexible and powerful, but in real-world applications you'll often find the need to encapsulate complex logic into more high-level and reusable operations. For example, in a collaborative app, after creating new users, you may want to automatically create a default workspace for them and assign some initial roles.
+
+A conventional approach is to implement a `signUp` API route that orchestrates these steps. However, since the operation is still very much database-centric, it's more natural to have the encapsulation at the ORM level. This is where custom procedures come in. They are type-safe procedures defined in ZModel and implemented with TypeScript, and can be invoked via the ORM client just like the built-in CRUD methods.
+
+## Implementing custom procedures
+
+Suppose you have the following custom procedures defined in ZModel:
+
+```zmodel title="schema.zmodel"
+// get blog post feeds for a given user
+procedure getUserFeeds(userId: Int, limit: Int?) : Post[] 
+
+// sign up a new user
+mutation procedure signUp(email: String) : User
+```
+
+:::info
+Query procedures and mutation procedures currently don't have any semantic differences at the ORM level. However, in the future they may behave differently, for example, when features like cached queries are introduced.
+:::
+
+When you construct a `ZenStackClient`, you must provide an implementation for each procedure:
+
+```ts title="db.ts"
+const db = new ZenStackClient({
+  ...
+  procedures: {
+    getUserFeeds: ({ client, args }) => {
+      return client.post.findMany({
+        where: { authorId: args.userId },
+        orderBy: { createdAt: 'desc' },
+        take: args.limit,
+      });
+    },
+
+    signUp: ({ client, args }) => {
+      return client.user.create({
+        data: {
+          email: args.email,
+          memberships: {
+            create: {
+              role: 'OWNER',
+              workspace: {
+                create: { name: 'Default Workspace' },
+              },
+            },
+          }
+        }
+      });
+    },
+  },
+});
+```
+
+The implementation callbacks are provided with a context argument with the following fields:
+
+  - `client`: an instance of `ZenStackClient` used to invoke the procedure.
+  - `args`: an object that contains the procedure arguments.
+
+At runtime, before passing the args to the callbacks, ZenStack verifies that they conform to the types defined in ZModel. You can implement additional validations in the implementation if needed. ZenStack doesn't verify the return values. It's your responsibility to ensure they match the declared return types.
+
+## Calling custom procedures
+
+The custom procedures methods are grouped under the `$procs` property of the client instance. You must provide arguments as an object under the `args` key:
+
+```ts
+const user = await db.$procs.signUp({
+  args: { email: '[email protected]' } 
+});
+
+const feeds = await db.$procs.getUserFeeds({
+  args: { userId: user.id, limit: 20 } 
+});
+```
+
+## Error handling
+
+The `ZenStackClient` always throws an `ORMError` to the caller when an error occurs. To follow this protocol, custom procedure implementations should ensure other types of errors are caught and wrapped into `ORMError` and re-thrown. See [Error Handling](./errors.md) for more details.

docs/orm/logging.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 14
+sidebar_position: 15
 description: Setup logging
 ---
 

docs/orm/plugins/_category_.yml

@@ -1,4 +1,4 @@
-position: 13
+position: 14
 label: Plugins
 collapsible: true
 collapsed: true

docs/recipe/plugin-dev.md

@@ -1,5 +1,5 @@
 ---
-sidebar_position: 5
+sidebar_position: 6
 description: Plugin development guide
 ---
 

docs/service/api-handler/rest.md

@@ -50,7 +50,7 @@ The factory function accepts an options object with the following fields:
 
 - externalIdMapping
 
-  Optional. An `Record<string, string>` value that provides a mapping from model names (as defined in ZModel) to unique constraint name. This is useful when you for example want to expose natural keys in place of a surrogate keys:
+  Optional. An `Record<string, string>` value that provides a mapping from model names (as defined in ZModel) to the model's unique field name. This is useful when you for example want to expose natural keys in place of a surrogate keys:
 
   ```ts
   // Expose tags by unique name and not by ID, ie. /tag/blue intead of /tag/id
@@ -98,6 +98,10 @@ model Comment {
     post Post @relation(fields: [postId], references: [id])
     postId Int
 }
+
+procedure getUserFeeds(userId: Int, limit: Int?) : Post[] 
+
+mutation procedure signUp(email: String) : User
 ```
 
 ### Listing resources
@@ -835,6 +839,47 @@ PATCH /:type/:id/relationships/:relationship
     }
     ```
 
+### Calling custom procedures
+
+Custom procedures can be invoked with the special `$procs` resource type.
+
+Use `GET` for query procedures and pass the arguments as a URL-encoded object in the `args` query parameter:
+
+```ts
+GET /$procs/:procName?args=<encoded arguments>
+```
+
+Use `POST` for mutation procedures and pass the arguments in the request body:
+
+```ts
+POST /$procs/:procName
+{
+    "args": { ... }
+}
+```
+
+#### Status codes
+
+- 200: The request was successful and the response body contains the custom procedure's return value.
+- 400: Invalid custom procedure name or arguments.
+- 500: An error occurred while executing the custom procedure.
+
+#### Examples
+
+```ts
+// for arguments `{"userId":1,"limit":10}`
+GET /$procs/getUserFeeds?args=%7B%22userId%22%3A1%2C%22limit%22%3A10%7D
+```
+
+```ts
+POST /$procs/signUp
+{
+    "args": {
+        "email": "[email protected]"
+    }
+}
+```
+
 ## Compound ID Fields
 
 ZModel allows a model to have compound ID fields, e.g.:

docs/service/api-handler/rpc.md

@@ -181,10 +181,18 @@ The following part explains how the `meta` information is included for different
 
     _Http method:_ `DELETE`
 
--   **[model]/check**
+-   **[$procs]/[custom-procedure-name]**
+
+    Invoking a query custom procedure. E.g., `/$procs/getUserFeeds?q=<encoded args>`.
 
     _Http method:_ `GET`
 
+-   **[$procs]/[mutation-custom-procedure-name]**
+
+    Invoking a mutation custom procedure. E.g., `/$procs/signUp`.
+
+    _Http method:_ `POST`
+
 ## HTTP Status Code and Error Responses
 
 ### Status code

docs/service/client-sdk/tanstack-query/index.md

@@ -521,6 +521,12 @@ Here's a quick example of using infinite query to load a list of posts with infi
 
 </Tabs>
 
+## Custom Procedures
+
+[Custom procedures](../../../modeling/custom-proc.md) are grouped under the `$procs` property on the client returned by `useClientQueries`. Query procedures are mapped to query hooks, while mutation procedures are mapped to mutation hooks.
+
+There's no automatic query invalidation or optimistic update support for custom procedures, since their semantics are unknown to the system. You need to implement such behavior manually as needed.
+
 ## Advanced Topics
 
 ### Query Invalidation