Release/0.14.0

CHANGELOG.md

@@ -1,3 +1,27 @@
+## [0.14.0] - 2025-02-04
+
+## Changed
+
+- multiple paths can now be registered on the same HTTP verb, and if the paths
+  are exactly the same, or if the "static" and the "parameter" portions of the
+  paths somehow overlap, then the handler is invoked **once for each registered
+  path**; for example if we register `@Get("/foo/:bar")` and `@Get("/foo/bar")`
+  (in that order) on the same handler function, then for every request to
+  `/foo/bar`, that handler is invoked **twice**, the first time having no
+  "param" at all, and the 2nd time having the param `bar` with the value
+  `"bar"`. This behavior follows TC39 decorator specs where all decorators to a
+  function are applied "from inside out" aka: the last declared decorator gets
+  applied first, and so on
+
+## Added
+
+- `ctx.state._oakRoutingCtrl_regPath` is available as a pointer to the
+  registered path that matches the URL request currently being handled; this is
+  helpful in rare situations where multiple overlapping paths are registered on
+  the same handler function, causing it to be invoked multiple times, and so we
+  may benefit from a mechanism to control when to write to the response body (as
+  this operation can only be done once)
+
 ## [0.13.0] - 2025-02-01
 
 ### Added

deno.jsonc

