feat(v26): method only routes (#3049)

Due to #2938 

This will set us free from the requirement to write slash to the keys
when we imply method depending routing.

Breaking change: `Integration` requires `config` parameter.

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

## Summary by CodeRabbit

* **New Features**
* Added `methodLikeRouteBehavior` configuration option to control
interpretation of method-like routing keys ("method" or "path")
* Added `hasHeadMethod` option for endpoint documentation configuration

* **Refactor**
* Integration constructor now requires a `config` parameter during
initialization
  * Routing syntax simplified to use cleaner method-based keys

<!-- end of auto-generated comment: release notes by coderabbit.ai -->

---------

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: RobinTail

CHANGELOG.md

@@ -4,20 +4,25 @@
 
 ### v26.0.0
 
-- `DependsOnMethod` removed: use flat syntax with explicit method and a slash;
+- `DependsOnMethod` removed:
+  - You can now specify methods as direct keys of an assigned object in `Routing`;
+  - That object can still contain nested paths as before;
+  - The keys matching lowercase HTTP methods are treated according to the new config setting `methodLikeRouteBehavior`:
+    - `method` — when assigned with an Endpoint the key is treated as method of its parent path (default);
+    - `path` — the key is always treated as a nested path segment;
 - `options` property renamed to `ctx` in argument of:
   - `Middleware::handler()`,
   - `ResultHandler::handler()`,
   - `handler` of `EndpointsFactory::build()` argument,
   - `testMiddleware()`;
 - `EndpointsFactory::addOptions()` renamed to `addContext()`;
+- The `Integration::constructor()` argument object now requires `config` property, similar to `Documentation`;
 
 ```patch
   const routing: Routing = {
 -   "/v1/users": new DependsOnMethod({
 +   "/v1/users": {
--     get: getUserEndpoint,
-+     "get /": getUserEndpoint,
+      get: getUserEndpoint,
 -   }).nest({
       create: makeUserEndpoint
 -   }),

README.md

@@ -307,10 +307,10 @@ const routing: Routing = {
     "delete /user/:id": deleteUserEndpoint,
     // method-based routing — /v1/account
     account: {
-      "get /": endpointA,
-      "delete /": endpointA,
-      "post /": endpointB,
-      "patch /": endpointB,
+      get: endpointA,
+      delete: endpointA,
+      post: endpointB,
+      patch: endpointB,
     },
   },
   // static file serving — /public serves files from ./assets
@@ -1087,6 +1087,7 @@ import { Integration } from "express-zod-api";
 
 const client = new Integration({
   routing,
+  config,
   variant: "client", // <— optional, see also "types" for a DIY solution
 });
 

compat-test/migration.spec.ts

@@ -4,6 +4,6 @@ import { describe, test, expect } from "vitest";
 describe("Migration", () => {
   test("should fix the import", async () => {
     const fixed = await readFile("./sample.ts", "utf-8");
-    expect(fixed).toBe(`const route = {\n"get /": someEndpoint,\n}\n`);
+    expect(fixed).toBe(`const route = {\nget: someEndpoint,\n}\n`);
   });
 });

example/generate-client.ts

@@ -7,6 +7,7 @@ await writeFile(
   "example.client.ts",
   await new Integration({
     routing,
+    config,
     serverUrl: `http://localhost:${config.http!.listen}`,
   }).printFormatted(), // or just .print(),
   "utf-8",

example/routing.ts

