update

Author: ymc9

code-repos/zenstackhq/v3-doc-orm-policy

@@ -4,7 +4,7 @@ import GithubCodeBlock from './GithubCodeBlock';
 
 interface StackBlitzGithubProps {
     repoPath: string;
-    openFile?: string;
+    openFile?: string | string[];
     codeFiles?: string[];
     startScript?: string;
 }
@@ -15,14 +15,16 @@ const StackBlitzGithub: React.FC<StackBlitzGithubProps> = ({
     codeFiles: plainCodeFiles = undefined,
     startScript,
 }) => {
+    const openFiles = Array.isArray(openFile) ? openFile : openFile ? openFile.split(',') : [];
+
     const options = {
-        openFile,
+        openFile: openFiles ? openFiles.join(',') : undefined,
         view: 'editor',
         startScript,
     } as const;
 
     if (!plainCodeFiles) {
-        plainCodeFiles = [openFile];
+        plainCodeFiles = [...openFiles];
     }
 
     return (

src/components/StackBlitzGithub.tsx

@@ -15,13 +15,13 @@ Input validation is a ZModel feature and doesn't exist in Prisma.
 Input validation is only applied to the ORM APIs like `create`, `update`, etc. It's not enforced at the query builder level.
 :::
 
-When defining a model field in ZModel, you specify its type, which provides a basic level of runtime validation - when an incompatible value is passed to such field during creation or update, the underlying database will reject the operation.
+When defining a model field in ZModel, you specify its type, which provides a basic level of runtime validation - when an incompatible value is passed to the field during creation or update, the ORM engine will reject the operation.
 
-However, oftentimes you want to expression more fine-grained validation rules, such as field length, string format, or numeric range, etc. ZModel provides a set of built-in field-level validation attributes, like `@length`, `@email`, etc. for this purpose. See [Input Validation](../reference/zmodel/input-validation.md) for more details.
+However, oftentimes you want to express more fine-grained validation rules, such as field length, string format, or numeric range, etc. ZModel provides a set of built-in field-level validation attributes, like `@length`, `@email`, etc., for this purpose. See [Input Validation](../reference/zmodel/input-validation.md) for more details.
 
-To support more complex rules, a powerful `@@validate` model-level attribute is provided to allow expression rules using multiple fields and logical operators. Inside the `@@validate` attribute, functions like `length()`, `isEmail()` etc. are available for building up expressions. See [Input Validation](../reference/zmodel/input-validation.md) for the full list of available functions.
+To support more complex rules, a powerful `@@validate` model-level attribute is provided to allow expression rules using multiple fields and logical operators. Inside the `@@validate` attribute, functions like `length()`, `isEmail()`, etc. are available for building up expressions. See [Input Validation](../reference/zmodel/input-validation.md) for the complete list of available functions.
 
-Arguments of mutation operations are validated before sending to the database. When a validation rule is violated, a `InputValidationError` exception is thrown, containing details about the violations.
+Arguments of mutation operations are validated before sending them to the database. When a validation rule is violated, an `InputValidationError` exception is thrown, containing details about the violations.
 
 Internally, ZenStack uses [Zod](https://zod.dev/) to perform validation. Most of the attributes and functions are 1:1 mapped to Zod APIs.
 

versioned_docs/version-3.x/orm/09-validation.md

@@ -18,9 +18,9 @@ plugin policy {
 
 ## Rule Types
 
-Policies can be defined as whitelist rule using the `@@allow` attribute or blacklist rule using `@@deny`.
+Policies can be defined as whitelist rules using the `@@allow` attribute or blacklist rules using `@@deny`.
 
-Here's a quick example. Don't worry about the details yet. We'll cover the CRUD operations and rule expressions in details later.
+Here's a quick example. Don't worry about the details yet. We'll cover the CRUD operations and rule expressions later.
 
 ```zmodel
 model User {
@@ -55,8 +55,8 @@ model Post {
 You can write as many policy rules as you want for a model. The order of the rules doesn't matter. ZenStack determines whether a CRUD operation is allowed using the following logic:
 
 1. If any `@@deny` rule evaluates to true, it's denied.
-1. If any `@@allow` rule evaluates to true, it's allowed.
-1. Otherwise, it's denied (secure by default).
+2. If any `@@allow` rule evaluates to true, it's allowed.
+3. Otherwise, it's denied (secure by default).
 
 ## Operation Types
 
@@ -76,7 +76,7 @@ Policy rules are expressed in terms of what CRUD operations they govern.
 
 - `post-update`
 
-    A special operation type to expression conditions that should hold **after** an entity is updated. See [Post-Update Policies](./post-update.md) for details.
+    A special operation type to express conditions that should hold **after** an entity is updated. See [Post-Update Policies](./post-update.md) for details.
 
 - `delete`
 
@@ -95,16 +95,18 @@ ZModel supports an intuitive expression language that's very similar to JavaScri
 - Literals like strings, numbers, and booleans
 - Comparisons with `==`, `>`, etc.
 - Logical combinations with `&&`, `||`, etc.
-- References to current model's fields like `published`
+- References to the current model's fields, like `published`
 
-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.
+They provide the basic building blocks for composing complex policy rules.
+
+Functions are an 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. 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
 
-The most common type of access control rules are those that concern the current user. The built-in `auth()` function is designed to access the current user. `auth()` returns an object, and its type is inferred from the ZModel schema with the following rules:
+The most common type of access control rules concerns the current user. The built-in `auth()` function is designed to access the current user. `auth()` returns an object, and its type is inferred from the ZModel schema with the following rules:
 
 1. If there's a `model` or `type` annotated with the `@@auth` attribute, it'll be used as the type of `auth()`.
 2. Otherwise, if there's a `model` or `type` named "User" (case sensitive), it'll be used.
@@ -134,25 +136,25 @@ model Post {
 
 So the big question becomes: Where does the value of `auth()` come from?
 
-ZenStack isn't an authentication framework, so it doesn't know how to fetch the current login user. You are responsible for providing that piece of information. We'll cover it in the next part where we talk about access control's runtime aspect. For now, just assume `auth()` gives you the **validated** current user info.
+ZenStack isn't an authentication library, so it doesn't know how to fetch the current login user. You are responsible for providing that piece of information. We'll cover it in the next part, where we talk about the runtime aspect of access control. For now, assume `auth()` gives you the **validated** current user info.
 
-If you don't provide the current user, `auth()` will return `null`, and you can use it to write rules for anonymous users like:
+If you don't provide the current user, `auth()` will return `null`, and you can use it to write rules for anonymous users, like:
 
 ```zmodel
 @@deny('all', auth() == null)
 ```
 
 ## Accessing Relations
 
-You can achieve a lot by writing policies using model's simple fields, however, real-world access control often involves relations. For example:
+You can achieve a lot by writing policies using a model's simple fields; however, real-world access control often involves relations. For example:
 
 > A user can only create posts if his profile is verified, where "Profile" is a relation of "User".
 
 ZenStack's policy really shines when it comes to how flexible it is in traversing relations.
 
 ### To-One Relations
 
-Accessing to-one relation is straightforward, simply use dot notation use relation's field, and you can chain as deeply as you need:
+Accessing to-one relation is straightforward, simply use dot notation to use the relation's field, and you can chain as deeply as you need:
 
 ```zmodel
 model User {
@@ -204,9 +206,9 @@ You can nest collection predicate expressions to build deep to-many relation tra
 
 ## Special Notes About `create`
 
-There're limitations with what relations can be accessed in `create` rules, because such rules are evaluated before the record is created, and at that time, relations are not accessible yet.
+There are limitations on what relations can be accessed in `create` rules, because such rules are evaluated before the record is created. At that time, relations are not accessible yet.
 
-As a result, `create` rules can only access "owned" relations - those relations that have foreign keys defined in the model where the rule is defined. For example, the following is allowed:
+As a result, `create` rules can only access "owned" relations - those relations that have foreign keys defined in the model where the rule is defined. During create, if the foreign key fields are set, the relations are accessible. For example, the following is allowed:
 
 ```zmodel
 model Profile {
@@ -250,7 +252,7 @@ model Profile {
 }
 ```
 
-You can use the `check()` function to directly delegate the policy check to the related entity:
+You can use the `check()` function to delegate the policy check to the related entity directly:
 
 ```zmodel
 model User {
@@ -267,7 +269,7 @@ model Profile {
 }
 ```
 
-You can make it even more concise by omitting the second argument and infer it from the context:
+You can make it even more concise by omitting the second argument and inferring it from the context:
 
 ```zmodel
 model Profile {

versioned_docs/version-3.x/orm/access-control/01-write-policies.md

@@ -6,7 +6,7 @@ After defining access control policies in ZModel, it's time to enjoy their benef
 
 ## Installing Runtime Plugin
 
-Similar to the schema side, access control's runtime aspect is encapsulated in the `@zenstackhq/plugin-policy` package too, as a Runtime Plugin (more about this topic [later](../plugins/index.md)). You should install it onto the raw ORM client to get a new client instance with access control enforcement.
+Similar to the schema side, access control's runtime aspect is encapsulated in the `@zenstackhq/plugin-policy` package too, as a Runtime Plugin (more about this topic [later](../plugins/index.md)). You should install it on the raw ORM client to get a new client instance with access control enforcement.
 
 ```ts
 import { ZenStackClient } from '@zenstackhq/runtime';
@@ -26,7 +26,7 @@ const authDb = db.$use(new PolicyPlugin());
 
 As mentioned in the previous part, you can use the `auth()` function in policy rules to refer to the current authenticated user. At runtime, you should use the `$setAuth()` API to provide such information. ZenStack itself is not an authentication library, so you need to determine how to achieve it based on your authentication mechanism.
 
-In a web application, the typical pattern is to inspect the incoming request, extract the user information from it and validate, and then call `$setAuth()` to get an ORM client bound to that user.
+In a web application, the typical pattern is to inspect the incoming request, extract and validate the user information from it, and then call `$setAuth()` to get an ORM client bound to that user.
 
 ```ts
 import { getSessionUser } from './auth'; // your auth helper
@@ -49,20 +49,20 @@ Use the `$auth` property to get the user info previously set by `$setAuth()`.
 
 ## Making Queries
 
-Access control policies are effective to both the ORM API and the query-builder API. To understand its behavior, the simplest mental model is to think that rows not satisfying the policies "don't exist".
+Access control policies are effective for both the ORM API and the query-builder API. To understand its behavior, the simplest mental model is to think that rows not satisfying the policies "don't exist".
 
 ### ORM Queries
 
-For the most part, the ORM queries behavior is very intuitive.
+For the most part, the ORM query behavior is very intuitive:
 
-Read operations like `findMany`, `findUnique`, `count`, etc., only return/involve rows that meet the "read" policies.
+    - Read operations like `findMany`, `findUnique`, `count`, etc., only return/involve rows that meet the "read" policies.
 
-Mutation operations that affect multiple rows like `updateMany` and `deleteMany` only impact rows that meet the "update" or "delete" policies respectively.
+    - Mutation operations that affect multiple rows, like `updateMany` and `deleteMany`, only impact rows that meet the "update" or "delete" policies respectively.
 
-Mutation operations that affect a single, unique row like `update` and `delete` will throw an `NotFoundError` if the target row doesn't meet the "update" or "delete" policies respectively.
+    - Mutation operations that affect a single, unique row, like `update` and `delete`, will throw an `NotFoundError` if the target row doesn't meet the "update" or "delete" policies respectively.
 
 :::info
-Why `NotFoundError` instead of `RejectedByPolicyError`? Remember the rationale is rows that don't satisfy the policies "don't exist".
+Why `NotFoundError` instead of `RejectedByPolicyError`? Because the rationale is rows that don't satisfy the policies "don't exist".
 :::
 
 There are some complications when "read" and "write" policies affect the same query. It's ubiquitous because most mutation APIs involve reading the post-mutation entity to return to the caller. When the mutation succeeds but the post-mutation entity cannot be read, a `RejectedByPolicyError` is thrown, even though the mutation is persisted.
@@ -78,31 +78,31 @@ await db.post.update({
 ```
 
 :::info
-Why throwing an error instead of returning `null`? Because it'll compromise type-safety. The `create`, `update`, and `delete` APIs don't have a nullable return type.
+Why throw an error instead of returning `null`? Because it'll compromise type-safety. The `create`, `update`, and `delete` APIs don't have a nullable return type.
 :::
 
 ### Query-Builder Queries
 
-The low-level Kysely-query-builder API is also subject to access control enforcement. Its behavior is intuitive:
+The low-level Kysely query-builder API is also subject to access control enforcement. Its behavior is intuitive:
 
 - Calling `$qb.selectFrom()` returns readable rows only.
 - When you call `$qb.insertInto()`, `RejectedByPolicyError` will be thrown if the inserted row doesn't satisfy the "create" policies. Similar for `update` and `delete`.
-- Calling `$qb.update()` and `$qb.delete()` only affects rows that satisfy the "update" and "delete" policies respectively.
+- Calling `$qb.update()` and `$qb.delete()` only affects rows that satisfy the "update" and "delete" policies, respectively.
 - When you join tables, the joined table will be filtered to readable rows only.
-- When you use sub-queries, the sub-query will be filtered to readable rows only.
+- When you use sub-queries, the sub-queries will be filtered to readable rows only.
 
 ## Limitations
 
 Here are some **IMPORTANT LIMITATIONS** about access control enforcement:
 
-1. Mutations caused by cascade deletes/updates and database triggers are completely internal to the database, so ZenStack cannot enforce access control on them.
+1. Mutations caused by cascade deletes/updates and database triggers are entirely internal to the database, so ZenStack cannot enforce access control on them.
 2. Raw SQL queries executed via `$executeRaw()` and `$queryRaw()` are not subject to access control enforcement.
 3. Similarly, raw queries made with query-builder API using the `sql` tag are not subject to access control enforcement.
 
 ## Samples
 
-<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm-policy" codeFiles={['zenstack/schema.zmodel', 'main.ts']} />
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm-policy" openFile={['basic/zenstack/schema.zmodel', 'basic/main.ts']} startScript="basic" />
 
 ## 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.
+ZenStack v3's ORM is built on top of Kysely. Regardless of whether 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.

versioned_docs/version-3.x/orm/access-control/02-query.md

@@ -1,6 +1,16 @@
 # 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.
+import StackBlitzGithub from '@site/src/components/StackBlitzGithub';
+
+:::info
+
+In ZenStack v2, post-update rules were implicitly defined with the "update" operation by using the `future()` function to refer to the post-update values. We found this approach to be unclean and error-prone. V3 made a breaking change to introduce a separate "post-update" operation.
+
+:::
+
+## Overview
+
+Among the CRUD operations, "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.
 
@@ -24,3 +34,8 @@ model Post {
 }
 ```
 
+When post-update policies are violated, a `RejectedByPolicyError` is thrown.
+
+## Samples
+
+<StackBlitzGithub repoPath="zenstackhq/v3-doc-orm-policy" openFile={['post-update/zenstack/schema.zmodel', 'post-update/main.ts']} startScript="post-update" />