merge dev to main (v3.5.2) (#2527)

ymc9 · web-flow · commit 554f82f2ef75 · 2026-03-28T22:32:41.000-07:00
diff --git a/package.json b/package.json
@@ -1,6 +1,6 @@
 {
     "name": "zenstack-v3",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "description": "ZenStack",
     "packageManager": "pnpm@10.23.0",
     "type": "module",
diff --git a/packages/auth-adapters/better-auth/package.json b/packages/auth-adapters/better-auth/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/better-auth",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "description": "ZenStack Better Auth Adapter. This adapter is modified from better-auth's Prisma adapter.",
     "type": "module",
     "scripts": {
diff --git a/packages/cli/package.json b/packages/cli/package.json
@@ -3,7 +3,7 @@
     "publisher": "zenstack",
     "displayName": "ZenStack CLI",
     "description": "FullStack database toolkit with built-in access control and automatic API generation.",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "type": "module",
     "author": {
         "name": "ZenStack Team"
diff --git a/packages/clients/client-helpers/package.json b/packages/clients/client-helpers/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/client-helpers",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "description": "Helpers for implementing clients that consume ZenStack's CRUD service",
     "type": "module",
     "scripts": {
diff --git a/packages/clients/tanstack-query/package.json b/packages/clients/tanstack-query/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/tanstack-query",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "description": "TanStack Query Client for consuming ZenStack v3's CRUD service",
     "type": "module",
     "scripts": {
diff --git a/packages/common-helpers/package.json b/packages/common-helpers/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/common-helpers",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "description": "ZenStack Common Helpers",
     "type": "module",
     "scripts": {
diff --git a/packages/config/eslint-config/package.json b/packages/config/eslint-config/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/eslint-config",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "type": "module",
     "private": true,
     "license": "MIT"
diff --git a/packages/config/typescript-config/package.json b/packages/config/typescript-config/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/typescript-config",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "private": true,
     "license": "MIT"
 }
diff --git a/packages/config/vitest-config/package.json b/packages/config/vitest-config/package.json
@@ -1,7 +1,7 @@
 {
     "name": "@zenstackhq/vitest-config",
     "type": "module",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "private": true,
     "license": "MIT",
     "exports": {
diff --git a/packages/create-zenstack/package.json b/packages/create-zenstack/package.json
@@ -1,6 +1,6 @@
 {
     "name": "create-zenstack",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "description": "Create a new ZenStack project",
     "type": "module",
     "scripts": {
diff --git a/packages/language/package.json b/packages/language/package.json
@@ -1,7 +1,7 @@
 {
     "name": "@zenstackhq/language",
     "description": "ZenStack ZModel language specification",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "license": "MIT",
     "author": "ZenStack Team",
     "files": [
diff --git a/packages/language/src/document.ts b/packages/language/src/document.ts
@@ -33,9 +33,10 @@ export async function loadDocument(
     fileName: string,
     additionalModelFiles: string[] = [],
     mergeImports: boolean = true,
+    returnPartialModelForError: boolean = false,
 ): Promise<
     | { success: true; model: Model; warnings: string[]; services: ZModelServices }
-    | { success: false; errors: string[]; warnings: string[] }
+    | { success: false; model?: Model; errors: string[]; warnings: string[] }
 > {
     const { ZModelLanguage: services } = createZModelServices(false);
     const extensions = services.LanguageMetaData.fileExtensions;
@@ -116,6 +117,7 @@ export async function loadDocument(
     if (errors.length > 0) {
         return {
             success: false,
+            model: returnPartialModelForError ? (document.parseResult.value as Model) : undefined,
             errors,
             warnings,
         };
@@ -139,6 +141,7 @@ export async function loadDocument(
     if (additionalErrors.length > 0) {
         return {
             success: false,
+            model: returnPartialModelForError ? (document.parseResult.value as Model) : undefined,
             errors: additionalErrors,
             warnings,
         };
diff --git a/packages/orm/package.json b/packages/orm/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/orm",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "description": "ZenStack ORM",
     "type": "module",
     "scripts": {
diff --git a/packages/orm/src/client/crud/dialects/lateral-join-dialect-base.ts b/packages/orm/src/client/crud/dialects/lateral-join-dialect-base.ts
@@ -2,9 +2,10 @@ import { invariant } from '@zenstackhq/common-helpers';
 import { type AliasableExpression, type Expression, type ExpressionBuilder, type SelectQueryBuilder } from 'kysely';
 import type { FieldDef, GetModels, SchemaDef } from '../../../schema';
 import { DELEGATE_JOINED_FIELD_PREFIX } from '../../constants';
-import type { FindArgs } from '../../crud-types';
+import type { FindArgs, NullsOrder, SortOrder } from '../../crud-types';
 import {
     buildJoinPairs,
+    ensureArray,
     getDelegateDescendantModels,
     getManyToManyRelation,
     isRelationField,
@@ -23,7 +24,10 @@ export abstract class LateralJoinDialectBase<Schema extends SchemaDef> extends B
     /**
      * Builds an array aggregation expression.
      */
-    protected abstract buildArrayAgg(arg: Expression<any>): AliasableExpression<any>;
+    protected abstract buildArrayAgg(
+        arg: Expression<any>,
+        orderBy?: { expr: Expression<any>; sort: SortOrder; nulls?: NullsOrder }[],
+    ): AliasableExpression<any>;
 
     override buildRelationSelection(
         query: SelectQueryBuilder<any, any, any>,
@@ -172,7 +176,8 @@ export abstract class LateralJoinDialectBase<Schema extends SchemaDef> extends B
             );
 
             if (relationFieldDef.array) {
-                return this.buildArrayAgg(this.buildJsonObject(objArgs)).as('$data');
+                const orderBy = this.buildRelationOrderByExpressions(relationModel, relationModelAlias, payload);
+                return this.buildArrayAgg(this.buildJsonObject(objArgs), orderBy).as('$data');
             } else {
                 return this.buildJsonObject(objArgs).as('$data');
             }
@@ -181,6 +186,50 @@ export abstract class LateralJoinDialectBase<Schema extends SchemaDef> extends B
         return qb;
     }
 
+    /**
+     * Extracts scalar `orderBy` clauses from the relation payload and maps them to
+     * the array-aggregation ordering format.
+     *
+     * For to-many relations aggregated into a JSON array (via lateral joins), this
+     * lets us preserve a stable ordering by passing `{ expr, sort, nulls? }` into
+     * the dialect's `buildArrayAgg` implementation.
+     */
+    private buildRelationOrderByExpressions(
+        model: string,
+        modelAlias: string,
+        payload: true | FindArgs<Schema, GetModels<Schema>, any, true>,
+    ): { expr: Expression<any>; sort: SortOrder; nulls?: NullsOrder }[] | undefined {
+        if (payload === true || !payload.orderBy) {
+            return undefined;
+        }
+
+        type ScalarSortValue = SortOrder | { sort: SortOrder; nulls?: NullsOrder };
+        const items: { expr: Expression<any>; sort: SortOrder; nulls?: NullsOrder }[] = [];
+
+        for (const orderBy of ensureArray(payload.orderBy)) {
+            for (const [field, value] of Object.entries(orderBy) as [string, ScalarSortValue | undefined][]) {
+                if (!value || requireField(this.schema, model, field).relation) {
+                    continue;
+                }
+
+                const expr = this.fieldRef(model, field, modelAlias);
+                let sort = typeof value === 'string' ? value : value.sort;
+                if (payload.take !== undefined && payload.take < 0) {
+                    // negative `take` requires negated sorting, and the result order
+                    // will be corrected during post-read processing
+                    sort = this.negateSort(sort, true);
+                }
+                if (typeof value === 'string') {
+                    items.push({ expr, sort });
+                } else {
+                    items.push({ expr, sort, nulls: value.nulls });
+                }
+            }
+        }
+
+        return items.length > 0 ? items : undefined;
+    }
+
     private buildRelationObjectArgs(
         relationModel: string,
         relationModelAlias: string,
diff --git a/packages/orm/src/client/crud/dialects/mysql.ts b/packages/orm/src/client/crud/dialects/mysql.ts
@@ -12,7 +12,7 @@ import {
 } from 'kysely';
 import { AnyNullClass, DbNullClass, JsonNullClass } from '../../../common-types';
 import type { BuiltinType, FieldDef, SchemaDef } from '../../../schema';
-import type { SortOrder } from '../../crud-types';
+import type { NullsOrder, SortOrder } from '../../crud-types';
 import { createInvalidInputError, createNotSupportedError } from '../../errors';
 import type { ClientOptions } from '../../options';
 import { isTypeDef } from '../../query-utils';
@@ -192,7 +192,13 @@ export class MySqlCrudDialect<Schema extends SchemaDef> extends LateralJoinDiale
         return this.eb.exists(this.eb.selectFrom(innerQuery.as('$exists_sub')).select(this.eb.lit(1).as('_')));
     }
 
-    protected buildArrayAgg(arg: Expression<any>): AliasableExpression<any> {
+    protected buildArrayAgg(
+        arg: Expression<any>,
+        _orderBy?: { expr: Expression<any>; sort: SortOrder; nulls?: NullsOrder }[],
+    ): AliasableExpression<any> {
+        // MySQL doesn't support ORDER BY inside JSON_ARRAYAGG.
+        // For relation queries that need deterministic ordering, ordering is applied
+        // by the input subquery before aggregation.
         return this.eb.fn.coalesce(sql`JSON_ARRAYAGG(${arg})`, sql`JSON_ARRAY()`);
     }
 
diff --git a/packages/orm/src/client/crud/dialects/postgresql.ts b/packages/orm/src/client/crud/dialects/postgresql.ts
@@ -11,7 +11,7 @@ import {
 import { parse as parsePostgresArray } from 'postgres-array';
 import { AnyNullClass, DbNullClass, JsonNullClass } from '../../../common-types';
 import type { BuiltinType, FieldDef, SchemaDef } from '../../../schema';
-import type { SortOrder } from '../../crud-types';
+import type { NullsOrder, SortOrder } from '../../crud-types';
 import { createInvalidInputError } from '../../errors';
 import type { ClientOptions } from '../../options';
 import { isEnum, isTypeDef } from '../../query-utils';
@@ -272,8 +272,24 @@ export class PostgresCrudDialect<Schema extends SchemaDef> extends LateralJoinDi
 
     // #region other overrides
 
-    protected buildArrayAgg(arg: Expression<any>) {
-        return this.eb.fn.coalesce(sql`jsonb_agg(${arg})`, sql`'[]'::jsonb`);
+    protected buildArrayAgg(
+        arg: Expression<any>,
+        orderBy?: { expr: Expression<any>; sort: SortOrder; nulls?: NullsOrder }[],
+    ) {
+        if (!orderBy || orderBy.length === 0) {
+            return this.eb.fn.coalesce(sql`jsonb_agg(${arg})`, sql`'[]'::jsonb`);
+        }
+
+        const orderBySql = sql.join(
+            orderBy.map(({ expr, sort, nulls }) => {
+                const dir = sql.raw(sort.toUpperCase());
+                const nullsSql = nulls ? sql` NULLS ${sql.raw(nulls.toUpperCase())}` : sql``;
+                return sql`${expr} ${dir}${nullsSql}`;
+            }),
+            sql.raw(', '),
+        );
+
+        return this.eb.fn.coalesce(sql`jsonb_agg(${arg} ORDER BY ${orderBySql})`, sql`'[]'::jsonb`);
     }
 
     override buildSkipTake(
diff --git a/packages/plugins/policy/package.json b/packages/plugins/policy/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/plugin-policy",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "description": "ZenStack Policy Plugin",
     "type": "module",
     "scripts": {
diff --git a/packages/schema/package.json b/packages/schema/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/schema",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "description": "ZenStack Runtime Schema",
     "type": "module",
     "scripts": {
diff --git a/packages/sdk/package.json b/packages/sdk/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/sdk",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "description": "ZenStack SDK",
     "type": "module",
     "scripts": {
diff --git a/packages/server/package.json b/packages/server/package.json
@@ -1,6 +1,6 @@
 {
     "name": "@zenstackhq/server",
-    "version": "3.5.1",
+    "version": "3.5.2",
     "description": "ZenStack automatic CRUD API handlers and server adapters",
     "type": "module",
     "scripts": {
diff --git a/packages/server/src/api/rest/openapi.ts b/packages/server/src/api/rest/openapi.ts
diff --git a/packages/server/test/openapi/rest-openapi.test.ts b/packages/server/test/openapi/rest-openapi.test.ts
diff --git a/packages/testtools/package.json b/packages/testtools/package.json
diff --git a/packages/zod/package.json b/packages/zod/package.json
diff --git a/samples/orm/package.json b/samples/orm/package.json
diff --git a/tests/e2e/orm/client-api/relation/order-by-nested-includes.test.ts b/tests/e2e/orm/client-api/relation/order-by-nested-includes.test.ts
diff --git a/tests/e2e/package.json b/tests/e2e/package.json
diff --git a/tests/regression/package.json b/tests/regression/package.json
diff --git a/tests/runtimes/bun/package.json b/tests/runtimes/bun/package.json
diff --git a/tests/runtimes/edge-runtime/package.json b/tests/runtimes/edge-runtime/package.json

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "zenstack-v3",`
`3`		`- "version": "3.5.1",`
	`3`	`+ "version": "3.5.2",`
`4`	`4`	`"description": "ZenStack",`
`5`	`5`	`"packageManager": "pnpm@10.23.0",`
`6`	`6`	`"type": "module",`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@zenstackhq/better-auth",`
`3`		`- "version": "3.5.1",`
	`3`	`+ "version": "3.5.2",`
`4`	`4`	`"description": "ZenStack Better Auth Adapter. This adapter is modified from better-auth's Prisma adapter.",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"scripts": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@zenstackhq/client-helpers",`
`3`		`- "version": "3.5.1",`
	`3`	`+ "version": "3.5.2",`
`4`	`4`	`"description": "Helpers for implementing clients that consume ZenStack's CRUD service",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"scripts": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@zenstackhq/tanstack-query",`
`3`		`- "version": "3.5.1",`
	`3`	`+ "version": "3.5.2",`
`4`	`4`	`"description": "TanStack Query Client for consuming ZenStack v3's CRUD service",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"scripts": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@zenstackhq/common-helpers",`
`3`		`- "version": "3.5.1",`
	`3`	`+ "version": "3.5.2",`
`4`	`4`	`"description": "ZenStack Common Helpers",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"scripts": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@zenstackhq/eslint-config",`
`3`		`- "version": "3.5.1",`
	`3`	`+ "version": "3.5.2",`
`4`	`4`	`"type": "module",`
`5`	`5`	`"private": true,`
`6`	`6`	`"license": "MIT"`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@zenstackhq/typescript-config",`
`3`		`- "version": "3.5.1",`
	`3`	`+ "version": "3.5.2",`
`4`	`4`	`"private": true,`
`5`	`5`	`"license": "MIT"`
`6`	`6`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,7 +1,7 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "@zenstackhq/vitest-config",`
`3`	`3`	`"type": "module",`
`4`		`- "version": "3.5.1",`
	`4`	`+ "version": "3.5.2",`
`5`	`5`	`"private": true,`
`6`	`6`	`"license": "MIT",`
`7`	`7`	`"exports": {`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "create-zenstack",`
`3`		`- "version": "3.5.1",`
	`3`	`+ "version": "3.5.2",`
`4`	`4`	`"description": "Create a new ZenStack project",`
`5`	`5`	`"type": "module",`
`6`	`6`	`"scripts": {`