v22 is for Tai

.github/workflows/codeql-analysis.yml

@@ -13,10 +13,10 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ master, v18, v19, v20 ]
+    branches: [ master, v19, v20, v21, make-v22 ]
   pull_request:
     # The branches below must be a subset of the branches above
-    branches: [ master, v18, v19, v20 ]
+    branches: [ master, v19, v20, v21, make-v22 ]
   schedule:
     - cron: '26 8 * * 1'
 

.github/workflows/minor.yml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
       - uses: fregante/setup-git-user@v2
       - run: |
           yarn install

.github/workflows/node.js.yml

@@ -5,17 +5,17 @@ name: Node.js CI
 
 on:
   push:
-    branches: [ master, v18, v19, v20 ]
+    branches: [ master, v19, v20, v21, make-v22 ]
   pull_request:
-    branches: [ master, v18, v19, v20 ]
+    branches: [ master, v19, v20, v21, make-v22 ]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        node-version: [18.18.0, 18.x, 20.9.0, 20.x, 22.0.0, 22.x]
+        node-version: [20.9.0, 20.x, 22.0.0, 22.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
     steps:
     - name: Get yarn cache dir

.github/workflows/npm-publish.yml

@@ -23,7 +23,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
           registry-url: https://registry.npmjs.org/
       - run: yarn install
       - run: npm publish --provenance --tag ${{ inputs.tag }}

.github/workflows/patch.yml

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 18
+          node-version: 20
       - uses: fregante/setup-git-user@v2
       - run: |
           yarn install

.github/workflows/swagger.yml

@@ -2,9 +2,9 @@ name: OpenAPI Validation
 
 on:
   push:
-    branches: [ master, v18, v19, v20 ]
+    branches: [ master, v19, v20, v21, make-v22 ]
   pull_request:
-    branches: [ master, v18, v19, v20 ]
+    branches: [ master, v19, v20, v21, make-v22 ]
 
 
 jobs:

CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## Version 22
+
+### v22.0.0
+
+- Minimum supported Node versions: 20.9.0 and 22.0.0:
+  - Node 18 is no longer supported, its end of life is April 30, 2025.
+- `BuiltinLogger::profile()` behavior changed for picoseconds: expressing them through nanoseconds;
+- The `splitResponse` property on the `Integration::constructor()` argument is removed;
+- Changes to the client code generated by `Integration`:
+  - The class name changed from `ExpressZodAPIClient` to just `Client`;
+  - The overload of the `Client::provide()` having 3 arguments and the `Provider` type are removed;
+  - The public `jsonEndpoints` const is removed — use the `content-type` header of an actual response instead;
+  - The public type `MethodPath` is removed — use the `Request` type instead.
+- The approach on tagging endpoints changed:
+  - The `tags` property moved from the argument of `createConfig()` to `Documentation::constructor()`;
+  - The overload of `EndpointsFactory::constructor()` accepting `config` property is removed;
+  - The argument of `EventStreamFactory::constructor()` is now the events map (formerly assigned to `events` property);
+  - Tags should be declared as the keys of the augmented interface `TagOverrides` instead;
+- Consider the automated migration using the built-in ESLint rule.
+
+```js
+// eslint.config.mjs — minimal ESLint 9 config to apply migrations automatically using "eslint --fix"
+import parser from "@typescript-eslint/parser";
+import migration from "express-zod-api/migration";
+
+export default [
+  { languageOptions: { parser }, plugins: { migration } },
+  { files: ["**/*.ts"], rules: { "migration/v22": "error" } },
+];
+```
+
+```diff
+  createConfig({
+-   tags: {},
+  });
+
+  new Documentation({
++   tags: {},
+  });
+
+  new EndpointsFactory(
+-   { config, resultHandler: new ResultHandler() }
++   new ResultHandler()
+  );
+
+  new EventStreamFactory(
+-   { config, events: {} }
++   {} // events map only
+  );
+```
+
+```ts
+// new tagging approach
+import { defaultEndpointsFactory, Documentation } from "express-zod-api";
+
+// Add similar declaration once, somewhere in your code, preferably near config
+declare module "express-zod-api" {
+  interface TagOverrides {
+    users: unknown;
+    files: unknown;
+    subscriptions: unknown;
+  }
+}
+
+// Add extended description of the tags to Documentation (optional)
+new Documentation({
+  tags: {
+    users: "All about users",
+    files: { description: "All about files", url: "https://example.com" },
+  },
+});
+```
+
 ## Version 21
 
 ### v21.11.1

README.md

@@ -1206,7 +1206,7 @@ import { EventStreamFactory } from "express-zod-api";
 import { setTimeout } from "node:timers/promises";
 
 const subscriptionEndpoint = EventStreamFactory({
-  events: { time: z.number().int().positive() },
+  time: z.number().int().positive(),
 }).buildVoid({
   input: z.object({}), // optional input schema
   handler: async ({ options: { emit, isClosed } }) => {
@@ -1264,9 +1264,9 @@ Consuming the generated client requires Typescript version 4.1 or higher.
 
 ```typescript
 // example frontend, simple implementation based on fetch()
-import { ExpressZodAPIClient } from "./client.ts"; // the generated file
+import { Client } from "./client.ts"; // the generated file
 
-const client = new ExpressZodAPIClient(async (method, path, params) => {
+const client = new Client(async (method, path, params) => {
   const hasBody = !["get", "delete"].includes(method);
   const searchParams = hasBody ? "" : `?${new URLSearchParams(params)}`;
   const response = await fetch(`https://example.com${path}${searchParams}`, {
@@ -1322,36 +1322,33 @@ _See the example of the generated documentation
 
 ## Tagging the endpoints
 
-When generating documentation, you may find it necessary to classify endpoints into groups. For this, the
-possibility of tagging endpoints is provided. In order to achieve the consistency of tags across all endpoints, the
-possible tags should be declared in the configuration first and another instantiation approach of the
-`EndpointsFactory` is required. Consider the following example:
+When generating documentation, you may find it necessary to classify endpoints into groups. The possibility of tagging
+endpoints is available for that purpose. In order to establish the constraints on tags across all the endpoints, they
+should be declared as keys of `TagOverrides` interface. Consider the following example:
 
 ```typescript
-import {
-  createConfig,
-  EndpointsFactory,
-  defaultResultHandler,
-} from "express-zod-api";
+import { defaultEndpointsFactory, Documentation } from "express-zod-api";
 
-const config = createConfig({
-  tags: {
-    users: "Everything about the users", // or advanced syntax:
-    files: {
-      description: "Everything about the files processing",
-      url: "https://example.com",
-    },
-  },
-});
+// Add similar declaration once, somewhere in your code, preferably near config
+declare module "express-zod-api" {
+  interface TagOverrides {
+    users: unknown;
+    files: unknown;
+    subscriptions: unknown;
+  }
+}
 
-// instead of defaultEndpointsFactory use the following approach:
-const taggedEndpointsFactory = new EndpointsFactory({
-  resultHandler: defaultResultHandler, // or use your custom one
-  config, // <—— supply your config here
+// Use the declared tags for endpoints
+const exampleEndpoint = defaultEndpointsFactory.build({
+  tag: "users", // or array ["users", "files"]
 });
 
-const exampleEndpoint = taggedEndpointsFactory.build({
-  tag: "users", // or array ["users", "files"]
+// Add extended description of the tags to Documentation (optional)
+new Documentation({
+  tags: {
+    users: "All about users",
+    files: { description: "All about files", url: "https://example.com" },
+  },
 });
 ```
 

SECURITY.md

@@ -4,6 +4,7 @@
 
 | Version | Release |     Supported      |
 | ------: | :------ | :----------------: |
+|  22.x.x | 02.2025 | :white_check_mark: |
 |  21.x.x | 11.2024 | :white_check_mark: |
 |  20.x.x | 06.2024 | :white_check_mark: |
 |  19.x.x | 05.2024 | :white_check_mark: |

eslint.config.js

@@ -60,7 +60,7 @@ const tsFactoryConcerns = [
     message: "use makeType() or makePublicLiteralType() helpers",
   },
   {
-    selector: "Identifier[name='createVariableDeclarationList']",
+    selector: "Identifier[name='createVariableStatement']",
     message: "use makeConst() helper",
   },
   {
@@ -73,7 +73,7 @@ const tsFactoryConcerns = [
   },
   {
     selector: "Identifier[name='createConstructorDeclaration']",
-    message: "use makeEmptyInitializingConstructor() helper",
+    message: "use makePublicConstructor() helper",
   },
   {
     selector: "Identifier[name='createParameterDeclaration']",
@@ -86,16 +86,25 @@ const tsFactoryConcerns = [
     message: "use makePropCall() helper",
   },
   {
-    selector: "Identifier[name='AmpersandAmpersandToken']",
-    message: "use makeAnd() helper",
+    selector: "Identifier[name='KeyOfKeyword']",
+    message: "use makeKeyOf() helper",
   },
   {
-    selector: "Identifier[name='EqualsEqualsEqualsToken']",
-    message: "use makeEqual() helper",
+    selector: "Identifier[name='createTemplateExpression']",
+    message: "use makeTemplate() helper",
   },
   {
-    selector: "Identifier[name='KeyOfKeyword']",
-    message: "use makeKeyOf() helper",
+    selector: "Identifier[name='createNewExpression']",
+    message: "use makeNew() helper",
+  },
+  {
+    selector: "Literal[value='Promise']",
+    message: "use makePromise() helper",
+  },
+  {
+    selector:
+      "CallExpression[callee.property.name='createTypeReferenceNode'][arguments.length=1]",
+    message: "use ensureTypeNode() helper",
   },
 ];
 
@@ -143,7 +152,7 @@ export default tsPlugin.config(
   },
   {
     name: "source/integration",
-    files: ["src/integration.ts"],
+    files: ["src/integration.ts", "src/integration-base.ts", "src/zts.ts"],
     rules: {
       "no-restricted-syntax": [
         "warn",

example/config.ts

@@ -19,11 +19,6 @@ export const config = createConfig({
     app.use("/docs", ui.serve, ui.setup(documentation));
   },
   cors: true,
-  tags: {
-    users: "Everything about the users",
-    files: "Everything about the files processing",
-    subscriptions: "Everything about the subscriptions",
-  },
 });
 
 // Uncomment these lines when using a custom logger, for example winston:
@@ -39,3 +34,14 @@ declare module "express-zod-api" {
   interface LoggerOverrides extends BuiltinLogger {}
 }
 */
+
+// Uncomment these lines for introducing constraints on tags
+/*
+declare module "express-zod-api" {
+  interface TagOverrides {
+    users: unknown;
+    files: unknown;
+    subscriptions: unknown;
+  }
+}
+*/

example/endpoints/accept-raw.ts

@@ -1,8 +1,7 @@
 import { z } from "zod";
-import { ez } from "../../src";
-import { taggedEndpointsFactory } from "../factories";
+import { defaultEndpointsFactory, ez } from "../../src";
 
-export const rawAcceptingEndpoint = taggedEndpointsFactory.build({
+export const rawAcceptingEndpoint = defaultEndpointsFactory.build({
   method: "post",
   tag: "files",
   input: ez.raw({

example/endpoints/retrieve-user.ts

@@ -1,7 +1,7 @@
 import createHttpError from "http-errors";
 import assert from "node:assert/strict";
 import { z } from "zod";
-import { taggedEndpointsFactory } from "../factories";
+import { defaultEndpointsFactory } from "../../src";
 import { methodProviderMiddleware } from "../middlewares";
 
 // Demonstrating circular schemas using z.lazy()
@@ -15,7 +15,7 @@ const feature: z.ZodType<Feature> = baseFeature.extend({
   features: z.lazy(() => feature.array()),
 });
 
-export const retrieveUserEndpoint = taggedEndpointsFactory
+export const retrieveUserEndpoint = defaultEndpointsFactory
   .addMiddleware(methodProviderMiddleware)
   .build({
     tag: "users",

example/endpoints/upload-avatar.ts

@@ -1,9 +1,8 @@
 import { z } from "zod";
-import { ez } from "../../src";
+import { defaultEndpointsFactory, ez } from "../../src";
 import { createHash } from "node:crypto";
-import { taggedEndpointsFactory } from "../factories";
 
-export const uploadAvatarEndpoint = taggedEndpointsFactory.build({
+export const uploadAvatarEndpoint = defaultEndpointsFactory.build({
   method: "post",
   tag: "files",
   description: "Handles a file upload.",