typespec-hono 0.6.0 → 0.8.0

package/dist/src/app.d.ts

@@ -23,7 +23,20 @@ import { type EmittedRoute, type EmittedService } from "typespec-http-zod";
  * operation (validators included) over a template no router could mount. What a request body must
  * look like does not depend on that.
  */
-export declare function toHonoPath(template: string, refuse: (template: string, name: string) => void): string;
+export declare function toHonoPath(template: string, refuse: (template: string, name: string) => void, 
+/**
+ * Wire names the document says carry RFC 6570 reserved expansion, so their value may contain `/`.
+ *
+ * **A hierarchical identifier is ONE value, not several segments.** An Obsidian note is
+ * `areas/health.md`; an S3 key and a GitHub file path are the same shape. A router that stops at
+ * the first `/` binds `areas` and 404s the rest. Hono spells the greedy form `:name{.+}`.
+ *
+ * Read from `EmittedRoute.reservedPathParameters`, which the library resolves from `allowReserved`
+ * on the parameter. **Never from the template**: the operator does not survive to `route.path`,
+ * `@typespec/http` strips it, and it can also be set with no operator in the template at all, so
+ * the template is a derived artefact rather than the source of truth.
+ */
+reserved?: ReadonlySet<string>): string;
 /** The one thing a Hono server cannot express, handed back rather than thrown. */
 export interface RenderRefusals {
     readonly unsupportedPathTemplate: (route: EmittedRoute, template: string, name: string) => void;

package/dist/src/app.js

@@ -29,12 +29,32 @@ const PLAIN_PATH_PARAMETER = /^[A-Za-z0-9_.~-]+$/;
  * operation (validators included) over a template no router could mount. What a request body must
  * look like does not depend on that.
  */
-export function toHonoPath(template, refuse) {
+export function toHonoPath(template, refuse, 
+/**
+ * Wire names the document says carry RFC 6570 reserved expansion, so their value may contain `/`.
+ *
+ * **A hierarchical identifier is ONE value, not several segments.** An Obsidian note is
+ * `areas/health.md`; an S3 key and a GitHub file path are the same shape. A router that stops at
+ * the first `/` binds `areas` and 404s the rest. Hono spells the greedy form `:name{.+}`.
+ *
+ * Read from `EmittedRoute.reservedPathParameters`, which the library resolves from `allowReserved`
+ * on the parameter. **Never from the template**: the operator does not survive to `route.path`,
+ * `@typespec/http` strips it, and it can also be set with no operator in the template at all, so
+ * the template is a derived artefact rather than the source of truth.
+ */
+reserved = new Set()) {
     return template.replace(/\{([^}]+)\}/g, (match, name) => {
-        if (PLAIN_PATH_PARAMETER.test(name))
-            return `:${name}`;
-        refuse(template, name);
-        return match;
+        /**
+         * **The name check comes FIRST and is unconditional.** A name Hono cannot carry is refused
+         * whether or not it is reserved: greedy matching does not make a space or a `+` in a parameter
+         * name expressible, and letting one through because another flag was set would mount a route
+         * matching the wrong requests rather than one that fails.
+         */
+        if (!PLAIN_PATH_PARAMETER.test(name)) {
+            refuse(template, name);
+            return match;
+        }
+        return reserved.has(name) ? `:${name}{.+}` : `:${name}`;
     });
 }
 /**
@@ -248,7 +268,7 @@ basePaths = [],
  * audience is wider.
  */
 securityFor) {
-    const entries = emitted.routes.flatMap((route) => {
+    const mounted = emitted.routes.flatMap((route) => {
         let dispatched;
         const names = emitted.schemaNames.get(route.operationId);
         // The library declares a `Responses` const for every operation, so a missing entry is a bug in
@@ -291,6 +311,7 @@ securityFor) {
         }
         return [{ route, names, validators, dispatched }];
     });
+    const entries = mounted;
     /**
      * **One registration per verb+path, not per operation.**
      *
@@ -385,7 +406,7 @@ securityFor) {
         /** A HEAD with no GET beside it: registered under GET, and guarded so only a HEAD reaches it. */
         const headOnly = plainGroups.length === 0 && headGroups.length > 0;
         const method = HONO_METHOD[registrationVerbOf(route.verb)] ?? "on";
-        const path = toHonoPath(route.path, (template, name) => refuse.unsupportedPathTemplate(route, template, name));
+        const path = toHonoPath(route.path, (template, name) => refuse.unsupportedPathTemplate(route, template, name), new Set(route.reservedPathParameters));
         /**
          * A route inside a sub-app is registered RELATIVE to the prefix it is mounted at.
          *
@@ -703,6 +724,27 @@ securityFor) {
      * check cannot be wrong in the direction that breaks a build.
      */
     const dispatchesBody = entries.some((entry) => entry.dispatched !== undefined);
+    /**
+     * **Imported only where a route actually validates something, like every other value import here.**
+     *
+     * This one was unconditional while the three around it were not, and the comment above them stated
+     * the rule it was breaking. A service whose operations declare no parameters at all -- two bare
+     * `GET`s, which is where a health check starts and therefore where a new consumer starts -- emitted
+     * an import nothing used, and `tsp compile` reported success:
+     * `TS6133: 'zValidator' is declared but its value is never read`.
+     *
+     * Counted from the same filtered list the middleware is rendered from, so it cannot disagree with
+     * what was emitted: a dispatched body's validator is `byContentType`, not a `zValidator`.
+     */
+    /**
+     * **`z` is only ever reached through `z.infer`**, which appears where an operation has an input
+     * type or a response body. A service whose every operation takes nothing and returns `void` names
+     * neither, so the import was written and never used:
+     * `TS6133: 'z' is declared but its value is never read`. Same shape as the `zValidator` one above,
+     * one step further along.
+     */
+    const usesZod = entries.some((entry) => inputTypeOf(entry) !== undefined || entry.names.response !== undefined);
+    const validates = entries.some((entry) => entry.validators.filter(([target]) => entry.dispatched === undefined || target !== VALIDATOR_TARGET.body).length > 0);
     const runtimeModule = JSON.stringify(emitted.options.runtimeModule);
     /**
      * **One base sub-app, mounted with `app.route()`. Hono's own nesting, not a rewritten path on
@@ -714,10 +756,8 @@ securityFor) {
     const usesBasePath = basePaths.length > 0;
     const needsHonoValue = subApps.size > 0 || usesBasePath;
     return `${GENERATED_BANNER}
-import { zValidator } from "@hono/zod-validator";
-${needsHonoValue ? 'import { Hono } from "hono";\nimport type { Context, Input } from "hono";' : 'import type { Context, Hono, Input } from "hono";'}
-import { z } from "zod";
-import type { AppEnv, Awaitable, Ctx, Result, RouteDeps } from ${runtimeModule};${negotiates ? `\nimport { selectContentType } from ${runtimeModule};` : ""}${guardsHead ? `\nimport { headOnly } from ${runtimeModule};` : ""}${dispatchesBody ? `\nimport { byContentType } from ${runtimeModule};` : ""}
+${validates ? 'import { zValidator } from "@hono/zod-validator";\n' : ""}${needsHonoValue ? 'import { Hono } from "hono";\nimport type { Context, Input } from "hono";' : 'import type { Context, Hono, Input } from "hono";'}
+${usesZod ? 'import { z } from "zod";\n' : ""}import type { AppEnv, Awaitable, Ctx, Result, RouteDeps } from ${runtimeModule};${negotiates ? `\nimport { selectContentType } from ${runtimeModule};` : ""}${guardsHead ? `\nimport { headOnly } from ${runtimeModule};` : ""}${dispatchesBody ? `\nimport { byContentType } from ${runtimeModule};` : ""}
 ${imports}
 /**
  * One method per operation, each concretely typed from the schemas it validates against.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-hono",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "TypeSpec emitter: generate a Hono server, and the Zod validators it enforces, from an HTTP service definition, agreeing with the OpenAPI document @typespec/openapi3 publishes from the same source.",
   "keywords": [
     "cloudflare-workers",
@@ -44,7 +44,7 @@
     "provenance": true
   },
   "dependencies": {
-    "typespec-http-zod": "^0.6.0"
+    "typespec-http-zod": "^0.10.0"
   },
   "devDependencies": {
     "@hono/zod-openapi": "^1.4.0",