update

ymc9 · ymc9 · commit 6da83851a052 · 2025-10-18T20:07:01.000-04:00
diff --git a/versioned_docs/version-3.x/orm/01-quick-start.md b/versioned_docs/version-3.x/orm/01-quick-start.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 1
 description: Quick start guide
 ---
 
diff --git a/versioned_docs/version-3.x/orm/02-cli.md b/versioned_docs/version-3.x/orm/02-cli.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 2
 description: Using the CLI
 ---
 
diff --git a/versioned_docs/version-3.x/orm/03-client.md b/versioned_docs/version-3.x/orm/03-client.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 3
 description: Creating a database client
 ---
 
diff --git a/versioned_docs/version-3.x/orm/05-query-builder.md b/versioned_docs/version-3.x/orm/05-query-builder.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 5
 description: Query builder API
 ---
 
diff --git a/versioned_docs/version-3.x/orm/09-validation.md b/versioned_docs/version-3.x/orm/09-validation.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 9
 description: Input validation in ZModel
 ---
 
diff --git a/versioned_docs/version-3.x/orm/10-computed-fields.md b/versioned_docs/version-3.x/orm/10-computed-fields.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 10
 description: Computed fields in ZModel
 ---
 
diff --git a/versioned_docs/version-3.x/orm/11-polymorphism.md b/versioned_docs/version-3.x/orm/11-polymorphism.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 11
 description: Polymorphic models
 ---
 
diff --git a/versioned_docs/version-3.x/orm/12-typed-json.md b/versioned_docs/version-3.x/orm/12-typed-json.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 12
 description: Strongly typed JSON fields
 ---
 
diff --git a/versioned_docs/version-3.x/orm/14-logging.md b/versioned_docs/version-3.x/orm/14-logging.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 14
 description: Setup logging
 ---
 
diff --git a/versioned_docs/version-3.x/orm/15-inferred-types.md b/versioned_docs/version-3.x/orm/15-inferred-types.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 15
 description: TypeScript types derived from the ZModel schema
 ---
 
diff --git a/versioned_docs/version-3.x/orm/16-errors.md b/versioned_docs/version-3.x/orm/16-errors.md
@@ -1,20 +1,25 @@
 ---
-sidebar_position: 16
 description: ORM Errors
 ---
 
 # Errors
 
 The ORM uses the following error classes from `@zenstackhq/runtime` to represent different types of failures:
 
-## `ValidationError`
+## `InputValidationError`
 
 This error is thrown when the argument passed to the ORM methods is invalid, e.g., missing required fields, or containing unknown fields. The `cause` property is set to the original error thrown during validation.
 
+If [input validation](../orm/Validation.md) is used, this error is also thrown when the validation rules are violated.
+
 ## `NotFoundError`
 
 This error is thrown when a requested record is not found in the database, e.g., when calling `findUniqueOrThrow`, `update`, etc.
 
 ## `QueryError`
 
 This error is used to encapsulate all other errors thrown from the underlying database driver. The `cause` property is set to the original error thrown.
+
+## `RejectedByPolicyError`
+
+This error is thrown when an operation is rejected by [access control policies](../orm/access-control/index.md).
diff --git a/versioned_docs/version-3.x/orm/17-migration.md b/versioned_docs/version-3.x/orm/17-migration.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 17
+description: Database schema migrations
 ---
 
 # Database Migration
diff --git a/versioned_docs/version-3.x/orm/access-control/01-write-policies.md b/versioned_docs/version-3.x/orm/access-control/01-write-policies.md
@@ -99,7 +99,7 @@ ZModel supports an intuitive expression language that's very similar to JavaScri
 
 They provide the basic building blocks for composing complex policy rules. Functions are a extensibility mechanism that allows encapsulating specific semantics (e.g., getting the current user). Function calls are expressions so they can be combined with other expressions using operators.
 
-The following sections will cover some of the functions and expression types that are specifically designed for writing policy rules. Refer to [Functions](../../reference/zmodel/07-function.md) and [Expression](../../reference/zmodel/08-expression.md) reference for more details.
+The following sections will cover some of the functions and expression types that are specifically designed for writing policy rules. See [Functions](../../reference/zmodel/07-function.md) and [Expression](../../reference/zmodel/08-expression.md) reference for more details. Refer to the [@zenstackhq/plugin-policy](../../reference/plugins/policy.md) documentation for functions available for writing policies.
 
 
 ## Accessing Current User
