Release/v0.13.0

.github/workflows/pr.yml

@@ -28,6 +28,9 @@ jobs:
       - name: Run linter
         run: deno lint
 
+      - name: Check doc
+        run: deno task check-doc
+
       - name: Run tests
         run: |
           deno test -A --coverage=cov_profile

.github/workflows/publish.yml

@@ -26,6 +26,9 @@ jobs:
       - name: Run linter
         run: deno lint --ignore=\*\*\/\*_test.ts
 
+      - name: Check doc
+        run: deno task check-doc
+
       - name: Run tests
         run: deno test -A
 

.gitignore

@@ -28,3 +28,4 @@ Temporary Items
 
 cov_profile
 cov_profile.lcov
+docs

.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,3 +1,30 @@
+## [0.13.0] - 2025-02-01
+
+### 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
+- Support for Open API Spec v3.1
+- Support for `operationId` and `tags` in OAS path request declarations
+- Support for top-level `tags` in OAS document
+
+### Changed
+
+- switched from `deps.ts` and `dev_deps.ts` to `deno.jsonc`
+- revamped documentation (JSDoc)
+- code format & code format settings for VS Code users
+- upgraded dependencies (`zod@^3.24.1`, `@std/assert@^1.0.10`,
+  `@std/testing@^1.0.8`)
+- updated typing for `OakOpenApiSpec` (added prop: `request`, untyped unproven
+  prop: `requestBody`)
+- upgraded dependencies: `jsr:@oak/oak@^17.1.4`, `jsr:@std/assert@^1.0.11`,
+  `jsr:@std/io@^0.225.2`, `jsr:@std/testing@^1.0.9`
+
+## Removed
+
+- the file `jsr.json` is removed in favour of the file `deno.jsonc`
+
 ## [0.12.2] - 2024-12-06
 
 ### Added

deno.jsonc

@@ -0,0 +1,46 @@
+{
+  "name": "@dklab/oak-routing-ctrl",
+  "version": "0.13.0",
+  "exports": {
+    ".": "./mod.ts",
+    "./mod": "./mod.ts"
+  },
+  "publish": {
+    "exclude": [
+      "./test_utils",
+      "**/*_test.ts",
+      "./CONTRIBUTING.md",
+      "./GOVERNANCE.md"
+    ]
+  },
+  "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"
+  },
+  "imports": {
+    "@asteasolutions/zod-to-openapi": "npm:@asteasolutions/zod-to-openapi@^7.3.0",
+    "@oak/oak": "jsr:@oak/oak@^17.1.4",
+    "@std/assert": "jsr:@std/assert@^1.0.11",
+    "@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"
+  },
+  "fmt": {
+    "useTabs": false,
+    "indentWidth": 2,
+    "semiColons": true,
+    "singleQuote": false,
+    "proseWrap": "always"
+  },
+  "exclude": [
+    "./docs",
+    "cov_profile",
+    "cov_profile.lcov",
+    "**/__snapshots__",
+    ".github",
+    ".vscode"
+  ]
+}

mod.ts

@@ -1,6 +1,5 @@
-export { useOakServer } from "./src/useOakServer.ts";
-export { useOakServer as useOak } from "./src/useOakServer.ts";
-export { useOas } from "./src/useOas.ts";
+export { useOak, useOakServer } from "./src/useOakServer.ts";
+export { useOas, type UseOasConfig } from "./src/useOas.ts";
 export { Controller } from "./src/Controller.ts";
 export {
   type ControllerMethodArg,
@@ -14,4 +13,8 @@ export { Delete } from "./src/Delete.ts";
 export { Options } from "./src/Options.ts";
 export { Head } from "./src/Head.ts";
 
-export { type OakOpenApiSpec, z, type zInfer } from "./deps.ts";
+export {
+  type OakOpenApiSpec,
+  z,
+  type zInfer,
+} from "./src/utils/schema_utils.ts";

src/Controller.ts

@@ -1,20 +1,31 @@
+import { join } from "@std/path";
 import { debug } from "./utils/logger.ts";
-import { join } from "../deps.ts";
 import { store } from "./Store.ts";
 import { patchOasPath } from "./oasStore.ts";
 
 /**
- * Just a standard Class, that can be decorated with the `@Controller` decorator
+ * Just a standard Class, that can be decorated with the {@linkcode Controller} decorator
  */
 export type ControllerClass = new (args?: unknown) => unknown;
 
+type ClassDecorator = (
+  target: ControllerClass,
+  context?: ClassDecoratorContext,
+) => void;
+
 /**
  * Decorator that should be used on the Controller Class
  * @NOTE under `experimentalDecorators`, `context` is not available
+ * @example
+ * ```ts
+ * ;@Controller("/api/")
+ * class ExampleClass {
+ *   // functions that handle endpoints starting with `/api/`
+ * }
+ * ```
  */
 export const Controller =
-  (pathPrefix: string = "") =>
-  (target: ControllerClass, context?: ClassDecoratorContext): void => {
+  (pathPrefix: string = ""): ClassDecorator => (target, context): void => {
     debug(
       `invoking ControllerDecorator for ${target.name} -`,
       "runtime provides context:",