Merge branch 'make-v24' into feat-error-tree

RobinTail · web-flow · commit 58c0d0577ae5 · 2025-05-28T12:43:06.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,7 +6,7 @@
 
 - Switched to Zod 4:
   - Minimum supported version of `zod` is 3.25.1, BUT imports MUST be from `zod/v4`;
-    - Explanation of the versioning strategy: https://github.com/colinhacks/zod/issues/4371;
+    - Read the [Explanation of the versioning strategy](https://github.com/colinhacks/zod/issues/4371);
     - Express Zod API, however, is not aiming to support both Zod 3 and Zod 4 simultaneously due to:
       - incompatibility of data structures;
       - operating composite schemas (need to avoid mixing schemas of different versions);
@@ -21,19 +21,23 @@
     - In order to specify an example for an input schema the `.example()` method must be called before `.transform()`;
 - The transforming proprietary schemas `ez.dateIn()` and `ez.dateOut()` now accept metadata as its argument:
   - This allows to set examples before transformation (`ez.dateIn()`) and to avoid the examples "branding";
-- Generating Documentation is mostly delegated to Zod 4 `z.toJSONSchema()`:
-  - The basic depiction of each schema is now natively performed by Zod 4;
+- Changes to `Documentation`:
+  - Generating Documentation is mostly delegated to Zod 4 `z.toJSONSchema()`;
   - Express Zod API implements some overrides and improvements to fit it into OpenAPI 3.1 that extends JSON Schema;
   - The `numericRange` option removed from `Documentation` class constructor argument;
   - The `Depicter` type signature changed: became a postprocessing function returning an overridden JSON Schema;
-- The `optionalPropStyle` option removed from `Integration` class constructor:
+- Changes to `Integration`:
+  - The `optionalPropStyle` option removed from `Integration` class constructor:
   - Use `.optional()` to add question mark to the object property as well as `undefined` to its type;
   - Use `.or(z.undefined())` to add `undefined` to the type of the object property;
-  - Reasoning: https://x.com/colinhacks/status/1919292504861491252;
-  - `z.any()` and `z.unknown()` are not optional, details: https://v4.zod.dev/v4/changelog#changes-zunknown-optionality.
-- The argument of `ResultHandler::handler` is now discriminated: either `output` or `error` is null, not both;
+  - See the [reasoning](https://x.com/colinhacks/status/1919292504861491252);
+  - `z.any()` and `z.unknown()` are required: [details](https://v4.zod.dev/v4/changelog#changes-zunknown-optionality);
+  - Added types generation for `z.never()`, `z.void()` and `z.unknown()` schemas;
+  - The fallback type for unsupported schemas and unclear transformations in response changed from `any` to `unknown`;
+- The argument of `ResultHandler::handler` is now discriminated: either `output` or `error` is `null`, not both;
 - The `getExamples()` public helper removed — use `.meta()?.examples` instead;
-- The `ez.file()` schema removed: use `z.string()`, `z.base64()` or the new `ez.buffer()` instead;
+- Added the new proprietary schema `ez.buffer()`;
+- The `ez.file()` schema removed: use `z.string()`, `z.base64()`, `ez.buffer()` or their union;
 - Consider the automated migration using the built-in ESLint rule.
 
 ```js
diff --git a/eslint.config.js b/eslint.config.js
@@ -20,6 +20,14 @@ const importConcerns = [
       "ImportDeclaration[source.value='ramda'] > ImportDefaultSpecifier",
     message: "use import * as R from 'ramda'",
   },
+  {
+    selector: "ImportDeclaration[source.value=/^zod/] > ImportDefaultSpecifier",
+    message: "do import { z } instead",
+  },
+  {
+    selector: "ImportDeclaration[source.value='zod'] > ImportSpecifier",
+    message: "should import from zod/v4", // @todo remove when zod version changed to 4.0.0
+  },
   ...builtinModules.map((mod) => ({
     selector: `ImportDeclaration[source.value='${mod}']`,
     message: `use node:${mod} for the built-in module`,
diff --git a/example/endpoints/list-users.ts b/example/endpoints/list-users.ts
@@ -1,4 +1,4 @@
-import z from "zod/v4";
+import { z } from "zod/v4";
 import { arrayRespondingFactory } from "../factories";
 
 /**
diff --git a/express-zod-api/package.json b/express-zod-api/package.json
@@ -1,6 +1,6 @@
 {
   "name": "express-zod-api",
-  "version": "24.0.0-beta.8",
+  "version": "24.0.0-beta.9",
   "description": "A Typescript framework to help you get an API server up and running with I/O schema validation and custom middlewares in minutes.",
   "license": "MIT",
   "repository": {
diff --git a/express-zod-api/src/common-helpers.ts b/express-zod-api/src/common-helpers.ts
@@ -8,6 +8,7 @@ import { AuxMethod, Method } from "./method";
 
 /** @desc this type does not allow props assignment, but it works for reading them when merged with another interface */
 export type EmptyObject = z.output<EmptySchema>;
+/** Avoiding z.ZodObject<Record<string, never>, $strip>, because its z.output<> is generic "object" (external issue) */
 export type EmptySchema = z.ZodRecord<z.ZodString, z.ZodNever>;
 export type FlatObject = Record<string, unknown>;
 
@@ -64,8 +65,8 @@ export const getInput = (
 export const ensureError = (subject: unknown): Error =>
   subject instanceof Error
     ? subject
-    : subject instanceof z.ZodError
-      ? new z.ZodRealError(subject.issues) // ZodError is not an instance of Error, unlike ZodRealError that is
+    : subject instanceof z.ZodError // ZodError does not extend Error, unlike ZodRealError that does
+      ? new z.ZodRealError(subject.issues)
       : new Error(String(subject));
 
 export const getMessageFromError = (error: Error): string => {
diff --git a/express-zod-api/src/date-out-schema.ts b/express-zod-api/src/date-out-schema.ts
@@ -12,5 +12,7 @@ export const dateOut = ({
     .brand(ezDateOutBrand as symbol)
     .meta({
       ...rest,
-      examples: examples as Array<string & z.$brand> | undefined,
+      examples: examples as
+        | Array<NonNullable<typeof examples>[number] & z.$brand>
+        | undefined,
     });
diff --git a/express-zod-api/src/endpoints-factory.ts b/express-zod-api/src/endpoints-factory.ts
@@ -118,7 +118,7 @@ export class EndpointsFactory<
   }
 
   public build<BOUT extends IOSchema, BIN extends IOSchema = EmptySchema>({
-    input = z.object({}) as IOSchema as BIN, // @todo revisit
+    input = z.object({}) as unknown as BIN,
     output: outputSchema,
     operationId,
     scope,
diff --git a/express-zod-api/src/json-schema-helpers.ts b/express-zod-api/src/json-schema-helpers.ts
@@ -9,7 +9,7 @@ const isJsonObjectSchema = (
 const propsMerger = R.mergeDeepWith((a: unknown, b: unknown) => {
   if (Array.isArray(a) && Array.isArray(b)) return R.concat(a, b);
   if (a === b) return b;
-  throw new Error("Can not flatten properties");
+  throw new Error("Can not flatten properties", { cause: { a, b } });
 });
 
 const canMerge = R.pipe(
diff --git a/express-zod-api/src/middleware.ts b/express-zod-api/src/middleware.ts
@@ -50,7 +50,7 @@ export class Middleware<
   readonly #handler: Handler<z.output<IN>, OPT, OUT>;
 
   constructor({
-    input = z.object({}) as IOSchema as IN, // @todo revisit
+    input = z.object({}) as unknown as IN,
     security,
     handler,
   }: {
diff --git a/express-zod-api/src/zod-plugin.ts b/express-zod-api/src/zod-plugin.ts
@@ -141,14 +141,12 @@ if (!(metaSymbol in globalThis)) {
     if (typeof Cls !== "function") continue;
     Object.defineProperties(Cls.prototype, {
       ["example" satisfies keyof z.ZodType]: {
-        get(): z.ZodType["example"] {
-          return exampleSetter.bind(this);
-        },
+        value: exampleSetter,
+        writable: false,
       },
       ["deprecated" satisfies keyof z.ZodType]: {
-        get(): z.ZodType["deprecated"] {
-          return deprecationSetter.bind(this);
-        },
+        value: deprecationSetter,
+        writable: false,
       },
       ["brand" satisfies keyof z.ZodType]: {
         set() {}, // this is required to override the existing method
@@ -162,19 +160,11 @@ if (!(metaSymbol in globalThis)) {
   Object.defineProperty(
     z.ZodDefault.prototype,
     "label" satisfies keyof z.ZodDefault,
-    {
-      get(): z.ZodDefault["label"] {
-        return labelSetter.bind(this);
-      },
-    },
+    { value: labelSetter, writable: false },
   );
   Object.defineProperty(
     z.ZodObject.prototype,
     "remap" satisfies keyof z.ZodObject,
-    {
-      get() {
-        return objectMapper.bind(this);
-      },
-    },
+    { value: objectMapper, writable: false },
   );
 }
diff --git a/express-zod-api/src/zts.ts b/express-zod-api/src/zts.ts
@@ -160,6 +160,11 @@ const onWrapped: Producer = (
   { next },
 ) => next(def.innerType);
 
+const getFallback = (isResponse: boolean) =>
+  ensureTypeNode(
+    isResponse ? ts.SyntaxKind.UnknownKeyword : ts.SyntaxKind.AnyKeyword,
+  );
+
 const onPipeline: Producer = (
   { _zod: { def } }: $ZodPipe,
   { next, isResponse },
@@ -180,7 +185,7 @@ const onPipeline: Producer = (
     object: ts.SyntaxKind.ObjectKeyword,
   };
   return ensureTypeNode(
-    (targetType && resolutions[targetType]) || ts.SyntaxKind.AnyKeyword,
+    (targetType && resolutions[targetType]) || getFallback(isResponse),
   );
 };
 
@@ -207,6 +212,9 @@ const producers: HandlingRules<
   undefined: onPrimitive(ts.SyntaxKind.UndefinedKeyword),
   [ezDateInBrand]: onPrimitive(ts.SyntaxKind.StringKeyword),
   [ezDateOutBrand]: onPrimitive(ts.SyntaxKind.StringKeyword),
+  never: onPrimitive(ts.SyntaxKind.NeverKeyword),
+  void: onPrimitive(ts.SyntaxKind.UndefinedKeyword),
+  unknown: onPrimitive(ts.SyntaxKind.UnknownKeyword),
   null: onNull,
   array: onArray,
   tuple: onTuple,
@@ -239,6 +247,6 @@ export const zodToTs = (
 ) =>
   walkSchema(schema, {
     rules: { ...brandHandling, ...producers },
-    onMissing: () => ensureTypeNode(ts.SyntaxKind.AnyKeyword),
+    onMissing: ({}, { isResponse }) => getFallback(isResponse),
     ctx,
   });
diff --git a/express-zod-api/tests/__snapshots__/zts.spec.ts.snap b/express-zod-api/tests/__snapshots__/zts.spec.ts.snap
@@ -18,10 +18,10 @@ exports[`zod-to-ts > Example > should produce the expected results 1`] = `
     date: any;
     undefined: undefined;
     null: null;
-    void: any;
+    void: undefined;
     any: any;
-    unknown: any;
-    never: any;
+    unknown: unknown;
+    never: never;
     optionalString?: string | undefined;
     nullablePartialObject: {
         string?: string | undefined;
@@ -139,18 +139,33 @@ exports[`zod-to-ts > Issue #2352: intersection of objects having same prop %# >
 }"
 `;
 
-exports[`zod-to-ts > PrimitiveSchema > outputs correct typescript 1`] = `
+exports[`zod-to-ts > PrimitiveSchema (isResponse=false) > outputs correct typescript 1`] = `
 "{
     string: string;
     number: number;
     boolean: boolean;
     date: any;
     undefined: undefined;
     null: null;
-    void: any;
+    void: undefined;
     any: any;
-    unknown: any;
-    never: any;
+    unknown: unknown;
+    never: never;
+}"
+`;
+
+exports[`zod-to-ts > PrimitiveSchema (isResponse=true) > outputs correct typescript 1`] = `
+"{
+    string: string;
+    number: number;
+    boolean: boolean;
+    date: unknown;
+    undefined: undefined;
+    null: null;
+    void: undefined;
+    any: any;
+    unknown: unknown;
+    never: never;
 }"
 `;
 
@@ -185,14 +200,6 @@ exports[`zod-to-ts > z.discriminatedUnion() > outputs correct typescript 1`] = `
 }"
 `;
 
-exports[`zod-to-ts > z.effect() > transformations > should handle an error within the transformation 1`] = `"any"`;
-
-exports[`zod-to-ts > z.effect() > transformations > should handle unsupported transformation in response 1`] = `"any"`;
-
-exports[`zod-to-ts > z.effect() > transformations > should produce the schema type 'intact' 1`] = `"number"`;
-
-exports[`zod-to-ts > z.effect() > transformations > should produce the schema type 'transformed' 1`] = `"string"`;
-
 exports[`zod-to-ts > z.literal() > Should produce the correct typescript 0 1`] = `""test""`;
 
 exports[`zod-to-ts > z.literal() > Should produce the correct typescript 1 1`] = `"true"`;
@@ -262,8 +269,6 @@ exports[`zod-to-ts > z.object() > supports zod.describe() 1`] = `
 }"
 `;
 
-exports[`zod-to-ts > z.optional() > Zod 4: does not add undefined to it, unwrap as is 1`] = `"string"`;
-
 exports[`zod-to-ts > z.optional() > Zod 4: should add question mark only to optional props 1`] = `
 "{
     optional?: string | undefined;
@@ -280,3 +285,13 @@ exports[`zod-to-ts > z.optional() > Zod 4: should add question mark only to opti
     ] | undefined;
 }"
 `;
+
+exports[`zod-to-ts > z.pipe() > transformations > should handle an error within the transformation 1`] = `"unknown"`;
+
+exports[`zod-to-ts > z.pipe() > transformations > should handle preprocess error in request 1`] = `"any"`;
+
+exports[`zod-to-ts > z.pipe() > transformations > should handle unsupported transformation in response 1`] = `"unknown"`;
+
+exports[`zod-to-ts > z.pipe() > transformations > should produce the schema type 'intact' 1`] = `"number"`;
+
+exports[`zod-to-ts > z.pipe() > transformations > should produce the schema type 'transformed' 1`] = `"string"`;
diff --git a/express-zod-api/tests/integration.spec.ts b/express-zod-api/tests/integration.spec.ts
@@ -108,7 +108,7 @@ describe("Integration", () => {
         schema: ReturnType<z.ZodType["brand"]>,
         { next },
       ) => {
-        delete schema._zod.bag.brand;
+        schema._zod.bag.brand = undefined;
         return next(schema);
       };
       const client = new Integration({
diff --git a/express-zod-api/tests/zts.spec.ts b/express-zod-api/tests/zts.spec.ts
@@ -201,7 +201,7 @@ describe("zod-to-ts", () => {
 
     test("Zod 4: does not add undefined to it, unwrap as is", () => {
       const node = zodToTs(optionalStringSchema, { ctx });
-      expect(printNodeTest(node)).toMatchSnapshot();
+      expect(printNodeTest(node)).toEqual("string");
     });
 
     test("Zod 4: should add question mark only to optional props", () => {
@@ -328,25 +328,28 @@ describe("zod-to-ts", () => {
     );
   });
 
-  describe("PrimitiveSchema", () => {
-    const primitiveSchema = z.object({
-      string: z.string(),
-      number: z.number(),
-      boolean: z.boolean(),
-      date: z.date(),
-      undefined: z.undefined(),
-      null: z.null(),
-      void: z.void(),
-      any: z.any(),
-      unknown: z.unknown(),
-      never: z.never(),
-    });
-    const node = zodToTs(primitiveSchema, { ctx });
+  describe.each([true, false])(
+    "PrimitiveSchema (isResponse=%s)",
+    (isResponse) => {
+      const primitiveSchema = z.object({
+        string: z.string(),
+        number: z.number(),
+        boolean: z.boolean(),
+        date: z.date(),
+        undefined: z.undefined(),
+        null: z.null(),
+        void: z.void(),
+        any: z.any(),
+        unknown: z.unknown(),
+        never: z.never(),
+      });
+      const node = zodToTs(primitiveSchema, { ctx: { ...ctx, isResponse } });
 
-    test("outputs correct typescript", () => {
-      expect(printNodeTest(node)).toMatchSnapshot();
-    });
-  });
+      test("outputs correct typescript", () => {
+        expect(printNodeTest(node)).toMatchSnapshot();
+      });
+    },
+  );
 
   describe("z.discriminatedUnion()", () => {
     const shapeSchema = z.discriminatedUnion("kind", [
@@ -373,7 +376,7 @@ describe("zod-to-ts", () => {
     });
   });
 
-  describe("z.effect()", () => {
+  describe("z.pipe()", () => {
     describe("transformations", () => {
       test.each([
         { isResponse: false, expected: "intact" },
@@ -392,6 +395,13 @@ describe("zod-to-ts", () => {
         ).toMatchSnapshot();
       });
 
+      test("should handle preprocess error in request", () => {
+        const schema = z.preprocess(() => {
+          throw new Error("intentional");
+        }, z.number());
+        expect(printNodeTest(zodToTs(schema, { ctx }))).toMatchSnapshot();
+      });
+
       test("should handle an error within the transformation", () => {
         const schema = z
           .number()
diff --git a/tools/headers.ts b/tools/headers.ts
@@ -1,7 +1,7 @@
 import { execSync } from "node:child_process";
 import { writeFile } from "node:fs/promises";
 import * as R from "ramda";
-import { z } from "zod";
+import { z } from "zod/v4";
 
 /**
  * @link https://chatgpt.com/c/6795dae3-8a10-800e-96af-fd0d01579f39

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import z from "zod/v4";`
	`1`	`+import { z } from "zod/v4";`
`2`	`2`	`import { arrayRespondingFactory } from "../factories";`
`3`	`3`
`4`	`4`	`/**`
Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "express-zod-api",`
`3`		`- "version": "24.0.0-beta.8",`
	`3`	`+ "version": "24.0.0-beta.9",`
`4`	`4`	`"description": "A Typescript framework to help you get an API server up and running with I/O schema validation and custom middlewares in minutes.",`
`5`	`5`	`"license": "MIT",`
`6`	`6`	`"repository": {`
Original file line number	Diff line number	Diff line change
`@@ -118,7 +118,7 @@ export class EndpointsFactory<`
`118`	`118`	`}`
`119`	`119`
`120`	`120`	`public build<BOUT extends IOSchema, BIN extends IOSchema = EmptySchema>({`
`121`		`- input = z.object({}) as IOSchema as BIN, // @todo revisit`
	`121`	`+ input = z.object({}) as unknown as BIN,`
`122`	`122`	`output: outputSchema,`
`123`	`123`	`operationId,`
`124`	`124`	`scope,`