express-zod-api 21.0.0-beta.3 → 21.0.0-beta.5

package/CHANGELOG.md

@@ -5,28 +5,25 @@
 ### v21.0.0
 
 - Minimum supported versions of `express`: 4.21.1 and 5.0.1 (fixed vulnerabilities);
-- Running HTTP server made optional (can now configure HTTPS only):
-  - Object argument of the `createConfig()` method changed:
-    - The `server` property renamed to `http` and made optional;
-    - Its nested properties moved to the top level of the config object:
-      `jsonParser`, `upload`, `compression`, `rawParser` and `beforeRouting`.
-  - The object resolved from the `createServer()` method changed:
-    - Properties `httpServer` and `httpsServer` are removed;
-    - Added `servers` property instead — array containing those server instances in the same order.
-- The `serializer` property of `Documentation` and `Integration` constructor argument removed;
-- The `originalError` property of `InputValidationError` and `OutputValidationError` removed (use `cause` instead);
-- The `getStatusCodeFromError()` method removed (use the `ensureHttpError().statusCode` instead);
-- Both `logger` and `getChildLogger` properties of `beforeRouting` argument are replaced with all-purpose `getLogger`:
-  - It returns the child logger for the given request (if configured) or the configured logger otherwise.
-- Specifying `method` or `methods` for `EndpointsFactory::build()` made optional and when it's omitted:
-  - If the endpoint is assigned to a route using `DependsOnMethod` instance, the corresponding method is used;
-  - Otherwise `GET` method is implied by default.
-- Other potentially breaking changes:
-  - The optional property `methods` of `EndpointsFactory::build()` must be non-empty array when used;
-  - The `Endpoint::getMethods()` method may now return `undefined`;
+- Breaking changes to `createConfig()` argument:
+  - The `server` property renamed to `http` and made optional — (can now configure HTTPS only);
+  - These properties moved to the top level: `jsonParser`, `upload`, `compression`, `rawParser` and `beforeRouting`;
+  - Both `logger` and `getChildLogger` arguments of `beforeRouting` function are replaced with all-purpose `getLogger`.
+- Breaking changes to `createServer()` resolved return:
+  - Both `httpServer` and `httpsServer` are combined into single `servers` property (array, same order).
+- Breaking changes to `EndpointsFactory::build()` argument:
+  - Plural `methods`, `tags` and `scopes` properties replaced with singular `method`, `tag`, `scope` accordingly;
+  - The `method` property also made optional and can now be derived from `DependsOnMethod` or imply `GET` by default;
+  - When `method` is assigned with an array, it must be non-empty.
+- Breaking changes to `positive` and `negative` propeties of `ResultHandler` constructor argument:
+  - Plural `statusCodes` and `mimeTypes` props within the values are replaced with singular `statusCode` and `mimeType`.
+- Other breaking changes:
+  - The `serializer` property of `Documentation` and `Integration` constructor argument removed;
+  - The `originalError` property of `InputValidationError` and `OutputValidationError` removed (use `cause` instead);
+  - The `getStatusCodeFromError()` method removed (use the `ensureHttpError().statusCode` instead);
   - The `testEndpoint()` method can no longer test CORS headers — that function moved to `Routing` traverse;
+  - For `Endpoint`: `getMethods()` may return `undefined`, `getMimeTypes()` removed, `getSchema()` variants reduced;
   - Public properties `pairs`, `firstEndpoint` and `siblingMethods` of `DependsOnMethod` replaced with `entries`.
-- Routing traverse improvement: performance +5%, memory consumption -17%.
 - Consider the automated migration using the built-in ESLint rule.
 
 ```js
@@ -40,8 +37,71 @@ export default [
 ];
 ```
 
+```ts
+// The sample of new structure
+const config = createConfig({
+  http: { listen: 80 }, // became optional
+  https: { listen: 443, options: {} },
+  upload: true,
+  compression: true,
+  beforeRouting: ({ app, getLogger }) => {
+    const logger = getLogger();
+    app.use((req, res, next) => {
+      const childLogger = getLogger(req);
+    });
+  },
+});
+const { servers } = await createServer(config, {});
+```
+
 ## Version 20
 
