Port for v25: avoid using example method in sources (#2955)

Cherry-picked 3aacc05 , #2954 

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->

## Summary by CodeRabbit

- New Features
- Standardized error handling with reusable default and array error
schemas, including documented examples.
- arrayResultHandler now uses a structured negative configuration
(schema + mimeType).

- Bug Fixes
- Resolved a TypeError occurring in some environments related to
generating examples.

- Documentation
  - Added v25.4.1 changelog entry with details and attribution.
  - Updated README with additional contributor avatars.

- Chores
- Introduced an ESLint rule to flag incompatible example() usage,
improving cross-environment compatibility.

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

Author: RobinTail

CHANGELOG.md

@@ -2,6 +2,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:

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)

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,
       ],
     },
   },

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);