v28 is for Koko Da Doll (#3208)

![Koko Da
Doll](https://metro.co.uk/wp-content/uploads/2023/04/SEI_152850843-60b7-e1682088625316.jpg?quality=90&strip=all&w=646)

[**Koko Da Doll**](https://en.wikipedia.org/wiki/Koko_Da_Doll) (aka
_Rasheeda Williams_) was a 35-year-young Black trans woman, performance
artist, singer, and star
of the acclaimed documentary **Kokomo City**. Born in College Park,
Georgia, she was based in Atlanta and
became a prominent voice for transgender visibility and the rights of
Black trans women.

She was a talented rap artist who released two singles: "Trick" (2020)
and "Bulletproof" (2022).

A song she created was featured on the TV show _The Chi_ in 2023,
showcasing her artistic talents beyond her advocacy work.

Koko was one of four Black trans women featured in the groundbreaking
documentary [**Kokomo City**](https://www.magpictures.com/kokomocity/),
directed by D. Smith. The film premiered at the 2023 Sundance Film
Festival and won both the NEXT Innovator Award and NEXT Audience
Award. It also received the Berlinale Panorama Audience Award.

In the film, Koko spoke openly about her experiences as a sex worker and
the challenges faced by Black trans women. She discussed doing sex work
to avoid homelessness for her mother, sister, and herself.

After the Sundance première, Koko wrote on Instagram:

> _"I will be the reason there's more opportunities and doors opening
for transgender girls."_

She hoped that her participation in the film would help save lives and
create more opportunities for young trans women.

On April 18, 2023, at around 11pm, Koko Da Doll was found dead with a
gunshot wound on a sidewalk near Holmes Shopping
Plaza in Southwest Atlanta. She was 35 years old.

A 17-year-old suspect was arrested on April 27, 2023, on suspicion of
murder, aggravated assault, and possession of a firearm in the
commission of a felony. Atlanta police indicated that a hate crime
investigation was ongoing.

Koko was the 13th trans person killed in the United States in 2023.
Following her death, _Kokomo City_ was dedicated to her memory. She was
honored during the In Memoriam segment at the 2023 BET Awards.

_The New York Times_ described her as someone who _"brims with vitality,
ambition, and insight"_ — a woman who fought tooth and nail for her life
and self-worth.

Her tragic death serves as a stark reminder of the ongoing violence and
discrimination faced by trans women in America.

[AP
News](https://apnews.com/article/koko-da-doll-kokomo-city-killed-transgender-0c02d2c623deffebceaa74912e308609)
·
[AL.com](https://www.al.com/reckon/2023/07/murdered-kokomo-city-star-koko-da-doll-shares-her-hopes-for-young-trans-girls.html)
·
[TDoR](https://tdor.translivesmatter.info/reports/2023/04/18/rasheeda-williams_atlanta-georgia-usa_0c3bc39f)


-------------------------------

Version 28 drops support for Node.js versions below 22.19.0, adds full
Zod 4.4+ compatibility, and makes the Zod plugin an optional peer
dependency — you now need to install `@express-zod-api/zod-plugin`
manually to keep using `.example()`, `.label()`, and similar methods,
while `brand()` is replaced by `.xBrand()` to avoid conflicts with Zod
4.4. Several config properties were renamed for clarity:
`wrongMethodBehavior` → `hintAllowedMethods`, `methodLikeRouteBehavior`
→ `recognizeMethodDependentRoutes`, `shortDescription` → `summary`, and
`noContent` → `noBodySchema`. The `hasSummaryFromDescription` boolean
was replaced with a more flexible `summarizer` function that lets you
customize how endpoint summaries are derived. The automated migration
tool has been updated accordingly, now requiring `eslint@^10.0.0` and
`typescript-eslint@^8.58.0`.

- #3207 
- #3242
- #3267 
- #3268 
- #3287 
- #3294 
- #3299 
- #3300 
- #3301 
- #3302 
- #3303 
- #3310 
- #3313 
- #3334
- #3340
- #3364 (incl. undo of #3357) 
- #3365

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **New Features**
* v28: public option/metadata renames (shortDescription → summary,
wrongMethodBehavior → hintAllowedMethods, methodLikeRouteBehavior →
recognizeMethodDependentRoutes, noContent → noBodySchema) and a
configurable documentation summarizer.

* **Documentation**
* CHANGELOG/README/SECURITY updated with v28 notes, summarizer docs,
migration examples and migration tool link; README shows Zod plugin as
optional and xBrand usage.

* **Chores**
* Zod plugin moved to optional/peer, branding API renamed (.brand →
.xBrand); tooling and Node/module resolution updates.

* **Tests**
* Test suite updated to align with renames, summarizer,
metadata/examples and branding changes.
<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: renovate[bot] <29139614+renovate[bot]@users.noreply.github.com>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
Co-authored-by: pullfrog[bot] <226033991+pullfrog[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: 5 people

.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

@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        node-version: [20.19.0, 20.x, 22.12.0, 22.x, 24.0.0, 24.x, 26.0.0, 26.x]
+        node-version: [22.19.0, 22.x, 24.0.0, 24.x, 26.0.0, 26.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,58 @@
 # Changelog
 
+## Version 28
+
+### v28.0.0
+
+- Supported Node.js versions: `^22.19.0 || ^24.0.0 || ^26.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):
+  - Now requires `eslint@^10.0.0` and `typescript-eslint@^8.58.0`.
+
+```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.3.0

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" } },
 ];