v24: Replacing usage of example() method in framework sources

CHANGELOG.md

@@ -2,6 +2,14 @@
 
 ## Version 24
 
+### v24.7.4
+
+- 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).
+
 ### v24.7.3
 
 - Fixed the depiction of the negative response to `HEAD` requests:

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/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)
 [<img src="https://github.com/zoton2.png" alt="@zoton2" width="50px" />](https://github.com/zoton2)

eslint.config.js

@@ -33,6 +33,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
@@ -210,6 +217,7 @@ export default tsPlugin.config(
         "warn",
         ...importConcerns,
         ...performanceConcerns,
+        ...compatibilityConcerns,
       ],
     },
   },

express-zod-api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "express-zod-api",
-  "version": "24.7.3",
+  "version": "24.7.4-beta.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": {

express-zod-api/src/result-handler.ts

@@ -95,6 +95,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({
@@ -112,15 +122,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);
@@ -139,6 +141,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.
@@ -169,10 +178,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);