@@ -20,7 +20,7 @@ export const routing: Routing = {
       ":id": {
         remove: deleteUserEndpoint, // nested path: /v1/user/:id/remove
         // syntax 2: methods are defined within the route
-        "patch /": updateUserEndpoint, // demonstrates authentication
+        patch: updateUserEndpoint, // demonstrates authentication
       },
       // demonstrates different response schemas depending on status code
       create: createUserEndpoint,

express-zod-api/src/config-type.ts

@@ -46,6 +46,14 @@ export interface CommonConfig {
    * @default 405
    * */
   wrongMethodBehavior?: 404 | 405;
+  /**
+   * @desc How to treat Routing keys that look like methods (when assigned with an Endpoint)
+   * @see Method
+   * @example "method" — the key is treated as method of its parent path
+   * @example "path" — the key is treated as a nested path segment
+   * @default "method"
+   * */
+  methodLikeRouteBehavior?: "method" | "path";
   /**
    * @desc The ResultHandler to use for handling routing, parsing and upload errors
    * @default defaultResultHandler

express-zod-api/src/documentation.ts

@@ -62,6 +62,7 @@ interface DocumentationParams {
   /**
    * @desc Depict the HEAD method for each Endpoint supporting the GET method (feature of Express)
    * @default true
+   * @todo move to config
    * */
   hasHeadMethod?: boolean;
   /** @default inline */
@@ -262,6 +263,7 @@ export class Documentation extends OpenApiBuilder {
     };
     walkRouting({
       routing,
+      config,
       onEndpoint: hasHeadMethod ? withHead(onEndpoint) : onEndpoint,
     });
     if (tags) this.rootDoc.tags = depictTags(tags);

express-zod-api/src/integration.ts

@@ -23,9 +23,11 @@ import { zodToTs } from "./zts.ts";
 import { ZTSContext } from "./zts-helpers.ts";
 import type Prettier from "prettier";
 import { ClientMethod } from "./method.ts";
+import { CommonConfig } from "./config-type.ts";
 
 interface IntegrationParams {
   routing: Routing;
+  config: CommonConfig;
   /**
    * @desc What should be generated
    * @example "types" — types of your endpoint requests and responses (for a DIY solution)
@@ -50,6 +52,7 @@ interface IntegrationParams {
   /**
    * @desc Depict the HEAD method for each Endpoint supporting the GET method (feature of Express)
    * @default true
+   * @todo move to config
    * */
   hasHeadMethod?: boolean;
   /**
@@ -89,6 +92,7 @@ export class Integration extends IntegrationBase {
 
   public constructor({
     routing,
+    config,
     brandHandling,
     variant = "client",
     clientClassName = "Client",
@@ -154,6 +158,7 @@ export class Integration extends IntegrationBase {
     };
     walkRouting({
       routing,
+      config,
       onEndpoint: hasHeadMethod ? withHead(onEndpoint) : onEndpoint,
     });
     this.#program.unshift(...this.#aliases.values());

express-zod-api/src/routing-walker.ts

@@ -3,6 +3,7 @@ import { RoutingError } from "./errors.ts";
 import { ClientMethod, isMethod, Method } from "./method.ts";
 import { Routing } from "./routing.ts";
 import { ServeStatic, StaticHandler } from "./serve-static.ts";
+import { CommonConfig } from "./config-type.ts";
 
 export type OnEndpoint<M extends string = Method> = (
   method: M,
@@ -20,6 +21,7 @@ export const withHead =
 
 interface RoutingWalkerParams {
   routing: Routing;
+  config: CommonConfig;
   onEndpoint: OnEndpoint;
   onStatic?: (path: string, handler: StaticHandler) => void;
 }
@@ -35,14 +37,23 @@ const detachMethod = (subject: string): [string, Method?] => {
 const trimPath = (path: string) =>
   path.trim().split("/").filter(Boolean).join("/");
 
-const processEntries = (subject: Routing, parent?: string) =>
-  Object.entries(subject).map<[string, Routing[string], Method?]>(
+const processEntries = (
+  { methodLikeRouteBehavior = "method" }: CommonConfig,
+  subject: Routing,
+  parent?: string,
+) => {
+  const preferMethod = methodLikeRouteBehavior === "method";
+  return Object.entries(subject).map<[string, Routing[string], Method?]>(
     ([_key, item]) => {
-      const [segment, method] = detachMethod(_key);
+      const [segment, method] =
+        isMethod(_key) && preferMethod && item instanceof AbstractEndpoint
+          ? ["/", _key]
+          : detachMethod(_key);
       const path = [parent || ""].concat(trimPath(segment) || []).join("/");
       return [path, item, method];
     },
   );
+};
 
 const prohibit = (method: Method, path: string) => {
   throw new RoutingError(
@@ -74,10 +85,11 @@ const checkDuplicate = (method: Method, path: string, visited: Set<string>) => {
 
 export const walkRouting = ({
   routing,
+  config,
   onEndpoint,
   onStatic,
 }: RoutingWalkerParams) => {
-  const stack = processEntries(routing);
+  const stack = processEntries(config, routing);
   const visited = new Set<string>();
   while (stack.length) {
     const [path, element, explicitMethod] = stack.shift()!;
@@ -98,7 +110,7 @@ export const walkRouting = ({
       if (element instanceof ServeStatic) {
         if (onStatic) element.apply(path, onStatic);
       } else {
-        stack.unshift(...processEntries(element, path));
+        stack.unshift(...processEntries(config, element, path));
       }
     }
   }

express-zod-api/src/routing.ts

@@ -16,7 +16,8 @@ import * as R from "ramda";
  * @example { "v1/books/:bookId": getBookEndpoint }
  * @example { "get /v1/books/:bookId": getBookEndpoint }
  * @example { v1: { "patch /books/:bookId": changeBookEndpoint } }
- * @example { dependsOnMethod: { "get /": retrieveEndpoint, "post /": createEndpoint } }
+ * @example { dependsOnMethod: { get: retrieveEndpoint, post: createEndpoint } }
+ * @see CommonConfig.methodLikeRouteBehavior
  * */
 export interface Routing {
   [K: string]: Routing | AbstractEndpoint | ServeStatic;
@@ -77,7 +78,7 @@ const collectSiblings = ({
       familiar.set(path, new Map(config.cors ? [["options", value]] : []));
     familiar.get(path)?.set(method, value);
   };
-  walkRouting({ routing, onEndpoint, onStatic: app.use.bind(app) });
+  walkRouting({ routing, config, onEndpoint, onStatic: app.use.bind(app) });
   return familiar;
 };