v28 is for Koko Da Doll

.github/workflows/codeql-analysis.yml

@@ -13,10 +13,10 @@ name: "CodeQL"
 
 on:
   push:
-    branches: [ master, v23, v24, v25, v26 ]
+    branches: [ master, v24, v25, v26, v27, make-v28 ]
   pull_request:
     # The branches below must be a subset of the branches above
-    branches: [ master, v23, v24, v25, v26 ]
+    branches: [ master, v24, v25, v26, v27, make-v28 ]
   schedule:
     - cron: '26 8 * * 1'
 

.github/workflows/headers.yml

@@ -6,7 +6,7 @@ on:
     - cron: "0 0 * * 0" # Runs every Sunday at midnight UTC
 
 permissions:
-  contents: write  # Grants write access to push changes
+  contents: write # Grants write access to push changes
   pull-requests: write # and create PRs
 
 jobs:
@@ -31,7 +31,7 @@ jobs:
         run: pnpm install
 
       - name: Check for new headers on IANA.ORG
-        run: pnpm unrun tools/headers.ts
+        run: pnpm node tools/headers.ts
 
       - name: Check for changes
         id: git-state

.github/workflows/node.js.yml

@@ -5,17 +5,17 @@ name: Node.js CI
 
 on:
   push:
-    branches: [ master, v23, v24, v25, v26 ]
+    branches: [ master, v24, v25, v26, v27, make-v28 ]
   pull_request:
-    branches: [ master, v23, v24, v25, v26 ]
+    branches: [ master, v24, v25, v26, v27, make-v28 ]
 
 jobs:
   build:
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false
       matrix:
-        node-version: [20.19.0, 20.x, 22.12.0, 22.x, 24.0.0, 24.x]
+        node-version: [22.19.0, 22.x, 24.0.0, 24.x]
         # See supported Node.js release schedule at https://nodejs.org/en/about/releases/
     steps:
     - name: Checkout

CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## Version 28
+
+### v28.0.0
+
+- Supported Node.js versions: `^22.19.0 || ^24.0.0`;
+- Breaking changes to the `createConfig()` argument (object):
+  - property `wrongMethodBehavior` (number) changed to `hintAllowedMethods` (boolean);
+  - property `methodLikeRouteBehavior` (string literal) changed to `recognizeMethodDependentRoutes` (boolean);
+- Breaking change to the `Documentation` constructor argument (object):
+  - property `hasSummaryFromDescription` renamed to `hasSummary`;
+- Breaking change to the `Integration` constructor argument (object):
+  - property `noContent` renamed to `noBodySchema`;
+- Consider using [the automated migration](https://www.npmjs.com/package/@express-zod-api/migration).
+
+```diff
+  createConfig({
+-   wrongMethodBehavior: 404,
++   hintAllowedMethods: false,
+-   methodLikeRouteBehavior: "path",
++   recognizeMethodDependentRoutes: false,
+  });
+```
+
+```diff
+  new Documentation({
+-   hasSummaryFromDescription: false,
++   hasSummary: false,
+  });
+```
+
+```diff
+  new Integration({
+-   noContent: z.undefined(),
++   noBodySchema: z.undefined(),
+  });
+```
+
 ## Version 27
 
 ### v27.2.0

README.md

@@ -243,7 +243,7 @@ const helloWorldEndpoint = defaultEndpointsFactory.build({
 Connect your endpoint to the `/v1/hello` route:
 
 ```ts
-import { Routing } from "express-zod-api";
+import type { Routing } from "express-zod-api";
 
 const routing: Routing = {
   v1: {
@@ -920,7 +920,7 @@ it normalizes errors into consistent HTTP responses with sensible status codes.
 - Routing, parsing and upload issues:
   - Handled by `ResultHandler` configured as `errorHandler` (the defaults is `defaultResultHandler`);
   - Parsing errors: passed through as-is (typically `HttpError` with `4XX` code used for response by default);
-  - Routing errors: `404` or `405`, based on `wrongMethodBehavior` configuration;
+  - Routing errors: `404` or `405`, based on `hintAllowedMethods` configuration;
   - Upload issues: thrown only if `upload.limitError` is configured (`HttpError::statusCode` can be used for response);
   - For other errors the default status code is `500`;
 - `ResultHandler` failures:
@@ -1218,7 +1218,7 @@ purpose, the `.deprecated()` method is available on each schema and `Endpoint`,
 You can also deprecate all routes the `Endpoint` assigned to by setting `EndpointsFactory::build({ deprecated: true })`.
 
 ```ts
-import { Routing } from "express-zod-api";
+import type { Routing } from "express-zod-api";
 import { z } from "zod";
 
 const someEndpoint = factory.build({

SECURITY.md

@@ -4,6 +4,7 @@
 
 | Version | Code name     | Release |     Supported      |
 | ------: | :------------ | :------ | :----------------: |
+|  28.x.x | Koko          | 04.2026 | :white_check_mark: |
 |  27.x.x | Nikki         | 02.2026 | :white_check_mark: |
 |  26.x.x | Lia           | 12.2025 | :white_check_mark: |
 |  25.x.x | Sara          | 08.2025 | :white_check_mark: |

cjs-test/tsconfig.json

@@ -1,4 +1,4 @@
 {
-  "extends": "@tsconfig/node20/tsconfig.json",
+  "extends": "@tsconfig/node22/tsconfig.json",
   "include": ["quick-start.ts"]
 }

compat-test/eslint.config.js

@@ -3,5 +3,5 @@ import migration from "@express-zod-api/migration";
 
 export default [
   { languageOptions: { parser }, plugins: { migration } },
-  { files: ["**/*.ts"], rules: { "migration/v27": "error" } },
+  { files: ["**/*.ts"], rules: { "migration/v28": "error" } },
 ];

compat-test/migration.spec.ts

@@ -2,10 +2,8 @@ import { readFile } from "node:fs/promises";
 import { describe, test, expect } from "vitest";
 
 describe("Migration", () => {
-  test("should fix the import", async () => {
+  test("should migrate", async () => {
     const fixed = await readFile("./sample.ts", "utf-8");
-    expect(fixed).toBe(
-      `import typescript from "typescript";\n\nnew Integration({ typescript, routing });\n`,
-    );
+    expect(fixed.split("\n")[0]).toBe(`createConfig({ hintAllowedMethods: false });`);
   });
 });

compat-test/package.json

@@ -3,18 +3,18 @@
   "type": "module",
   "private": true,
   "scripts": {
-    "pretest": "echo 'new Integration({ routing });' > sample.ts",
+    "pretest": "echo 'createConfig({ wrongMethodBehavior: 404 });' > sample.ts",
     "test": "eslint --fix && vitest --run",
     "posttest": "rm sample.ts"
   },
   "devDependencies": {
     "@express-zod-api/migration": "workspace:*",
-    "eslint": "npm:eslint@9.0.0",
+    "eslint": "npm:eslint@10.0.0",
     "express": "npm:express@5.1.0",
     "express-zod-api": "workspace:*",
     "http-errors": "npm:http-errors@2.0.1",
     "typescript": "npm:typescript@5.1.3",
-    "typescript-eslint": "npm:typescript-eslint@8.0.0",
+    "typescript-eslint": "npm:typescript-eslint@8.58.0",
     "zod": "npm:zod@4.1.13"
   }
 }

compat-test/quick-start.spec.ts

@@ -8,14 +8,14 @@ import {
   expect,
   test,
 } from "vitest";
-import { givePort } from "../tools/ports";
+import { givePort } from "../tools/ports.ts";
 
 describe("ESM Test", async () => {
   let out = "";
   const listener = (chunk: Buffer) => {
     out += chunk.toString();
   };
-  const quickStart = spawn("unrun", ["quick-start.ts"]);
+  const quickStart = spawn("node", ["quick-start.ts"]);
   quickStart.stdout.on("data", listener);
   quickStart.stderr.on("data", listener);
   await vi.waitFor(() => assert(out.includes(`Listening`)), { timeout: 1e4 });

eslint.config.js

@@ -195,7 +195,7 @@ export default tsPlugin.config(
   prettierRules,
   {
     name: "globally/ignored",
-    ignores: ["**/dist/", "**/coverage/", "compat-test/sample.ts"],
+    ignores: ["**/dist/", "**/coverage/", "compat-test"],
   },
   {
     name: "globally/disabled",
@@ -210,6 +210,7 @@ export default tsPlugin.config(
       curly: ["warn", "multi-or-nest", "consistent"],
       "@typescript-eslint/no-shadow": "warn",
       "no-restricted-syntax": ["warn", ...importConcerns],
+      "no-duplicate-imports": "warn",
     },
   },
   {
@@ -274,6 +275,7 @@ export default tsPlugin.config(
     files: ["*-test/quick-start.ts", "example/example.client.ts"],
     rules: {
       "prettier/prettier": "off",
+      "no-duplicate-imports": "off",
       "@typescript-eslint/no-explicit-any": "off",
       "@typescript-eslint/no-empty-object-type": [
         "error",

esm-test/quick-start.spec.ts

@@ -1,12 +1,12 @@
 import { spawn } from "node:child_process";
-import { givePort } from "../tools/ports";
+import { givePort } from "../tools/ports.ts";
 
 describe("ESM Test", async () => {
   let out = "";
   const listener = (chunk: Buffer) => {
     out += chunk.toString();
   };
-  const quickStart = spawn("unrun", ["quick-start.ts"]);
+  const quickStart = spawn("node", ["quick-start.ts"]);
   quickStart.stdout.on("data", listener);
   quickStart.stderr.on("data", listener);
   const port = givePort("esm");

example/config.ts

@@ -1,7 +1,7 @@
 import { BuiltinLogger, createConfig } from "express-zod-api";
 import ui from "swagger-ui-express";
 import createHttpError from "http-errors";
-import { givePort } from "../tools/ports";
+import { givePort } from "../tools/ports.ts";
 import qs from "qs";
 
 export const config = createConfig({

example/endpoints/create-user.ts

@@ -1,7 +1,7 @@
 import createHttpError from "http-errors";
 import assert from "node:assert/strict";
 import { z } from "zod";
-import { statusDependingFactory } from "../factories";
+import { statusDependingFactory } from "../factories.ts";
 
 const namePart = z.string().regex(/^\w+$/);
 

example/endpoints/delete-user.ts

@@ -1,7 +1,7 @@
 import createHttpError from "http-errors";
 import assert from "node:assert/strict";
 import { z } from "zod";
-import { noContentFactory } from "../factories";
+import { noContentFactory } from "../factories.ts";
 
 /** @desc The endpoint demonstrates no content response established by its factory */
 export const deleteUserEndpoint = noContentFactory.buildVoid({

example/endpoints/list-users.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { arrayRespondingFactory } from "../factories";
+import { arrayRespondingFactory } from "../factories.ts";
 
 const roleSchema = z.enum(["manager", "operator", "admin"]);
 

example/endpoints/retrieve-user.ts

@@ -2,7 +2,7 @@ import createHttpError from "http-errors";
 import assert from "node:assert/strict";
 import { z } from "zod";
 import { defaultEndpointsFactory } from "express-zod-api";
-import { methodProviderMiddleware } from "../middlewares";
+import { methodProviderMiddleware } from "../middlewares.ts";
 
 // Demonstrating circular schemas using z.object()
 const feature = z

example/endpoints/send-avatar.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fileSendingEndpointsFactory } from "../factories";
+import { fileSendingEndpointsFactory } from "../factories.ts";
 import { readFile } from "node:fs/promises";
 
 export const sendAvatarEndpoint = fileSendingEndpointsFactory.build({

example/endpoints/stream-avatar.ts

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { fileStreamingEndpointsFactory } from "../factories";
+import { fileStreamingEndpointsFactory } from "../factories.ts";
 
 export const streamAvatarEndpoint = fileStreamingEndpointsFactory.build({
   shortDescription: "Streams a file content.",

example/endpoints/time-subscription.ts

@@ -1,6 +1,6 @@
 import { z } from "zod";
 import { setTimeout } from "node:timers/promises";
-import { eventsFactory } from "../factories";
+import { eventsFactory } from "../factories.ts";
 
 /** @desc The endpoint demonstrates emitting server-sent events (SSE) */
 export const subscriptionEndpoint = eventsFactory.buildVoid({

example/endpoints/update-user.ts

@@ -2,7 +2,7 @@ import createHttpError from "http-errors";
 import assert from "node:assert/strict";
 import { z } from "zod";
 import { ez } from "express-zod-api";
-import { keyAndTokenAuthenticatedEndpointsFactory } from "../factories";
+import { keyAndTokenAuthenticatedEndpointsFactory } from "../factories.ts";
 
 export const updateUserEndpoint =
   keyAndTokenAuthenticatedEndpointsFactory.build({

example/factories.ts

@@ -7,7 +7,7 @@ import {
   EventStreamFactory,
   defaultEndpointsFactory,
 } from "express-zod-api";
-import { authMiddleware } from "./middlewares";
+import { authMiddleware } from "./middlewares.ts";
 import { createReadStream } from "node:fs";
 import { z } from "zod";
 import { stat } from "node:fs/promises";

example/generate-client.ts

@@ -1,7 +1,7 @@
 import { writeFile } from "node:fs/promises";
 import { Integration } from "express-zod-api";
-import { routing } from "./routing";
-import { config } from "./config";
+import { routing } from "./routing.ts";
+import { config } from "./config.ts";
 import typescript from "typescript";
 
 await writeFile(

example/generate-documentation.ts

@@ -1,8 +1,8 @@
 import { writeFile } from "node:fs/promises";
 import { Documentation } from "express-zod-api";
-import { config } from "./config";
-import { routing } from "./routing";
-import manifest from "./package.json";
+import { config } from "./config.ts";
+import { routing } from "./routing.ts";
+import manifest from "./package.json" with { type: "json" };
 
 await writeFile(
   "example.documentation.yaml",

example/index.spec.ts

@@ -1,19 +1,18 @@
-import assert from "node:assert/strict";
+import assert, { fail } from "node:assert/strict";
 import { spawn } from "node:child_process";
 import { createReadStream, readFileSync } from "node:fs";
-import { Client, Subscription } from "./example.client";
-import { givePort } from "../tools/ports";
+import { Client, Subscription } from "./example.client.ts";
+import { givePort } from "../tools/ports.ts";
 import { createHash } from "node:crypto";
 import { readFile } from "node:fs/promises";
-import { fail } from "node:assert";
 
 describe("Example", async () => {
   let out = "";
   const listener = (chunk: Buffer) => {
     out += chunk.toString();
   };
   const matchOut = (regExp: RegExp) => regExp.test(out);
-  const example = spawn("unrun", ["index.ts"]);
+  const example = spawn("node", ["index.ts"]);
   example.stdout.on("data", listener);
   const port = givePort("example");
   await vi.waitFor(() => assert(out.includes(`Listening`)), { timeout: 1e4 });

example/index.ts

@@ -1,6 +1,6 @@
 import { createServer } from "express-zod-api";
-import { config } from "./config";
-import { routing } from "./routing";
+import { config } from "./config.ts";
+import { routing } from "./routing.ts";
 
 /**
  * "await" is only needed for using entities returned from this method.

example/middlewares.ts

@@ -1,7 +1,7 @@
 import createHttpError from "http-errors";
 import assert from "node:assert/strict";
 import { z } from "zod";
-import { Method, Middleware } from "express-zod-api";
+import { Middleware, type Method } from "express-zod-api";
 
 export const authMiddleware = new Middleware({
   security: {

example/package.json

@@ -4,10 +4,10 @@
   "version": "0.0.0",
   "type": "module",
   "scripts": {
-    "start": "unrun index.ts",
+    "start": "node index.ts",
     "build": "pnpm build:docs && pnpm build:client",
-    "build:docs": "unrun generate-documentation.ts",
-    "build:client": "unrun generate-client.ts",
+    "build:docs": "node generate-documentation.ts",
+    "build:client": "node generate-client.ts",
     "pretest": "tsc",
     "test": "vitest run index.spec.ts"
   },