@@ -1,6 +1,6 @@
 {
   "name": "@dklab/oak-routing-ctrl",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "exports": {
     ".": "./mod.ts",
     "./mod": "./mod.ts"
@@ -15,8 +15,8 @@
   },
   "tasks": {
     "pretty": "deno lint --ignore=docs && deno check . && deno fmt",
-    "test": "deno test -RE",
-    "check-doc": "deno check --doc .",
+    "test": "deno test -RE -I=jspm.dev,jsr.io,deno.land -N=0.0.0.0,127.0.0.1",
+    "check-doc": "deno check -I=jspm.dev,jsr.io,deno.land --doc .",
     "doc": "deno doc --html mod.ts"
   },
   "imports": {
@@ -26,7 +26,8 @@
     "@std/io": "jsr:@std/io@^0.225.2",
     "@std/path": "jsr:@std/path@^1.0.8",
     "@std/testing": "jsr:@std/testing@^1.0.9",
-    "zod": "npm:zod@^3.24.1"
+    "zod": "npm:zod@^3.24.1",
+    "superoak": "https://deno.land/x/[email protected]/mod.ts"
   },
   "fmt": {
     "useTabs": false,

mod.ts

@@ -18,3 +18,11 @@ export {
   z,
   type zInfer,
 } from "./src/utils/schema_utils.ts";
+
+export type {
+  /**
+   * re-exporting from oak for convenient uses
+   * @ignore
+   */
+  Context,
+} from "@oak/oak";

src/Controller.ts

@@ -26,19 +26,29 @@ type ClassDecorator = (
  */
 export const Controller =
   (pathPrefix: string = ""): ClassDecorator => (target, context): void => {
+    const ctrlClassName = target.name;
     debug(
-      `invoking ControllerDecorator for ${target.name} -`,
+      `invoking ControllerDecorator for ${ctrlClassName} -`,
       "runtime provides context:",
       context,
     );
     const fnNames: string[] = Object.getOwnPropertyNames(target.prototype);
     for (const fnName of fnNames) {
       const pair = store.get(fnName);
       if (!pair) continue;
-      pair.forEach((path, verb, p) => {
+      const patchedPair = new Map();
+      pair.forEach((verb, path) => {
         const fullPath = join(pathPrefix, path);
-        p.set(verb, fullPath);
-        patchOasPath(fnName, verb, fullPath);
+        patchedPair.set(fullPath, verb);
+        debug(
+          `[${ctrlClassName}] @Controller: patched [${verb}] ${path} to ${fullPath}`,
+        );
+        // @TODO consider throwing if we discover 2 (or more) Controllers
+        // sharing the exact same set of path, fnName, and method
+        patchOasPath(ctrlClassName, fnName, verb, fullPath);
       });
+      store.delete(fnName);
+      const fqFnName = `${ctrlClassName}.${fnName}`;
+      store.set(fqFnName, patchedPair);
     }
   };

src/Delete_test.ts

@@ -23,5 +23,5 @@ Deno.test("@Delete decorator", () => {
   assertSpyCall(Delete, 0, { args: ["/bar"] });
   assertInstanceOf(Delete.calls[0].returned, Function);
   assertSpyCalls(Delete, 1);
-  assertEquals(store.get("doSomething")?.get("delete"), "/bar");
+  assertEquals(store.get("doSomething")?.get("/bar"), "delete");
 });

src/Get_test.ts

@@ -23,5 +23,5 @@ Deno.test("@Get decorator", () => {
   assertSpyCall(Get, 0, { args: ["/bar"] });
   assertInstanceOf(Get.calls[0].returned, Function);
   assertSpyCalls(Get, 1);
-  assertEquals(store.get("doSomething")?.get("get"), "/bar");
+  assertEquals(store.get("doSomething")?.get("/bar"), "get");
 });

src/Head_test.ts

@@ -23,5 +23,5 @@ Deno.test("@Head decorator", () => {
   assertSpyCall(Head, 0, { args: ["/bar"] });
   assertInstanceOf(Head.calls[0].returned, Function);
   assertSpyCalls(Head, 1);
-  assertEquals(store.get("doSomething")?.get("head"), "/bar");
+  assertEquals(store.get("doSomething")?.get("/bar"), "head");
 });

src/Options_test.ts

@@ -23,5 +23,5 @@ Deno.test("@Options decorator", () => {
   assertSpyCall(Options, 0, { args: ["/bar"] });
   assertInstanceOf(Options.calls[0].returned, Function);
   assertSpyCalls(Options, 1);
-  assertEquals(store.get("doSomething")?.get("options"), "/bar");
+  assertEquals(store.get("doSomething")?.get("/bar"), "options");
 });

src/Patch_test.ts

@@ -23,5 +23,5 @@ Deno.test("@Patch decorator", () => {
   assertSpyCall(Patch, 0, { args: ["/bar"] });
   assertInstanceOf(Patch.calls[0].returned, Function);
   assertSpyCalls(Patch, 1);
-  assertEquals(store.get("doSomething")?.get("patch"), "/bar");
+  assertEquals(store.get("doSomething")?.get("/bar"), "patch");
 });

src/Post_test.ts

@@ -23,5 +23,5 @@ Deno.test("@Post decorator", () => {
   assertSpyCall(Post, 0, { args: ["/bar"] });
   assertInstanceOf(Post.calls[0].returned, Function);
   assertSpyCalls(Post, 1);
-  assertEquals(store.get("doSomething")?.get("post"), "/bar");
+  assertEquals(store.get("doSomething")?.get("/bar"), "post");
 });

src/Put_test.ts

@@ -27,7 +27,7 @@ Deno.test("@Put decorator", () => {
   assertSpyCall(Put, 0, { args: ["/bar"] });
   assertInstanceOf(Put.calls[0].returned, Function);
   assertSpyCalls(Put, 1);
-  assertEquals(store.get("doSomething")?.get("put"), "/bar");
+  assertEquals(store.get("doSomething")?.get("/bar"), "put");
 
   // assertSpyCalls(spyLoggerDebug, 1);
   // assertSpyCalls(spyStoreRegister, 1);

src/Store.ts

@@ -7,7 +7,7 @@ export type SupportedVerb =
   | "head"
   | "options";
 
-export const store: Map<string, Map<SupportedVerb, string>> = new Map();
+export const store: Map<string, Map<string, SupportedVerb>> = new Map();
 
 /**
  * internal library helper method, used to keep track of the declared
@@ -21,8 +21,13 @@ export const register = (
   const normalizedVerb: SupportedVerb = verb.toLowerCase() as SupportedVerb;
   const existingPair = store.get(fnName);
   if (existingPair) {
-    existingPair.set(normalizedVerb, path);
+    // @NOTE that we intentionally allow multiple paths registered on the
+    // same verb e.g.
+    // - @Get('/foo') AND @Get('/foo/bar')
+    // - @Get('/foo') AND @Get('/bar')
+    // - @Get('/foo/:bar') AND @Get('/foo/bar')
+    existingPair.set(path, normalizedVerb);
   } else {
-    store.set(fnName, new Map([[normalizedVerb, path]]));
+    store.set(fnName, new Map([[path, normalizedVerb]]));
   }
 };

src/Store_test.ts

@@ -23,11 +23,11 @@ Deno.test("Store", () => {
   assertSpyCall(spyStoreGet, 3, { args: ["handlerFnName"] });
   assertSpyCall(spyStoreGet, 4, { args: ["handlerFnName"] });
   const finalMap = new Map([
-    ["get", "/foo"],
-    ["post", "/bar"],
-    ["put", "/baz"],
-    ["delete", "/maz"],
-    ["patch", "/laz"],
+    ["/foo", "get"],
+    ["/bar", "post"],
+    ["/baz", "put"],
+    ["/maz", "delete"],
+    ["/laz", "patch"],
   ]);
   assertEquals(store.get("handlerFnName"), finalMap);