express-zod-api 21.0.0-beta.4 → 21.0.0-beta.6

package/CHANGELOG.md

@@ -21,8 +21,8 @@
   - 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 `Endpoint::getMethods()` method may now return `undefined`;
   - 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`.
 - Consider the automated migration using the built-in ESLint rule.
 
@@ -56,6 +56,41 @@ const { servers } = await createServer(config, {});
 
 ## Version 20
 
+### v20.22.1
+
+- Avoids startup logo distortion when the terminal is too narrow;
+- Self-diagnosis for potential problems disabled in production mode to ensure faster startup:
+  - Warning about potentially unserializable schema for JSON operating endpoints was introduced in v20.15.0.
+
+### 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:

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
@@ -287,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
   },
 });
@@ -304,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
+    }, // ...
   });
 ```
 
@@ -321,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
   });
 ```
 
@@ -535,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"),
-    };
-  },
 });
 ```
 
@@ -564,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",
@@ -590,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.
@@ -718,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"],
@@ -735,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 },
   },
 };
 ```
@@ -764,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,
 });
 ```
 
@@ -873,6 +870,7 @@ origins of errors that could happen in runtime and be handled the following way:
 Consider enabling production mode by setting `NODE_ENV` environment variable to `production` for your deployment:
 
 - Express activates some [performance optimizations](https://expressjs.com/en/advanced/best-practice-performance.html);
+- Self-diagnosis for potential problems is disabled to ensure faster startup;
 - The `defaultResultHandler`, `defaultEndpointsFactory` and `LastResortHandler` generalize server-side error messages
   in negative responses in order to improve the security of your API by not disclosing the exact causes of errors:
   - Throwing errors that have or imply `5XX` status codes become just `Internal Server Error` message in response;
@@ -905,17 +903,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");
     },
   }),
 );
@@ -949,9 +942,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");
     },
   },
 });
@@ -1284,9 +1275,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
 });
 ```
@@ -1309,9 +1298,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",
@@ -1326,7 +1314,6 @@ const taggedEndpointsFactory = new EndpointsFactory({
 });
 
 const exampleEndpoint = taggedEndpointsFactory.build({
-  // ...
   tag: "users", // or array ["users", "files"]
 });
 ```
@@ -1365,12 +1352,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 },
 });
 ```