Plugin: Restoring metadata example and examples props

CHANGELOG.md

@@ -2,6 +2,16 @@
 
 ## Version 24
 
+### v24.7.1
+
+- Compatibility fix for `zod@^3.25.68` and `^4.0.0`:
+  - Previously typed metadata properties `example` and `examples` were removed from `zod` core:
+    See [Commit ee5615d](https://github.com/colinhacks/zod/commit/ee5615d76b93aac15d7428a17b834a062235f6a1);
+  - This version restores those properties as a part of Zod plugin in order to comply to the existing implementation;
+  - The `example` property is marked as deprecated and will be removed in v25 — please refrain from using it;
+  - The `examples` property still supports an object for backward compatibility, but it will only support array in v25;
+  - To avoid confusion, consider using the Zod plugin's method `.example()` where possible (except `ez.dateIn()`).
+
 ### v24.7.0
 
 - Supporting `HEAD` method:

express-zod-api/src/metadata.ts

@@ -15,15 +15,19 @@ export const getBrand = (subject: $ZodType) => {
 };
 
 /**
- * @since zod 3.25.44
+ * @since zod 3.25.44 can be an object
  * @link https://github.com/colinhacks/zod/pull/4586
+ * @since zod 3.25.68 and 4.0.0 was completely removed
+ * @link https://github.com/colinhacks/zod/commit/ee5615d76b93aac15d7428a17b834a062235f6a1
  * */
 export const getExamples = (subject: $ZodType): ReadonlyArray<unknown> => {
   const { examples, example } = globalRegistry.get(subject) || {};
   if (examples) {
     return Array.isArray(examples)
       ? examples
-      : Object.values(examples).map(({ value }) => value);
+      : /** @todo remove this branch in v25 */
+        Object.values(examples).map(({ value }) => value);
   }
+  /** @todo remove this in v25 */
   return example === undefined ? [] : [example];
 };

express-zod-api/src/zod-plugin.ts

@@ -40,6 +40,11 @@ declare module "ramda" {
 declare module "zod/v4/core" {
   interface GlobalMeta {
     default?: unknown; // can be an actual value or a label like "Today"
+    examples?:
+      | unknown[] // see zod commit ee5615d
+      | Record<string, { value: unknown; [k: string]: unknown }>; // @todo remove in v25
+    /** @deprecated use examples instead */
+    example?: unknown; // see zod commit ee5615d @todo remove in v25
   }
 }