express-zod-api 24.0.0-beta.1 → 24.0.0-beta.10

package/CHANGELOG.md

@@ -6,26 +6,38 @@
 
 - Switched to Zod 4:
   - Minimum supported version of `zod` is 3.25.1, BUT imports MUST be from `zod/v4`;
-    - Explanation of the versioning strategy: https://github.com/colinhacks/zod/issues/4371;
+    - Read the [Explanation of the versioning strategy](https://github.com/colinhacks/zod/issues/4371);
     - Express Zod API, however, is not aiming to support both Zod 3 and Zod 4 simultaneously due to:
       - incompatibility of data structures;
       - operating composite schemas (need to avoid mixing schemas of different versions);
       - the temporary nature of this transition;
       - the advantages of Zod 4 that provide opportunities to simplifications and corrections of known issues.
   - `IOSchema` type had to be simplified down to a schema resulting to an `object`, but not an `array`;
-  - Despite supporting examples by the new Zod method `.meta()`, users should still use `.example()` to set them;
   - Refer to [Migration guide on Zod 4](https://v4.zod.dev/v4/changelog) for adjusting your schemas;
-- Generating Documentation is partially delegated to Zod 4 `z.toJSONSchema()`:
-  - The basic depiction of each schema is now natively performed by Zod 4;
+- Changes to `ZodType::example()` (Zod plugin method):
+  - Now acts as an alias for `ZodType::meta({ examples })`;
+  - The argument has to be the output type of the schema (used to be the opposite):
+    - This change is only breaking for transforming schemas;
+    - In order to specify an example for an input schema the `.example()` method must be called before `.transform()`;
+- The transforming proprietary schemas `ez.dateIn()` and `ez.dateOut()` now accept metadata as its argument:
+  - This allows to set examples before transformation (`ez.dateIn()`) and to avoid the examples "branding";
+- Changes to `Documentation`:
+  - Generating Documentation is mostly delegated to Zod 4 `z.toJSONSchema()`;
   - Express Zod API implements some overrides and improvements to fit it into OpenAPI 3.1 that extends JSON Schema;
   - The `numericRange` option removed from `Documentation` class constructor argument;
-  - The `brandHandling` should consist of postprocessing functions altering the depiction made by Zod 4;
-  - The `Depicter` type signature changed;
-- The `optionalPropStyle` option removed from `Integration` class constructor:
+  - The `Depicter` type signature changed: became a postprocessing function returning an overridden JSON Schema;
+- Changes to `Integration`:
+  - The `optionalPropStyle` option removed from `Integration` class constructor:
   - Use `.optional()` to add question mark to the object property as well as `undefined` to its type;
   - Use `.or(z.undefined())` to add `undefined` to the type of the object property;
-  - Reasoning: https://x.com/colinhacks/status/1919292504861491252;
-  - `z.any()` and `z.unknown()` are not optional, details: https://v4.zod.dev/v4/changelog#changes-zunknown-optionality.
+  - See the [reasoning](https://x.com/colinhacks/status/1919292504861491252);
+  - `z.any()` and `z.unknown()` are required: [details](https://v4.zod.dev/v4/changelog#changes-zunknown-optionality);
+  - Added types generation for `z.never()`, `z.void()` and `z.unknown()` schemas;
+  - The fallback type for unsupported schemas and unclear transformations in response changed from `any` to `unknown`;
+- The argument of `ResultHandler::handler` is now discriminated: either `output` or `error` is `null`, not both;
+- The `getExamples()` public helper removed — use `.meta()?.examples` instead;
+- Added the new proprietary schema `ez.buffer()`;
+- The `ez.file()` schema removed: use `z.string()`, `z.base64()`, `ez.buffer()` or their union;
 - Consider the automated migration using the built-in ESLint rule.
 
 ```js
@@ -44,8 +56,34 @@ export default [
 + import { z } from "zod/v4";
 ```
 
+```diff
+  input: z.string()
++   .example("123")
+    .transform(Number)
+-   .example("123")
+```
+
+```diff
+- ez.dateIn().example("2021-12-31");
++ ez.dateIn({ examples: ["2021-12-31"] });
+- ez.file("base64");
++ z.base64();
+- ez.file("buffer");
++ ez.buffer();
+```
+
 ## Version 23
 
+### v23.6.1
+
+- `createServer()` displays a warning when no server is configured.
+
+### v23.6.0
+
+- Featuring `gracefulShutdown.beforeExit()` hook:
+  - The function to execute after the server was closed, but before terminating the process (can be asynchronous);
+  - The feature suggested by [@HeikoOsigus](https://github.com/HeikoOsigus).
+
 ### v23.5.0
 
 - Integer number `format` in generated Documentation now also depends on the `numericRange` option:

package/README.md

@@ -36,9 +36,9 @@ Start your API server with I/O schema validation and custom middlewares in minut
    2. [Headers as input source](#headers-as-input-source)
    3. [Response customization](#response-customization)
    4. [Empty response](#empty-response)
-   5. [Error handling](#error-handling)
-   6. [Production mode](#production-mode)
-   7. [Non-object response](#non-object-response) including file downloads
+   5. [Non-JSON response](#non-json-response) including file downloads
+   6. [Error handling](#error-handling)
+   7. [Production mode](#production-mode)
    8. [HTML Forms (URL encoded)](#html-forms-url-encoded)
    9. [File uploads](#file-uploads)
    10. [Connect to your own express app](#connect-to-your-own-express-app)
@@ -84,6 +84,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/HeikoOsigus.png" alt="@HeikoOsigus" width="50px" />](https://github.com/HeikoOsigus)
 [<img src="https://github.com/crgeary.png" alt="@crgeary" width="50px" />](https://github.com/crgeary)
 [<img src="https://github.com/williamgcampbell.png" alt="@williamgcampbell" width="50px" />](https://github.com/williamgcampbell)
 [<img src="https://github.com/gmorgen1.png" alt="@gmorgen1" width="50px" />](https://github.com/gmorgen1)
@@ -478,7 +479,7 @@ By the way, you can also refine the whole I/O object, for example in case you ne
 const endpoint = endpointsFactory.build({
   input: z
     .object({
-      email: z.string().email().optional(),
+      email: z.email().optional(),
       id: z.string().optional(),
       otherThing: z.string().optional(),
     })
@@ -561,7 +562,7 @@ in actual response by calling
 which in turn calls
 [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString).
 It is also impossible to transmit the `Date` in its original form to your endpoints within JSON. Therefore, there is
-confusion with original method ~~z.date()~~ that should not be used within IO schemas of your API.
+confusion with original method ~~z.date()~~ that is not recommended to use without transformations.
 
 In order to solve this problem, the framework provides two custom methods for dealing with dates: `ez.dateIn()` and
 `ez.dateOut()` for using within input and output schemas accordingly.
@@ -577,7 +578,7 @@ provides your endpoint handler or middleware with a `Date`. It supports the foll
 ```
 
 `ez.dateOut()`, on the contrary, accepts a `Date` and provides `ResultHandler` with a `string` representation in ISO
-format for the response transmission. Consider the following simplified example for better understanding:
+format for the response transmission. Both schemas accept metadata as an argument. Consider the following example:
 
 ```typescript
 import { z } from "zod/v4";
@@ -587,10 +588,10 @@ const updateUserEndpoint = defaultEndpointsFactory.build({
   method: "post",
   input: z.object({
     userId: z.string(),
-    birthday: ez.dateIn(), // string -> Date in handler
+    birthday: ez.dateIn({ examples: ["1963-04-21"] }), // string -> Date in handler
   }),
   output: z.object({
-    createdAt: ez.dateOut(), // Date -> string in response
+    createdAt: ez.dateOut({ examples: ["2021-12-31"] }), // Date -> string in response
   }),
   handler: async ({ input }) => ({
     createdAt: new Date("2022-01-22"), // 2022-01-22T00:00:00.000Z
@@ -871,6 +872,33 @@ const resultHandler = new ResultHandler({
 });
 ```
 
+## Non-JSON response
+
+To configure a non-JSON responses (for example, to send an image file) you should specify its MIME type.
+
+You can find two approaches to `EndpointsFactory` and `ResultHandler` implementation
+[in this example](https://github.com/RobinTail/express-zod-api/blob/master/example/factories.ts).
+One of them implements file streaming, in this case the endpoint just has to provide the filename.
+The response schema can be `z.string()`, `z.base64()` or `ez.buffer()` to reflect the data accordingly in the
+[generated documentation](#creating-a-documentation).
+
+```typescript
+const fileStreamingEndpointsFactory = new EndpointsFactory(
+  new ResultHandler({
+    positive: { schema: ez.buffer(), mimeType: "image/*" },
+    negative: { schema: z.string(), mimeType: "text/plain" },
+    handler: ({ response, error, output }) => {
+      if (error) return void response.status(400).send(error.message);
+      if ("filename" in output)
+        fs.createReadStream(output.filename).pipe(
+          response.attachment(output.filename),
+        );
+      else response.status(400).send("Filename is missing");
+    },
+  }),
+);
+```
+
 ## Error handling
 
 All runtime errors are handled by a `ResultHandler`. The default is `defaultResultHandler`. Using `ensureHttpError()`
@@ -914,34 +942,6 @@ createHttpError(500, "Something is broken"); // —> "Internal Server Error"
 createHttpError(501, "We didn't make it yet", { expose: true }); // —> "We didn't make it yet"
 ```
 
-## Non-object response
-
-Thus, you can configure non-object responses too, for example, to send an image file.
-
-You can find two approaches to `EndpointsFactory` and `ResultHandler` implementation
-[in this example](https://github.com/RobinTail/express-zod-api/blob/master/example/factories.ts).
-One of them implements file streaming, in this case the endpoint just has to provide the filename.
-The response schema generally may be just `z.string()`, but I made more specific `ez.file()` that also supports
-`ez.file("binary")` and `ez.file("base64")` variants which are reflected in the
-[generated documentation](#creating-a-documentation).
-
-```typescript
-const fileStreamingEndpointsFactory = new EndpointsFactory(
-  new ResultHandler({
-    positive: { schema: ez.file("buffer"), mimeType: "image/*" },
-    negative: { schema: z.string(), mimeType: "text/plain" },
-    handler: ({ response, error, output }) => {
-      if (error) return void response.status(400).send(error.message);
-      if ("filename" in output)
-        fs.createReadStream(output.filename).pipe(
-          response.type(output.filename),
-        );
-      else response.status(400).send("Filename is missing");
-    },
-  }),
-);
-```
-
 ## HTML Forms (URL encoded)
 
 Use the proprietary schema `ez.form()` with an object shape or a custom `z.object()` with form fields in order to
@@ -957,7 +957,7 @@ export const submitFeedbackEndpoint = defaultEndpointsFactory.build({
   method: "post",
   input: ez.form({
     name: z.string().min(1),
-    email: z.string().email(),
+    email: z.email(),
     message: z.string().min(1),
   }),
 });
@@ -1109,7 +1109,7 @@ new ResultHandler({
   negative: [
     {
       statusCode: 409, // conflict: entity already exists
-      schema: z.object({ status: z.literal("exists"), id: z.number().int() }),
+      schema: z.object({ status: z.literal("exists"), id: z.int() }),
     },
     {
       statusCode: [400, 500], // validation or internal error
@@ -1147,7 +1147,7 @@ const rawAcceptingEndpoint = defaultEndpointsFactory.build({
   input: ez.raw({
     /* the place for additional inputs, like route params, if needed */
   }),
-  output: z.object({ length: z.number().int().nonnegative() }),
+  output: z.object({ length: z.int().nonnegative() }),
   handler: async ({ input: { raw } }) => ({
     length: raw.length, // raw is Buffer
   }),
@@ -1167,6 +1167,7 @@ createConfig({
   gracefulShutdown: {
     timeout: 1000,
     events: ["SIGINT", "SIGTERM"],
+    beforeExit: /* async */ () => {},
   },
 });
 ```
@@ -1185,7 +1186,7 @@ import { EventStreamFactory } from "express-zod-api";
 import { setTimeout } from "node:timers/promises";
 
 const subscriptionEndpoint = new EventStreamFactory({
-  time: z.number().int().positive(),
+  time: z.int().positive(),
 }).buildVoid({
   input: z.object({}), // optional input schema
   handler: async ({ options: { emit, isClosed } }) => {
@@ -1271,7 +1272,11 @@ const exampleEndpoint = defaultEndpointsFactory.build({
   shortDescription: "Retrieves the user.", // <—— this becomes the summary line
   description: "The detailed explanaition on what this endpoint does.",
   input: z.object({
-    id: z.number().describe("the ID of the user").example(123),
+    id: z
+      .string()
+      .example("123") // input examples should be set before transformations
+      .transform(Number)
+      .describe("the ID of the user"),
   }),
   // ..., similarly for output and middlewares
 });