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

AGENTS.md

@@ -103,17 +103,16 @@ interface SampleInterface {
 - **Zod**: Use named import `import { z } from "zod"`
 - **Ramda**: Use namespace import `import * as R from "ramda"`
 - **Node.js built-ins**: Use `node:` prefix
-- **Type-only imports**: Use `import type` for types and interfaces
-- **Relative imports**: Must be extensionless
-- Combine import from the same module into a single line
+- **Type-only imports**: Use `import type` for types and interfaces (verbatimModuleSyntax)
+- **Relative imports**: Use `.ts` extension when file is meant to be run by `node` (`example` and testing workspaces)
+- Combine imports from the same module into a single statement
 
 ```typescript
 import { z } from "zod";
 import * as R from "ramda";
 import { dirname } from "node:path";
-import type { SomeType } from "./module-a";
-import { someValue } from "./module-b";
-import { anotherValue, type AnotherType } from "./module-c";
+import type { SomeType } from "./module-a"; // for compiled code
+import { someValue } from "./module-b.ts"; // for node execution
 ```
 
 ### 5. Type Declaration Convention

CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## Version 28
+
+### v28.0.0
+
+- Supported Node.js versions: `^22.19.0 || ^24.0.0`;
+- Zod compatibility: `^4.3.4` (supports Zod 4.4+ without upper limit);
+- The Zod plugin is no longer installed automatically — it's an optional peer dependency now:
+  - To keep using `.example()`, `.label()`, `.remap()`, `.deprecated()` and methods on schemas, as well as runtime
+    distinguishable brands, install the `@express-zod-api/zod-plugin` manually and import it (ideally at the top of a
+    file declaring your `Routing`);
+  - Breaking change: `ZodType::brand()` method is no longer patched by the plugin:
+    - Use `.xBrand()` method instead — alias for `.meta({ "x-brand": ... })` and does not conflict with Zod 4.4;
+- 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 `EndpointsFactory::build()` argument (object):
+  - property `shortDescription` renamed to `summary`;
+- Breaking change to the `Documentation` constructor argument (object):
+  - property `hasSummaryFromDescription` (boolean) replaced with `summarizer` (function);
+  - If used with `false` value, replace it with `summarizer: ({ summary, trim }) => trim(summary)` for same behavior;
+- Featuring `summarizer` option to customize the summary of the Endpoint in the generated Documentation:
+  - The function receives `summary`, `description` and the default `trim()` function as arguments;
+  - The default summarizer uses `description` as a fallback for missing `summary`;
+  - The `trim()` function accepts a string and the limit (default: 50, best practice) that you can now customize;
+- 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,
+  });
+
+  factory.build({
+-   shortDescription: "Retrieves the user.",
++   summary: "Retrieves the user.",
+  });
+
+  new Documentation({
+-   hasSummaryFromDescription: false,
++   summarizer: ({ summary, trim }) => trim(summary),
+  });
+
+  new Integration({
+-   noContent: z.undefined(),
++   noBodySchema: z.undefined(),
+  });
+```
+
 ## Version 27
 
 ### v27.2.6

README.md

@@ -164,8 +164,7 @@ Much can be customized to fit your needs.
 
 - [Typescript](https://www.typescriptlang.org/) first.
 - Web server — [Express.js](https://expressjs.com/) v5.
-- Schema validation — [Zod 4.x](https://github.com/colinhacks/zod) including [Zod Plugin](#zod-plugin):
-  - For using with Zod 3.x, install the framework versions below 24.0.0.
+- Schema validation — [Zod 4.x](https://github.com/colinhacks/zod);
 - Supports any logger having `info()`, `debug()`, `error()` and `warn()` methods;
   - Built-in console logger with colorful and pretty inspections by default.
 - Generators:
@@ -243,7 +242,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 +919,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:
@@ -1100,8 +1099,21 @@ expect(output).toEqual({ collectedContext: ["prev"], testLength: 9 });
 
 ## Zod Plugin
 
-Express Zod API augments Zod using [Zod Plugin](https://www.npmjs.com/package/@express-zod-api/zod-plugin),
-adding the runtime helpers the framework relies on.
+The [@express-zod-api/zod-plugin](https://www.npmjs.com/package/@express-zod-api/zod-plugin) is an optional package
+that extends Zod with convenience methods:
+
+- `.xBrand(name)` — shorthand for `.meta({ "x-brand": name })`;
+- `.example(value)` — shorthand for `.meta({ examples: [value] })`;
+- `.deprecated()` — shorthand for `.meta({ deprecated: true })`;
+- `.label(text)` — shorthand for `.meta({ default: text })` on `ZodDefault`;
+- `.remap(mapping)` — for renaming `ZodObject` shape properties;
+
+To benefit from these methods, install `@express-zod-api/zod-plugin` and import it once, preferably at the top of a
+file declaring your `Routing`.
+
+```ts
+import "@express-zod-api/zod-plugin"; // in your routing.ts file
+```
 
 ## End-to-End Type Safety
 
@@ -1162,20 +1174,21 @@ in the generated documentation of your API. Consider the following example:
 import { defaultEndpointsFactory } from "express-zod-api";
 
 const exampleEndpoint = defaultEndpointsFactory.build({
-  shortDescription: "Retrieves the user.", // <—— this becomes the summary line
+  summary: "Retrieves the user.",
   description: "The detailed explanaition on what this endpoint does.",
   input: z.object({
     id: z
-      .string()
-      .example("123") // input examples should be set before transformations
+      .string() // input examples should be set before transformations
+      .example("123") // requires Zod Plugin, or .meta({ examples: ["123"] })
       .transform(Number)
       .describe("the ID of the user"),
   }),
   // ..., similarly for output and middlewares
 });
 ```
 
