@comity/router-path-to-regexp 0.9.0 → 0.9.1

package/README.md

@@ -29,7 +29,6 @@ This package does NOT:
 
 - `PathRouter`
 
-
 No exhaustive reference; see docs for constraints.
 ---
 
@@ -50,7 +49,3 @@ No exhaustive reference; see docs for constraints.
 ## Status
 
 Stable
-
-_Review Completed: 2026-07-25_
-_Reviewer: Hobiri MAGI (DeepSeek v4 Pro)_
-_Compliance Score: 99.5% (Green)_

package/dist/cjs/router.js

@@ -4,6 +4,27 @@ exports.PathRouter = void 0;
 const path_to_regexp_1 = require("path-to-regexp");
 /**
  * PathRouter is a router implementation that matches incoming HTTP requests based on their URL path and HTTP method. It supports static paths and can be extended to support dynamic path parameters in the future.
+ *
+ * @typeParam State - Route state type carried by the registered routes.
+ * @typeParam Services - Application service map carried by the registered routes.
+ *
+ * @remarks
+ * The constructor is generic in `State` and `Services` (with the same defaults
+ * as `Route`) so a service-typed route — `Route<{}, AppServices>` — is
+ * *checked* at registration instead of being rejected against `Route[]`'s
+ * erased defaults. All routes registered with one router must share the same
+ * state and service map; routes whose maps differ belong in separate routers
+ * (routers themselves are heterogeneous inside `Router[]`).
+ *
+ * The service typing deliberately stops at this boundary: matching returns
+ * the non-generic `RouteMatch`, whose `route` slot is `Route` with defaults.
+ * This is an intentional erasure, not an oversight — `HttpContext` is
+ * invariant in `Services` (its `resolve` return type is covariant in
+ * `Services` and its key is contravariant), so no erased route slot could
+ * accept a typed route soundly, and the request context handed to a handler
+ * at dispatch time is the kernel's real, fully-registered container at
+ * runtime regardless of the static type. The erase happens once, inside this
+ * constructor, immediately after the routes have been type-checked.
  */
 class PathRouter {
     #routes;
@@ -14,6 +35,9 @@ class PathRouter {
         this.#routes = routes
             .filter((r) => r.path)
             .map((r) => ({
+            // Local, justified erase: the routes were just checked against
+            // Route<State, Services>; storage and dispatch are the router's
+            // intentional erased boundary (see class JSDoc).
             route: r,
             match: (0, path_to_regexp_1.match)(r.path, { decode: decodeURIComponent }),
         }));

package/dist/esm/router.js

@@ -1,6 +1,27 @@
 import { match } from "path-to-regexp";
 /**
  * PathRouter is a router implementation that matches incoming HTTP requests based on their URL path and HTTP method. It supports static paths and can be extended to support dynamic path parameters in the future.
+ *
+ * @typeParam State - Route state type carried by the registered routes.
+ * @typeParam Services - Application service map carried by the registered routes.
+ *
+ * @remarks
+ * The constructor is generic in `State` and `Services` (with the same defaults
+ * as `Route`) so a service-typed route — `Route<{}, AppServices>` — is
+ * *checked* at registration instead of being rejected against `Route[]`'s
+ * erased defaults. All routes registered with one router must share the same
+ * state and service map; routes whose maps differ belong in separate routers
+ * (routers themselves are heterogeneous inside `Router[]`).
+ *
+ * The service typing deliberately stops at this boundary: matching returns
+ * the non-generic `RouteMatch`, whose `route` slot is `Route` with defaults.
+ * This is an intentional erasure, not an oversight — `HttpContext` is
+ * invariant in `Services` (its `resolve` return type is covariant in
+ * `Services` and its key is contravariant), so no erased route slot could
+ * accept a typed route soundly, and the request context handed to a handler
+ * at dispatch time is the kernel's real, fully-registered container at
+ * runtime regardless of the static type. The erase happens once, inside this
+ * constructor, immediately after the routes have been type-checked.
  */
 export class PathRouter {
     #routes;
@@ -11,6 +32,9 @@ export class PathRouter {
         this.#routes = routes
             .filter((r) => r.path)
             .map((r) => ({
+            // Local, justified erase: the routes were just checked against
+            // Route<State, Services>; storage and dispatch are the router's
+            // intentional erased boundary (see class JSDoc).
             route: r,
             match: match(r.path, { decode: decodeURIComponent }),
         }));

package/dist/types/router.d.ts

@@ -1,13 +1,34 @@
 import type { Route, RouteMatch, Router, RouteResolutionContext } from "@comity/router";
 /**
  * PathRouter is a router implementation that matches incoming HTTP requests based on their URL path and HTTP method. It supports static paths and can be extended to support dynamic path parameters in the future.
+ *
+ * @typeParam State - Route state type carried by the registered routes.
+ * @typeParam Services - Application service map carried by the registered routes.
+ *
+ * @remarks
+ * The constructor is generic in `State` and `Services` (with the same defaults
+ * as `Route`) so a service-typed route — `Route<{}, AppServices>` — is
+ * *checked* at registration instead of being rejected against `Route[]`'s
+ * erased defaults. All routes registered with one router must share the same
+ * state and service map; routes whose maps differ belong in separate routers
+ * (routers themselves are heterogeneous inside `Router[]`).
+ *
+ * The service typing deliberately stops at this boundary: matching returns
+ * the non-generic `RouteMatch`, whose `route` slot is `Route` with defaults.
+ * This is an intentional erasure, not an oversight — `HttpContext` is
+ * invariant in `Services` (its `resolve` return type is covariant in
+ * `Services` and its key is contravariant), so no erased route slot could
+ * accept a typed route soundly, and the request context handed to a handler
+ * at dispatch time is the kernel's real, fully-registered container at
+ * runtime regardless of the static type. The erase happens once, inside this
+ * constructor, immediately after the routes have been type-checked.
  */
-export declare class PathRouter implements Router {
+export declare class PathRouter<State = Record<string, unknown>, Services extends Record<keyof Services, unknown> = Record<string, unknown>> implements Router {
     #private;
     /**
      * @param routes - An array of Route objects that define the routing rules for this router.
      */
-    constructor(routes: Route[]);
+    constructor(routes: Route<State, Services>[]);
     /**
      * Matches an incoming HTTP request against the defined routes.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comity/router-path-to-regexp",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "path-to-regexp adapter for Comity applications.",
   "type": "module",
   "private": false,
@@ -58,13 +58,13 @@
   "sideEffects": false,
   "peerDependencies": {
     "path-to-regexp": "^8.0.0",
-    "@comity/router": "0.9.0"
+    "@comity/router": "0.9.1"
   },
   "dependencies": {
-    "@comity/router": "0.9.0"
+    "@comity/router": "0.9.1"
   },
   "devDependencies": {
-    "@types/node": "^24.13.4",
+    "@types/node": "^24.19.1",
     "path-to-regexp": "^8.4.2",
     "typescript": "^5.9.3"
   },