feat(v24): descriptions handling for proprietary date schemas

CHANGELOG.md

@@ -60,8 +60,8 @@ export default [
 ```
 
 ```diff
-- ez.dateIn().example("2021-12-31");
-+ ez.dateIn({ examples: ["2021-12-31"] });
+- ez.dateIn().describe("birthday").example("1963-04-21");
++ ez.dateIn({ description: "birthday", examples: ["1963-04-21"] });
 ```
 
 ## Version 23

example/endpoints/update-user.ts

@@ -16,11 +16,17 @@ export const updateUserEndpoint =
         .transform((value) => parseInt(value, 10))
         .refine((value) => value >= 0, "should be greater than or equal to 0"),
       name: z.string().nonempty().example("John Doe"),
-      birthday: ez.dateIn({ examples: ["1963-04-21"] }),
+      birthday: ez.dateIn({
+        description: "the day of birth",
+        examples: ["1963-04-21"],
+      }),
     }),
     output: z.object({
       name: z.string().example("John Doe"),
-      createdAt: ez.dateOut({ examples: ["2021-12-31"] }),
+      createdAt: ez.dateOut({
+        description: "account creation date",
+        examples: ["2021-12-31"],
+      }),
     }),
     handler: async ({
       input: { id, name },

example/example.client.ts

@@ -67,6 +67,7 @@ type PatchV1UserIdInput = {
   token: string;
   id: string;
   name: string;
+  /** the day of birth */
   birthday: string;
 };
 
@@ -75,6 +76,7 @@ type PatchV1UserIdPositiveVariant1 = {
   status: "success";
   data: {
     name: string;
+    /** account creation date */
     createdAt: string;
   };
 };

example/example.documentation.yaml

@@ -146,7 +146,7 @@ paths:
                   type: string
                   minLength: 1
                 birthday:
-                  description: YYYY-MM-DDTHH:mm:ss.sssZ
+                  description: the day of birth
                   type: string
                   format: date-time
                   pattern: ^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?)?Z?$
@@ -187,7 +187,7 @@ paths:
                           - John Doe
                         type: string
                       createdAt:
-                        description: YYYY-MM-DDTHH:mm:ss.sssZ
+                        description: account creation date
                         type: string
                         format: date-time
                         externalDocs:

express-zod-api/src/date-in-schema.ts

@@ -2,18 +2,22 @@ import { z } from "zod/v4";
 
 export const ezDateInBrand = Symbol("DateIn");
 
-export const dateIn = (meta: Parameters<z.ZodString["meta"]>[0] = {}) => {
+export const dateIn = ({
+  examples,
+  ...rest
+}: Parameters<z.ZodString["meta"]>[0] = {}) => {
   const schema = z.union([
     z.iso.date(),
     z.iso.datetime(),
     z.iso.datetime({ local: true }),
   ]) as unknown as z.ZodUnion<[z.ZodString, z.ZodString, z.ZodString]>; // this fixes DTS build for ez export
 
   return schema
-    .meta(meta)
+    .meta({ examples })
     .transform((str) => new Date(str))
     .pipe(z.date())
-    .brand(ezDateInBrand as symbol);
+    .brand(ezDateInBrand as symbol)
+    .meta(rest);
 };
 
 export type DateInSchema = ReturnType<typeof dateIn>;

express-zod-api/src/documentation-helpers.ts

@@ -176,11 +176,14 @@ const ensureCompliance = ({
   return valid;
 };
 
-export const depictDateIn: Depicter = ({ jsonSchema: { examples } }, ctx) => {
+export const depictDateIn: Depicter = (
+  { jsonSchema: { examples, description } },
+  ctx,
+) => {
   if (ctx.isResponse)
     throw new DocumentationError("Please use ez.dateOut() for output.", ctx);
   const jsonSchema: JSONSchema.StringSchema = {
-    description: "YYYY-MM-DDTHH:mm:ss.sssZ",
+    description: description || "YYYY-MM-DDTHH:mm:ss.sssZ",
     type: "string",
     format: "date-time",
     pattern: /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}:\d{2}(\.\d+)?)?Z?$/.source,
@@ -190,11 +193,14 @@ export const depictDateIn: Depicter = ({ jsonSchema: { examples } }, ctx) => {
   return jsonSchema;
 };
 
-export const depictDateOut: Depicter = ({ jsonSchema: { examples } }, ctx) => {
+export const depictDateOut: Depicter = (
+  { jsonSchema: { examples, description } },
+  ctx,
+) => {
   if (!ctx.isResponse)
     throw new DocumentationError("Please use ez.dateIn() for input.", ctx);
   const jsonSchema: JSONSchema.StringSchema = {
-    description: "YYYY-MM-DDTHH:mm:ss.sssZ",
+    description: description || "YYYY-MM-DDTHH:mm:ss.sssZ",
     type: "string",
     format: "date-time",
     externalDocs: { url: isoDateDocumentationUrl },