Merge branch 'master' into make-v26

RobinTail · web-flow · commit a8138fb54693 · 2025-09-21T19:36:10.000+02:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -21,6 +21,14 @@
 
 ## Version 25
 
+### v25.4.1
+
+- This patch fixes the issue for users facing `TypeError: .example is not a function`, but not using that method:
+  - Some environments fail to load Zod plugin properly so that the usage of `ZodType::example()` (plugin method)
+    internally by the framework itself could cause that error;
+  - This version fixes the problem by replacing the usage of `.example()` with `globalRegistry.add()`;
+  - The issue was found and reported by [@misha-z1nchuk](https://github.com/misha-z1nchuk).
+
 ### v25.4.0
 
 - Feat: configurable query parser:
diff --git a/README.md b/README.md
@@ -85,6 +85,7 @@ Therefore, many basic tasks can be accomplished faster and easier, in particular
 
 These people contributed to the improvement of the framework by reporting bugs, making changes and suggesting ideas:
 
+[<img src="https://github.com/misha-z1nchuk.png" alt="@misha-z1nchuk" width="50px" />](https://github.com/misha-z1nchuk)
 [<img src="https://github.com/GreaterTamarack.png" alt="@GreaterTamarack" width="50px" />](https://github.com/GreaterTamarack)
 [<img src="https://github.com/pepegc.png" alt="@pepegc" width="50px" />](https://github.com/pepegc)
 [<img src="https://github.com/MichaelHindley.png" alt="@MichaelHindley" width="50px" />](https://github.com/MichaelHindley)
diff --git a/eslint.config.js b/eslint.config.js
@@ -30,6 +30,13 @@ const importConcerns = [
   })),
 ];
 
+const compatibilityConcerns = [
+  {
+    selector: "CallExpression > MemberExpression[property.name='example']",
+    message: "avoid using example() method to operate without zod plugin",
+  },
+];
+
 const performanceConcerns = [
   {
     selector: "ImportDeclaration[source.value=/assert/]", // #2169
@@ -202,6 +209,7 @@ export default tsPlugin.config(
         "warn",
         ...importConcerns,
         ...performanceConcerns,
+        ...compatibilityConcerns,
       ],
     },
   },
diff --git a/express-zod-api/package.json b/express-zod-api/package.json
@@ -1,6 +1,6 @@
 {
   "name": "express-zod-api",
-  "version": "25.4.0",
+  "version": "25.4.1",
   "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/result-handler.ts b/express-zod-api/src/result-handler.ts
@@ -94,6 +94,16 @@ export class ResultHandler<
   }
 }
 
+const defaultNegativeSchema = z.object({
+  status: z.literal("error"),
+  error: z.object({ message: z.string() }),
+});
+globalRegistry.add(defaultNegativeSchema, {
+  examples: [
+    { status: "error", error: { message: "Sample error message" } },
+  ] satisfies z.output<typeof defaultNegativeSchema>[],
+});
+
 export const defaultResultHandler = new ResultHandler({
   positive: (output) => {
     const responseSchema = z.object({
@@ -111,15 +121,7 @@ export const defaultResultHandler = new ResultHandler({
     }
     return responseSchema;
   },
-  negative: z
-    .object({
-      status: z.literal("error"),
-      error: z.object({ message: z.string() }),
-    })
-    .example({
-      status: "error",
-      error: { message: "Sample error message" },
-    }),
+  negative: defaultNegativeSchema,
   handler: ({ error, input, output, request, response, logger }) => {
     if (error) {
       const httpError = ensureHttpError(error);
@@ -138,6 +140,13 @@ export const defaultResultHandler = new ResultHandler({
   },
 });
 
+const arrayNegativeSchema = z.string();
+globalRegistry.add(arrayNegativeSchema, {
+  examples: ["Sample error message"] satisfies z.output<
+    typeof arrayNegativeSchema
+  >[],
+});
+
 /**
  * @deprecated Resist the urge of using it: this handler is designed only to simplify the migration of legacy APIs.
  * @desc Responding with array is a bad practice keeping your endpoints from evolving without breaking changes.
@@ -170,10 +179,7 @@ export const arrayResultHandler = new ResultHandler({
     }
     return responseSchema;
   },
-  negative: {
-    schema: z.string().example("Sample error message"),
-    mimeType: "text/plain",
-  },
+  negative: { schema: arrayNegativeSchema, mimeType: "text/plain" },
   handler: ({ response, output, error, logger, request, input }) => {
     if (error) {
       const httpError = ensureHttpError(error);
diff --git a/express-zod-api/tests/__snapshots__/env.spec.ts.snap b/express-zod-api/tests/__snapshots__/env.spec.ts.snap
@@ -215,6 +215,45 @@ exports[`Environment checks > Zod checks/refinements > Snapshot control 'ZodStri
 }
 `;
 
+exports[`Environment checks > Zod imperfections > circular object schema has no sign of getter in its shape 1`] = `
+{
+  "features": {
+    "configurable": true,
+    "enumerable": true,
+    "value": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "items": {
+        "additionalProperties": false,
+        "properties": {
+          "features": {
+            "$ref": "#",
+          },
+          "name": {
+            "type": "string",
+          },
+        },
+        "required": [
+          "name",
+          "features",
+        ],
+        "type": "object",
+      },
+      "type": "array",
+    },
+    "writable": true,
+  },
+  "name": {
+    "configurable": true,
+    "enumerable": true,
+    "value": {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "type": "string",
+    },
+    "writable": true,
+  },
+}
+`;
+
 exports[`Environment checks > Zod new features > input examples of transformations 1`] = `
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
diff --git a/express-zod-api/tests/env.spec.ts b/express-zod-api/tests/env.spec.ts
@@ -50,16 +50,16 @@ describe("Environment checks", () => {
       expect(R.omit(["$schema"], json)).toEqual({});
     });
 
-    test("circular object schema has a getter since 4.0.15", () => {
+    test("circular object schema has no sign of getter in its shape", () => {
       const schema = z.object({
         name: z.string(),
         get features() {
           return schema.array();
         },
       });
       expect(
-        Object.getOwnPropertyDescriptors(schema._zod.def.shape).features,
-      ).toHaveProperty("get", expect.any(Function));
+        Object.getOwnPropertyDescriptors(schema._zod.def.shape),
+      ).toMatchSnapshot();
     });
 
     test("ZodError inequality", () => {
diff --git a/package.json b/package.json
@@ -24,7 +24,7 @@
     "eslint-plugin-prettier": "^5.4.1",
     "husky": "^9.0.5",
     "prettier": "3.6.2",
-    "tsdown": "^0.15.0",
+    "tsdown": "^0.15.3",
     "tsx": "^4.19.4",
     "typescript-eslint": "catalog:dev",
     "vitest": "^3.2.3"
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml

Original file line number	Diff line number	Diff line change
`@@ -1,6 +1,6 @@`
`1`	`1`	`{`
`2`	`2`	`"name": "express-zod-api",`
`3`		`- "version": "25.4.0",`
	`3`	`+ "version": "25.4.1",`
`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": {`