added tests, pruned dependencies, updated proj config

Author: Thesephi

.vscode/settings.json

@@ -2,5 +2,6 @@
   "editor.tabSize": 2,
   "deno.enable": true,
   "editor.formatOnSave": true,
-  "editor.defaultFormatter": "denoland.vscode-deno"
+  "editor.defaultFormatter": "denoland.vscode-deno",
+  "[typescript]": { "editor.defaultFormatter": "denoland.vscode-deno" }
 }

CHANGELOG.md

@@ -1,10 +1,17 @@
 ## Unreleased
 
+### Added
+
+- Laxer usage of `ControllerMethodArgs` decorator: now allowing `queries`,
+  `params`, `header` as literal arguments, so that things still work even if
+  users accidentally / deliberately use the undocumented singular / plural forms
+
 ### Changed
 
 - switched from `deps.ts` and `dev_deps.ts` to `deno.jsonc`
-- revamped documentation
-- code format
+- revamped documentation (JSDoc)
+- code format & code format settings for VS Code users
+- upgraded dependencies (`zod@^3.24.1`)
 
 ## [0.12.2] - 2024-12-06
 

deno.jsonc

@@ -1,18 +1,24 @@
 {
   "imports": {
     "@asteasolutions/zod-to-openapi": "npm:@asteasolutions/zod-to-openapi@^7.3.0",
-    "@dklab/oak-routing-ctrl": "jsr:@dklab/oak-routing-ctrl@^0.12.2",
     "@oak/oak": "jsr:@oak/oak@^17.1.3",
     "@std/assert": "jsr:@std/assert@^1.0.9",
     "@std/io": "jsr:@std/io@^0.225.0",
     "@std/path": "jsr:@std/path@^1.0.8",
     "@std/testing": "jsr:@std/testing@^1.0.6",
-    "zod": "npm:zod@^3.23.8"
+    "zod": "npm:zod@^3.24.1"
   },
   "tasks": {
     "pretty": "deno lint --ignore=docs && deno check . && deno fmt",
     "test": "deno test -RE",
     "check-doc": "deno check --doc .",
     "doc": "deno doc --html mod.ts"
+  },
+  "fmt": {
+    "useTabs": false,
+    "indentWidth": 2,
+    "semiColons": true,
+    "singleQuote": false,
+    "proseWrap": "always"
   }
 }

deno.lock