-You can also use `schema.meta({ id: "UniqueName" })` for custom schema naming.
+Setting examples via `.example()` requires [Zod Plugin](#zod-plugin). You can also use `.meta({ examples: [] })` and
+`.meta({ id: "UniqueName" })` for custom schema naming.
 _See the complete example of the generated documentation
 [here](https://github.com/RobinTail/express-zod-api/blob/master/example/example.documentation.yaml)_
 
@@ -1213,18 +1226,18 @@ new Documentation({
 
 ## Deprecated schemas and routes
 
-As your API evolves, you may need to mark some parameters or routes as deprecated before deleting them. For this
-purpose, the `.deprecated()` method is available on each schema and `Endpoint`, it's immutable.
-You can also deprecate all routes the `Endpoint` assigned to by setting `EndpointsFactory::build({ deprecated: true })`.
+As your API evolves, you may need to mark some parameters or routes as deprecated before deleting them. This can be
+achieved using the corresponding method or metadata. The `.deprecated()` method on Zod schema requires to install the
+[Zod Plugin](#zod-plugin). Consider the following example:
 
 ```ts
-import { Routing } from "express-zod-api";
+import type { Routing } from "express-zod-api";
 import { z } from "zod";
 
 const someEndpoint = factory.build({
   deprecated: true, // deprecates all routes the endpoint assigned to
   input: z.object({
-    prop: z.string().deprecated(), // deprecates the property or a path parameter
+    prop: z.string().deprecated(), // requires Zod Plugin, or .meta({ deprecated: true })
   }),
 });
 
@@ -1236,10 +1249,11 @@ const routing: Routing = {
 
 ## Customizable brands handling
 
-You can customize handling rules for your schemas in Documentation and Integration. Use the `.brand()` method on your
-schema to make it special and distinguishable for the framework in runtime. Using symbols is recommended for branding.
-After that use the `brandHandling` feature of both constructors to declare your custom implementation. In case you need
-to reuse a handling rule for multiple brands, use the exposed types `Depicter` and `Producer`.
+You can customize handling rules for your schemas in Documentation and Integration. The framework treats your schema
+specially based on its `x-brand` metadata. When the [Zod Plugin](#zod-plugin) is installed you can conveniently use
+the `.xBrand()` method on Zod schema, preferably with a symbol argument for its branding. After that use the
+`brandHandling` feature of both constructors to declare your custom implementation. In case you need to reuse a
+handling rule for multiple brands, use the exposed types `Depicter` and `Producer`.
 
 ```ts
 import ts from "typescript";
@@ -1252,7 +1266,7 @@ import {
 } from "express-zod-api";
 
 const myBrand = Symbol("MamaToldMeImSpecial"); // I recommend to use symbols for this purpose
-const myBrandedSchema = z.string().brand(myBrand);
+const myBrandedSchema = z.string().xBrand(myBrand); // requires Zod Plugin, or .meta({ "x-brand": myBrand })
 
 const ruleForDocs: Depicter = (
   { zodSchema, jsonSchema }, // jsonSchema is the default depiction

SECURITY.md

@@ -4,6 +4,7 @@
 
 | Version | Code name     | Release |     Supported      |
 | ------: | :------------ | :------ | :----------------: |
+|  28.x.x | Koko          | 05.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"]
 }

cjs-test/zod-plugin.spec.ts

@@ -1,7 +1,7 @@
 import { createRequire } from "node:module";
 const require = createRequire(import.meta.url);
 
-require("express-zod-api"); // side effect here via Zod Plugin
+require("@express-zod-api/zod-plugin"); // side effect here
 const z = require("zod"); // ensure CJS version of Zod is used
 
 describe("Zod plugin in CJS environment", () => {

compat-test/dts.spec.ts

@@ -2,14 +2,6 @@ import { describe, test, expect } from "vitest";
 import { readFile } from "node:fs/promises";
 
 describe("DTS", () => {
-  test("Framework must import Zod plugin", async () => {
-    const fwDts = await readFile(
-      "./node_modules/express-zod-api/dist/index.d.ts",
-      "utf-8",
-    );
-    expect(fwDts).toMatch(`import "@express-zod-api/zod-plugin";`);
-  });
-
   test("Zod plugin must import augmentation", async () => {
     const pluginDts = await readFile(
       "./node_modules/express-zod-api/node_modules/@express-zod-api/zod-plugin/dist/index.d.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.3.4"
   }
 }

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 });