diff --git a/versioned_docs/version-3.x/orm/access-control/02-query.md b/versioned_docs/version-3.x/orm/access-control/02-query.md
@@ -105,3 +105,4 @@ Here are some **IMPORTANT LIMITATIONS** about access control enforcement:
 
 ## Implementation Notes
 
+ZenStack v3's ORM is built above Kysely. Regardless you use the ORM API or the query-builder one, queries are eventually transformed into Kysely's SQL AST, and then compiled down to SQL and sent to the database for execution. The access control enforcement is implemented by transforming the AST and injecting proper filters.
diff --git a/versioned_docs/version-3.x/orm/access-control/03-post-update.md b/versioned_docs/version-3.x/orm/access-control/03-post-update.md
@@ -1 +1,26 @@
 # Post-Update Rules
+
+Among the operation types, "update" is a special one because it has a "pre" state and "post" state. The "update" policies we've seen in the previous parts refer to the "pre" state, meaning that if your polices refer to the model's fields, the fields are evaluated to their values before the update happens.
+
+However, sometimes you want to express conditions that should hold after the update happens. For example, you may want to ensure that after an update, a post's `published` field cannot be set to true unless the current user is the author. Post-update policies are designed for such scenarios.
+
+Writing post-update rules is essentially the same as writing regular "update" rules, except that fields will refer to their post-update values. You can use the built-in `before()` function to refer to the pre-update entity if needed.
+
+Another key difference is that "post-update" operation is by default allowed. If you don't write any post-update rules, the update operation will succeed as long as it passes the "update" policies. However, if you have any post-update rules for a model, at least one `@@allow` rule must evaluate to true for the update operation to succeed.
+
+```zmodel
+model Post {
+    id        Int @id @default(autoincrement())
+    title     String
+    published Boolean @default(false)
+    author    User @relation(fields: [authorId], references: [id])
+    authorId  Int
+
+    // only author can publish the post
+    @@deny('post-update', published == true && auth().id != authorId)
+
+    // prevent changing authorId
+    @@deny('post-update', before().authorId != authorId)
+}
+```
+
diff --git a/versioned_docs/version-3.x/orm/index.md b/versioned_docs/version-3.x/orm/index.md
@@ -1,5 +1,4 @@
 ---
-sidebar_position: 1
 description: ZenStack ORM overview
 ---
 
diff --git a/versioned_docs/version-3.x/reference/plugins/policy.md b/versioned_docs/version-3.x/reference/plugins/policy.md
@@ -3,3 +3,132 @@ sidebar_position: 3
 ---
 
 # @zenstackhq/plugin-policy