@@ -180,6 +180,7 @@ function getEnhancedHandler(
     for (const p of consumerDesirableParams) {
       switch (true) {
         case p === "param":
+        case p === "params" as ControllerMethodArg: // undocumented on purpose
           // path param
           decoratedArgs.push(ctx.params);
           break;
@@ -188,10 +189,13 @@ function getEnhancedHandler(
           decoratedArgs.push(parsedReqBody);
           break;
         case p === "query":
+        case p === "queries" as ControllerMethodArg: // undocumented on purpose
           // search query a.k.a URLSearchParams
           decoratedArgs.push(parsedReqSearchParams);
           break;
-        case p === "headers": {
+        case p === "headers":
+        case p === "header" as ControllerMethodArg: // undocumented on purpose
+        {
           // request headers
           const headers: Record<string, string> = {};
           ctx.request.headers.forEach((v: string, k: string) => headers[k] = v);

src/ControllerMethodArgs.ts

@@ -887,6 +887,44 @@ Deno.test("getEnhancedHandler - not declaring any param", async () => {
   assertSpyCalls(testHandler, 1);
 });
 
+Deno.test("getEnhancedHandler - declaring undocumented params", async () => {
+  const spyParseOakRequestBody = spy(_internal, "parseOakReqBody");
+  // deno-lint-ignore no-explicit-any
+  const testHandler = spy((..._rest: any[]) => 44);
+  // deno-lint-ignore ban-types
+  const enhancedHandler: Function = _internal.getEnhancedHandler(
+    testHandler,
+    "context" as ControllerMethodArg,
+    "params" as ControllerMethodArg,
+    "queries" as ControllerMethodArg,
+    "header" as ControllerMethodArg,
+    "hiddenFeature" as ControllerMethodArg,
+  );
+  const ctx = createMockContext({
+    path: "/hello/world",
+    params: { lorem: "undocumented usage", hiddenFeature: "84" },
+    headers: [["X-Foo", "Bearer Bar"]],
+  });
+  Object.defineProperty(ctx.request, "body", {
+    get: () => createMockRequestBody("binary"),
+  });
+  Object.defineProperty(ctx.request.url, "searchParams", {
+    value: new Map([["ipsum", "dolor"]]),
+  });
+  await enhancedHandler(ctx);
+  const [context, param, query, headers, hiddenFeature] =
+    testHandler.calls[0].args;
+  assertEquals(param, { lorem: "undocumented usage", hiddenFeature: "84" });
+  assertEquals(query, { ipsum: "dolor" });
+  assertEquals(hiddenFeature, "84");
+  assertEquals(context, ctx);
+  assertEquals(headers, { "x-foo": "Bearer Bar" });
+  assertEquals(testHandler.calls[0].returned, 44);
+  assertSpyCalls(testHandler, 1);
+  assertSpyCalls(spyParseOakRequestBody, 1);
+  spyParseOakRequestBody.restore();
+});
+
 /**
  * @NOTE if/when `oak` supports such a method, better import from there instead
  */

src/ControllerMethodArgs_test.ts

@@ -57,6 +57,26 @@ snapshot[`useOakServer - fully decorated Controller 1`] = `
     path: "/test/baz/:zaz",
     regexp: /^\\/test\\/baz(?:\\/([^\\/#\\?]+?))[\\/#\\?]?\$/i,
   },
+  {
+    methods: [
+      "HEAD",
+      "GET",
+    ],
+    middleware: [
+      [AsyncFunction (anonymous)],
+    ],
+    options: {
+      end: undefined,
+      ignoreCaptures: undefined,
+      sensitive: undefined,
+      strict: undefined,
+    },
+    paramNames: [
+      "zaz_zaz",
+    ],
+    path: "/test/dolor/:zaz_zaz",
+    regexp: /^\\/test\\/dolor(?:\\/([^\\/#\\?]+?))[\\/#\\?]?\$/i,
+  },
   {
     methods: [
       "PUT",

src/__snapshots__/useOakServer_test.ts.snap

@@ -66,6 +66,11 @@ class TestController {
   baz(query: Record<string, string>, param: Record<string, string>) {
     return `hello, path /baz/${param.zaz} with query ${query.someKey}`;
   }
+  @Get("/dolor/:zaz_zaz")
+  @ControllerMethodArgs("params" as ControllerMethodArg) // intentional coercing to test undocumented usage
+  dolor(param: Record<string, string>) {
+    return `hello, path /dolor/${param.zaz_zaz}`;
+  }
   @Put("/taz/:someId")
   @ControllerMethodArgs("body")
   taz(body: ArrayBuffer, ctx: RouteContext<"/taz/:someId">) {
@@ -188,6 +193,12 @@ Deno.test({
         mockRequestPathParams: { zaz: "jaz" },
         expectedResponse: "hello, path /baz/jaz with query chaz",
       },
+      {
+        caseDescription: "handler with 'params' as undocumented usage",
+        method: "get",
+        mockRequestPathParams: { zaz_zaz: "jaz_jaz" },
+        expectedResponse: "hello, path /dolor/jaz_jaz",
+      },
       {
         caseDescription: "handler for a request with a binary payload",
         method: "put",

src/useOakServer_test.ts

@@ -5,7 +5,7 @@ import {
   OpenAPIRegistry,
   type RouteConfig,
 } from "@asteasolutions/zod-to-openapi";
-import { type OpenAPIObjectConfig } from "npm:@asteasolutions/zod-to-openapi@^7.2.0/dist/v3.0/openapi-generator";
+import { type OpenAPIObjectConfig } from "@asteasolutions/zod-to-openapi/dist/v3.0/openapi-generator";
 import { debug } from "./utils/logger.ts";
 import { inspect } from "./utils/inspect.ts";
 

src/useOas.ts

@@ -2,7 +2,7 @@ import {
   extendZodWithOpenApi,
   type ResponseConfig,
   type RouteConfig,
-} from "npm:@asteasolutions/zod-to-openapi@^7.2.0";
+} from "@asteasolutions/zod-to-openapi";
 
 /**
  * Open API Schema interface, usable when composing the request/response
@@ -36,7 +36,7 @@ export type OakOpenApiSpec =
   };
 
 // must import from `npm:` instead of from `deno.land` to be compatible with `@asteasolutions/zod-to-openapi`
-import { z as slowTypedZ } from "npm:zod@^3.23.8";
+import { z as slowTypedZ } from "zod";
 extendZodWithOpenApi(slowTypedZ);
 type SubsetOfZ = Pick<
   typeof slowTypedZ,