+### v20.22.0
+
+- Featuring a helper to describe nested Routing for already assigned routes:
+  - Suppose you want to describe `Routing` for both `/v1/path` and `/v1/path/subpath` routes having Endpoints attached;
+  - Previously, an empty path segment was proposed for that purpose, but there is more elegant and readable way now;
+  - The `.nest()` method is available both on `Endpoint` and `DependsOnMethod` instances:
+
+```ts
+import { Routing } from "express-zod-api";
+
+// Describing routes /v1/path and /v1/path/subpath both having endpoints assigned:
+const before: Routing = {
+  v1: {
+    path: {
+      "": endpointA,
+      subpath: endpointB,
+    },
+  },
+};
+
+const after: Routing = {
+  v1: {
+    path: endpointA.nest({
+      subpath: endpointB,
+    }),
+  },
+};
+```
+
+### v20.21.2
+
+- Fixed the example implementation in the generated client for endpoints using path params:
+  - The choice of parser was made based on the exported `const jsonEndpoints` indexed by `path`;
+  - The actual `path` used for the lookup already contained parameter substitutions so that JSON parser didn't work;
+  - The new example implementation suggests choosing the parser based on the actual `response.headers`;
+  - The issue was found and reported by [@HenriJ](https://github.com/HenriJ).
+
+```diff
+- const parser = `${method} ${path}` in jsonEndpoints ? "json" : "text";
++ const isJSON = response.headers
++   .get("content-type")
++   ?.startsWith("application/json");
+- return response[parser]();
++ return response[isJSON ? "json" : "text"]();
+```
+
 ### v20.21.1
 
 - Performance tuning: `Routing` traverse made about 12 times faster.

package/README.md

@@ -32,17 +32,18 @@ Start your API server with I/O schema validation and custom middlewares in minut
    13. [Enabling compression](#enabling-compression)
 5. [Advanced features](#advanced-features)
    1. [Customizing input sources](#customizing-input-sources)
-   2. [Route path params](#route-path-params)
-   3. [Multiple schemas for one route](#multiple-schemas-for-one-route)
-   4. [Response customization](#response-customization)
-   5. [Error handling](#error-handling)
-   6. [Production mode](#production-mode)
-   7. [Non-object response](#non-object-response) including file downloads
-   8. [File uploads](#file-uploads)
-   9. [Serving static files](#serving-static-files)
-   10. [Connect to your own express app](#connect-to-your-own-express-app)
-   11. [Testing endpoints](#testing-endpoints)
-   12. [Testing middlewares](#testing-middlewares)
+   2. [Nested routes](#nested-routes)
+   3. [Route path params](#route-path-params)
+   4. [Multiple schemas for one route](#multiple-schemas-for-one-route)
+   5. [Response customization](#response-customization)
+   6. [Error handling](#error-handling)
+   7. [Production mode](#production-mode)
+   8. [Non-object response](#non-object-response) including file downloads
+   9. [File uploads](#file-uploads)
+   10. [Serving static files](#serving-static-files)
+   11. [Connect to your own express app](#connect-to-your-own-express-app)
+   12. [Testing endpoints](#testing-endpoints)
+   13. [Testing middlewares](#testing-middlewares)
 6. [Special needs](#special-needs)
    1. [Different responses for different status codes](#different-responses-for-different-status-codes)
    2. [Array response](#array-response) for migrating legacy APIs
@@ -84,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/HenriJ.png" alt="@HenriJ" width="50px" />](https://github.com/HenriJ)
 [<img src="https://github.com/JonParton.png" alt="@JonParton" width="50px" />](https://github.com/JonParton)
 [<img src="https://github.com/williamgcampbell.png" alt="@williamgcampbell" width="50px" />](https://github.com/williamgcampbell)
 [<img src="https://github.com/t1nky.png" alt="@t1nky" width="50px" />](https://github.com/t1nky)
@@ -206,7 +208,7 @@ The endpoint responds with "Hello, World" or "Hello, {name}" if the name is supp
 import { z } from "zod";
 
 const helloWorldEndpoint = defaultEndpointsFactory.build({
-  // method: "get" (default) or methods: ["get", "post", ...]
+  // method: "get" (default) or array ["get", "post", ...]
   input: z.object({
     name: z.string().optional(),
   }),
@@ -286,12 +288,9 @@ const authMiddleware = new Middleware({
   handler: async ({ input: { key }, request, logger }) => {
     logger.debug("Checking the key and token");
     const user = await db.Users.findOne({ key });
-    if (!user) {
-      throw createHttpError(401, "Invalid key");
-    }
-    if (request.headers.token !== user.token) {
+    if (!user) throw createHttpError(401, "Invalid key");
+    if (request.headers.token !== user.token)
       throw createHttpError(401, "Invalid token");
-    }
     return { user }; // provides endpoints with options.user
   },
 });
@@ -303,10 +302,9 @@ By using `.addMiddleware()` method before `.build()` you can connect it to the e
 const yourEndpoint = defaultEndpointsFactory
   .addMiddleware(authMiddleware)
   .build({
-    // ...,
-    handler: async ({ options }) => {
-      // options.user is the user returned by authMiddleware
-    },
+    handler: async ({ options: { user } }) => {
+      // user is the one returned by authMiddleware
+    }, // ...
   });
 ```
 
@@ -320,7 +318,7 @@ import { defaultEndpointsFactory } from "express-zod-api";
 const factory = defaultEndpointsFactory
   .addMiddleware(authMiddleware) // add Middleware instance or use shorter syntax:
   .addMiddleware({
-    handler: async ({ options: { user } }) => ({}), // options.user from authMiddleware
+    handler: async ({ options: { user } }) => ({}), // user from authMiddleware
   });
 ```
 
@@ -534,18 +532,14 @@ const updateUserEndpoint = defaultEndpointsFactory.build({
   method: "post",
   input: z.object({
     userId: z.string(),
-    birthday: ez.dateIn(), // string -> Date
+    birthday: ez.dateIn(), // string -> Date in handler
   }),
   output: z.object({
-    createdAt: ez.dateOut(), // Date -> string
+    createdAt: ez.dateOut(), // Date -> string in response
+  }),
+  handler: async ({ input }) => ({
+    createdAt: new Date("2022-01-22"), // 2022-01-22T00:00:00.000Z
   }),
-  handler: async ({ input }) => {
-    // input.birthday is Date
-    return {
-      // transmitted as "2022-01-22T00:00:00.000Z"
-      createdAt: new Date("2022-01-22"),
-    };
-  },
 });
 ```
 
@@ -563,7 +557,6 @@ That function has several parameters and can be asynchronous.
 import { createConfig } from "express-zod-api";
 
 const config = createConfig({
-  // ... other options
   cors: ({ defaultHeaders, request, endpoint, logger }) => ({
     ...defaultHeaders,
     "Access-Control-Max-Age": "5000",
@@ -589,8 +582,7 @@ const config = createConfig({
       key: fs.readFileSync("privkey.pem", "utf-8"),
     },
     listen: 443, // port, UNIX socket or options
-  },
-  // ... cors, logger, etc
+  }, // ... cors, logger, etc
 });
 
 // 'await' is only needed if you're going to use the returned entities.
@@ -717,14 +709,13 @@ In order to receive a compressed response the client should include the followin
 
 You can customize the list of `request` properties that are combined into `input` that is being validated and available
 to your endpoints and middlewares. The order here matters: each next item in the array has a higher priority than its
-previous sibling.
+previous sibling. The following arrangement is default:
 
 ```typescript
 import { createConfig } from "express-zod-api";
 
 createConfig({
   inputSources: {
-    // the defaults are:
     get: ["query", "params"],
     post: ["body", "params", "files"],
     put: ["body", "params"],
@@ -734,21 +725,32 @@ createConfig({
 });
 ```
 
+## Nested routes
+
+Suppose you want to assign both `/v1/path` and `/v1/path/subpath` routes with Endpoints:
+
+```typescript
+import { Routing } from "express-zod-api";
+
+const routing: Routing = {
+  v1: {
+    path: endpointA.nest({
+      subpath: endpointB,
+    }),
+  },
+};
+```
+
 ## Route path params
 
-You can describe the route of the endpoint using parameters:
+You can assign your Endpoint to a route like `/v1/user/:id` where `:id` is the path parameter:
 
 ```typescript
 import { Routing } from "express-zod-api";
 
 const routing: Routing = {
   v1: {
-    user: {
-      // route path /v1/user/:id, where :id is the path param
-      ":id": getUserEndpoint,
-      // use the empty string to represent /v1/user if needed:
-      // "": listAllUsersEndpoint,
-    },
+    user: { ":id": getUserEndpoint },
   },
 };
 ```
@@ -763,12 +765,8 @@ const getUserEndpoint = endpointsFactory.build({
     // other inputs (in query):
     withExtendedInformation: z.boolean().optional(),
   }),
-  output: z.object({
-    /* ... */
-  }),
-  handler: async ({ input: { id } }) => {
-    // id is the route path param, number
-  },
+  output: z.object({}),
+  handler: async ({ input: { id } }) => ({}), // id is number,
 });
 ```
 
@@ -821,7 +819,7 @@ import {
 const yourResultHandler = new ResultHandler({
   positive: (data) => ({
     schema: z.object({ data }),
-    mimeType: "application/json", // optinal, or mimeTypes for array
+    mimeType: "application/json", // optinal or array
   }),
   negative: z.object({ error: z.string() }),
   handler: ({ error, input, output, request, response, logger }) => {
@@ -904,17 +902,12 @@ const fileStreamingEndpointsFactory = new EndpointsFactory(
     positive: { schema: ez.file("buffer"), mimeType: "image/*" },
     negative: { schema: z.string(), mimeType: "text/plain" },
     handler: ({ response, error, output }) => {
-      if (error) {
-        response.status(400).send(error.message);
-        return;
-      }
-      if ("filename" in 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");
-      }
+      else response.status(400).send("Filename is missing");
     },
   }),
 );
@@ -948,9 +941,7 @@ const config = createConfig({
     limits: { fileSize: 51200 }, // 50 KB
     limitError: createHttpError(413, "The file is too large"), // handled by errorHandler in config
     beforeUpload: ({ request, logger }) => {
-      if (!canUpload(request)) {
-        throw createHttpError(403, "Not authorized");
-      }
+      if (!canUpload(request)) throw createHttpError(403, "Not authorized");
     },
   },
 });
@@ -1094,7 +1085,7 @@ import { ResultHandler } from "express-zod-api";
 
 new ResultHandler({
   positive: (data) => ({
-    statusCodes: [201, 202], // created or will be created
+    statusCode: [201, 202], // created or will be created
     schema: z.object({ status: z.literal("created"), data }),
   }),
   negative: [
@@ -1103,7 +1094,7 @@ new ResultHandler({
       schema: z.object({ status: z.literal("exists"), id: z.number().int() }),
     },
     {
-      statusCodes: [400, 500], // validation or internal error
+      statusCode: [400, 500], // validation or internal error
       schema: z.object({ status: z.literal("error"), reason: z.string() }),
     },
   ],
@@ -1283,9 +1274,7 @@ const exampleEndpoint = defaultEndpointsFactory.build({
     .object({
       id: z.number().describe("the ID of the user"),
     })
-    .example({
-      id: 123,
-    }),
+    .example({ id: 123 }),
   // ..., similarly for output and middlewares
 });
 ```
@@ -1308,9 +1297,8 @@ import {
 } from "express-zod-api";
 
 const config = createConfig({
-  // ..., use the simple or the advanced syntax:
   tags: {
-    users: "Everything about the users",
+    users: "Everything about the users", // or advanced syntax:
     files: {
       description: "Everything about the files processing",
       url: "https://example.com",
@@ -1325,8 +1313,7 @@ const taggedEndpointsFactory = new EndpointsFactory({
 });
 
 const exampleEndpoint = taggedEndpointsFactory.build({
-  // ...
-  tag: "users", // or tags: ["users", "files"]
+  tag: "users", // or array ["users", "files"]
 });
 ```
 
@@ -1364,12 +1351,10 @@ const ruleForClient: Producer = (
 ) => ts.factory.createKeywordTypeNode(ts.SyntaxKind.BooleanKeyword);
 
 new Documentation({
-  /* config, routing, title, version */
   brandHandling: { [myBrand]: ruleForDocs },
 });
 
 new Integration({
-  /* routing */
   brandHandling: { [myBrand]: ruleForClient },
 });
 ```
@@ -1404,7 +1389,7 @@ const output = z.object({
 });
 
 endpointsFactory.build({
-  methods,
+  method,
   input,
   output,
   handler: async (): Promise<z.input<typeof output>> => ({