+
+The `@zenstackhq/plugin-policy` plugin provides a set of ZModel declarations and a ORM runtime plugin to enable access control features. See [Access Control](../../orm/access-control/index.md) for more details.
+
+## ZModel Declarations
+
+The plugin contributes a set of ZModel attributes and functions for defining access control policies. To use them, you need to add the plugin declaration in your ZModel schema:
+
+```zmodel
+plugin policy {
+    provider = '@zenstackhq/plugin-policy'
+}
+```
+
+### Attributes
+
+Use the following model-level attributes to define access control policies:
+
+- `@@allow`
+
+    ```zmodel
+    attribute @@allow(_ operation: String, _ condition: Boolean)
+    ```
+
+    Defines an access policy that allows a set of operations when the given condition is true.
+     - `operation`: comma-separated list of "create", "read", "update", "post-update", "delete". Use "all" to denote all operations.
+     - `condition`: a boolean expression that controls if the operation should be allowed.
+  
+- `@@deny`
+  
+    ```zmodel
+    attribute @@deny(_ operation: String, _ condition: Boolean)
+    ```
+
+    Defines an access policy that denies a set of operations when the given condition is true.
+     - `operation`: comma-separated list of "create", "read", "update", "post-update", "delete". Use "all" to denote all operations.
+     - `condition`: a boolean expression that controls if the operation should be denied.
+
+### Functions
+
+The following functions can be used in policy conditions:
+
+- `auth()`
+
+    ```zmodel
+    function auth(): User {}
+    ```
+
+    Gets the current login user. The return type of the function is the `User` model defined in the current ZModel.
+
+- `now()`
+
+    ```zmodel
+    function now(): DateTime {}
+    ```
+
+    Gets the current datetime.
+
+- `contains()`
+
+    ```zmodel
+    function contains(field: String, search: String, caseInSensitive: Boolean?): Boolean {
+    }
+    ```
+
+    Checks if the field value contains the search string. By default, the search is case-sensitive, and "LIKE" operator is used to match. If `caseInSensitive` is true, "ILIKE" operator is used if supported, otherwise it still falls back to "LIKE" and delivers whatever the database's behavior is.
+
+- `startsWith()`
+
+    ```zmodel
+    function startsWith(field: String, search: String, caseInSensitive: Boolean?): Boolean {
+    }
+    ```
+
+    Checks the field value starts with the search string. By default, the search is case-sensitive, and "LIKE" operator is used to match. If `caseInSensitive` is true, "ILIKE" operator is used if supported, otherwise it still falls back to "LIKE" and delivers whatever the database's behavior is.
+
+- `endsWith()`
+
+    ```zmodel
+    function endsWith(field: String, search: String, caseInSensitive: Boolean?): Boolean {
+    }
+    ```
+
+    Checks the field value ends with the search string. By default, the search is case-sensitive, and "LIKE" operator is used to match. If `caseInSensitive` is true, "ILIKE" operator is used if supported, otherwise it still falls back to "LIKE" and delivers whatever the database's behavior is.
+
+- `has()`
+
+    ```zmodel
+    function has(field: Any[], search: Any): Boolean {}
+    ```
+
+    Checks if the list field value has the given search value.
+
+- `hasSome()`
+
+    ```zmodel
+    function hasSome(field: Any[], search: Any[]): Boolean {
+    }
+    ```
+
+    Checks if the list field value has at least one element of the search list
+
+- `hasEvery()`
+
+    ```zmodel
+    function hasEvery(field: Any[], search: Any[]): Boolean {}
+    ```
+
+    Checks if the list field value has all elements of the search list.
+
+
+- `isEmpty()`
+
+    ```zmodel
+    function isEmpty(field: Any[]): Boolean {}
+    ```
+
+    Checks if the list field value is empty.
+
+## Runtime Plugin
+
+The plugin exports a runtime plugin `PolicyPlugin` that can be installed to the ORM client to enable access control enforcement.
+
+```ts
+import { ZenStackClient } from '@zenstackhq/runtime';
+import { PolicyPlugin } from '@zenstackhq/plugin-policy';
+
+const db = new ZenStackClient(...);
+const authDb = db.$use(new PolicyPlugin());
+```
diff --git a/versioned_docs/version-3.x/reference/zmodel/10-input-validation.md b/versioned_docs/version-3.x/reference/zmodel/10-input-validation.md

Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-sidebar_position: 1`
`3`	`2`	`description: Quick start guide`
`4`	`3`	`---`
`5`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-sidebar_position: 2`
`3`	`2`	`description: Using the CLI`
`4`	`3`	`---`
`5`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-sidebar_position: 3`
`3`	`2`	`description: Creating a database client`
`4`	`3`	`---`
`5`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-sidebar_position: 5`
`3`	`2`	`description: Query builder API`
`4`	`3`	`---`
`5`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-sidebar_position: 9`
`3`	`2`	`description: Input validation in ZModel`
`4`	`3`	`---`
`5`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-sidebar_position: 10`
`3`	`2`	`description: Computed fields in ZModel`
`4`	`3`	`---`
`5`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-sidebar_position: 11`
`3`	`2`	`description: Polymorphic models`
`4`	`3`	`---`
`5`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-sidebar_position: 12`
`3`	`2`	`description: Strongly typed JSON fields`
`4`	`3`	`---`
`5`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-sidebar_position: 14`
`3`	`2`	`description: Setup logging`
`4`	`3`	`---`
`5`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,4 @@`
`1`	`1`	`---`
`2`		`-sidebar_position: 15`
`3`	`2`	`description: TypeScript types derived from the ZModel schema`
`4`	`3`	`---`
`5`	`4`