@zuplo/cli 7.15.16 → 7.15.18

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/node_modules/@hono/node-server/dist/index.cjs +16 -4
  2. package/node_modules/@hono/node-server/dist/index.mjs +16 -4
  3. package/node_modules/@hono/node-server/package.json +1 -1
  4. package/node_modules/@zuplo/core/package.json +1 -1
  5. package/node_modules/@zuplo/graphql/package.json +1 -1
  6. package/node_modules/@zuplo/openapi-tools/package.json +1 -1
  7. package/node_modules/@zuplo/otel/out/esm/{chunk-6YAK7LGJ.js → chunk-BJ3PRHGL.js} +2 -2
  8. package/node_modules/@zuplo/otel/out/esm/chunk-BJ3PRHGL.js.map +1 -0
  9. package/node_modules/@zuplo/otel/out/esm/index.js +1 -1
  10. package/node_modules/@zuplo/otel/out/types/index.d.ts +10 -0
  11. package/node_modules/@zuplo/otel/package.json +1 -1
  12. package/node_modules/@zuplo/runtime/out/esm/{chunk-HMKEMARF.js → chunk-6KHAYHSW.js} +76 -78
  13. package/node_modules/@zuplo/runtime/out/esm/chunk-6KHAYHSW.js.map +1 -0
  14. package/node_modules/@zuplo/runtime/out/esm/index.js +1 -1
  15. package/node_modules/@zuplo/runtime/out/esm/mcp-gateway/index.js +1 -1
  16. package/node_modules/@zuplo/runtime/out/esm/mocks/index.js +1 -1
  17. package/node_modules/@zuplo/runtime/package.json +1 -1
  18. package/node_modules/router/HISTORY.md +67 -52
  19. package/node_modules/router/README.md +222 -2
  20. package/node_modules/router/index.d.ts +188 -0
  21. package/node_modules/router/index.js +86 -50
  22. package/node_modules/router/lib/layer.js +154 -47
  23. package/node_modules/router/lib/param.js +47 -0
  24. package/node_modules/router/lib/route.d.ts +118 -0
  25. package/node_modules/router/lib/route.js +14 -8
  26. package/node_modules/router/lib/symbols.js +4 -0
  27. package/node_modules/router/lib/tracing.js +173 -0
  28. package/node_modules/router/package.json +24 -9
  29. package/package.json +11 -11
  30. package/node_modules/@zuplo/otel/out/esm/chunk-6YAK7LGJ.js.map +0 -1
  31. package/node_modules/@zuplo/runtime/out/esm/chunk-HMKEMARF.js.map +0 -1
  32. /package/node_modules/@zuplo/runtime/out/esm/{chunk-HMKEMARF.js.LEGAL.txt → chunk-6KHAYHSW.js.LEGAL.txt} +0 -0
@@ -9,5 +9,5 @@
9
9
  * See https://zuplo.com/legal/eula for more information.
10
10
  */
11
11
 
12
- import{P as p,V as c,Z as u}from"../chunk-HMKEMARF.js";import"../chunk-KZBZ5KM5.js";import{a as d}from"../chunk-APWLPHXH.js";import"../chunk-R6UNMRUU.js";import"../chunk-5XXEIH5B.js";import"../chunk-5JGLAPFA.js";import{Y as i}from"../chunk-I65Y62VQ.js";import{a as o}from"../chunk-VXPFMOL5.js";function w(l={request:new Request("https://api.example.com")}){let e=[];function t(s){e.push(Promise.resolve(s))}return o(t,"waitUntil"),{context:new a({event:{waitUntil:t},route:l.route,originalRequest:l.request}),invokeResponse:o(async()=>{await Promise.all(e)},"invokeResponse")}}o(w,"createMockContext");var g={path:"/",methods:["GET"],handler:{module:{},export:"default"},raw:o(()=>({}),"raw")},a=class extends EventTarget{static{o(this,"MockZuploContext")}#e;#t;contextId;requestId;log;route;custom;incomingRequestProperties;parentContext;analyticsContext;constructor({event:e,route:t=g,parentContext:n,originalRequest:r}){super(),this.requestId=crypto.randomUUID(),this.contextId=crypto.randomUUID(),this.log={info:i.console.info,log:i.console.log,debug:i.console.debug,warn:i.console.warn,error:i.console.error,setLogProperties:o(()=>{},"setLogProperties")},this.custom={},this.route=t,this.incomingRequestProperties={ip:"203.0.113.7",asn:1234,asOrganization:"ORGANIZATION",city:"Seattle",region:"Washington",regionCode:"WA",colo:"SEA",continent:"NA",country:"US",postalCode:"98004",metroCode:"SEA",latitude:void 0,longitude:void 0,timezone:void 0,httpProtocol:void 0,clientCert:void 0,clientMtlsVerificationStatus:void 0,clientMtlsVerificationReason:void 0,clientCertFingerprintSha256:void 0,clientCertNotBefore:void 0,clientCertNotAfter:void 0,clientCertIssuerDn:void 0,clientCertSubjectDn:void 0},this.parentContext=n,this.#e=e,this.#t=r,this.analyticsContext=new c(this.requestId)}waitUntil(e){this.#e.waitUntil(e)}invokeInboundPolicy(e,t){throw new Error("Not implemented")}invokeOutboundPolicy(e,t,n){throw new Error("Not implemented")}invokeRoute(e,t){throw new Error("Not implemented")}addResponseSendingHook(e){throw new Error("Not implemented")}addResponseSendingFinalHook(e){throw new Error("Not implemented")}addPreRequestHandler(e,t){let n;try{n=u.getContextExtensions(this)}catch{n=u.initialize(this,new d(this.#t??new Request("https://api.example.com")))}n.preRequestPhase??="active",p(this,n,e,t)}get preRequestHandlers(){let e;try{e=u.getContextExtensions(this)}catch{return[]}return(e.preRequestState?.entries??[]).map(t=>({policyName:t.policyName,name:t.name}))}addEventListener(e,t,n){let r=o(s=>{try{typeof t=="function"?t(s):t.handleEvent(s)}catch(m){throw this.log.error(`Error invoking event ${e}. See following logs for details.`),m}},"wrapped");super.addEventListener(e,r,n)}};export{a as MockZuploContext,w as createMockContext};
12
+ import{P as p,V as c,Z as u}from"../chunk-6KHAYHSW.js";import"../chunk-KZBZ5KM5.js";import{a as d}from"../chunk-APWLPHXH.js";import"../chunk-R6UNMRUU.js";import"../chunk-5XXEIH5B.js";import"../chunk-5JGLAPFA.js";import{Y as i}from"../chunk-I65Y62VQ.js";import{a as o}from"../chunk-VXPFMOL5.js";function w(l={request:new Request("https://api.example.com")}){let e=[];function t(s){e.push(Promise.resolve(s))}return o(t,"waitUntil"),{context:new a({event:{waitUntil:t},route:l.route,originalRequest:l.request}),invokeResponse:o(async()=>{await Promise.all(e)},"invokeResponse")}}o(w,"createMockContext");var g={path:"/",methods:["GET"],handler:{module:{},export:"default"},raw:o(()=>({}),"raw")},a=class extends EventTarget{static{o(this,"MockZuploContext")}#e;#t;contextId;requestId;log;route;custom;incomingRequestProperties;parentContext;analyticsContext;constructor({event:e,route:t=g,parentContext:n,originalRequest:r}){super(),this.requestId=crypto.randomUUID(),this.contextId=crypto.randomUUID(),this.log={info:i.console.info,log:i.console.log,debug:i.console.debug,warn:i.console.warn,error:i.console.error,setLogProperties:o(()=>{},"setLogProperties")},this.custom={},this.route=t,this.incomingRequestProperties={ip:"203.0.113.7",asn:1234,asOrganization:"ORGANIZATION",city:"Seattle",region:"Washington",regionCode:"WA",colo:"SEA",continent:"NA",country:"US",postalCode:"98004",metroCode:"SEA",latitude:void 0,longitude:void 0,timezone:void 0,httpProtocol:void 0,clientCert:void 0,clientMtlsVerificationStatus:void 0,clientMtlsVerificationReason:void 0,clientCertFingerprintSha256:void 0,clientCertNotBefore:void 0,clientCertNotAfter:void 0,clientCertIssuerDn:void 0,clientCertSubjectDn:void 0},this.parentContext=n,this.#e=e,this.#t=r,this.analyticsContext=new c(this.requestId)}waitUntil(e){this.#e.waitUntil(e)}invokeInboundPolicy(e,t){throw new Error("Not implemented")}invokeOutboundPolicy(e,t,n){throw new Error("Not implemented")}invokeRoute(e,t){throw new Error("Not implemented")}addResponseSendingHook(e){throw new Error("Not implemented")}addResponseSendingFinalHook(e){throw new Error("Not implemented")}addPreRequestHandler(e,t){let n;try{n=u.getContextExtensions(this)}catch{n=u.initialize(this,new d(this.#t??new Request("https://api.example.com")))}n.preRequestPhase??="active",p(this,n,e,t)}get preRequestHandlers(){let e;try{e=u.getContextExtensions(this)}catch{return[]}return(e.preRequestState?.entries??[]).map(t=>({policyName:t.policyName,name:t.name}))}addEventListener(e,t,n){let r=o(s=>{try{typeof t=="function"?t(s):t.handleEvent(s)}catch(m){throw this.log.error(`Error invoking event ${e}. See following logs for details.`),m}},"wrapped");super.addEventListener(e,r,n)}};export{a as MockZuploContext,w as createMockContext};
13
13
  //# sourceMappingURL=index.js.map
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@zuplo/runtime",
3
3
  "type": "module",
4
- "version": "7.15.16",
4
+ "version": "7.15.18",
5
5
  "repository": "https://github.com/zuplo/zuplo",
6
6
  "author": "Zuplo, Inc.",
7
7
  "exports": {
@@ -1,11 +1,26 @@
1
- 2.2.0 / 2025-03-26
2
- ==================
1
+ 2.3.0
2
+ =====
3
+
4
+ * Add `router.listRoutes()` to list the registered routes
5
+ * Add `diagnostics_channel` tracing through the `express.router.request` `TracingChannel`
6
+ - Traces request handlers, error handlers and `router.param()` callbacks
7
+ - Exposes the matched route pattern as `route` on the tracing context
8
+ * Add TypeScript declarations for `Router` and `Route`
9
+ * perf: skip decoding route parameters without `%`
10
+ * Set `err.statusCode` to 400 for malformed route parameters
11
+ * Fix `req.url` losing the path separator when a mounted layer rewrites it
12
+ * Keep layer match results local to each request
13
+ - The internal `Layer` no longer stores `keys`, `params` or `path`
14
+ - The internal `layer.match()` returns `{ params, path, keys, pattern }` or `false` instead of a boolean
15
+
16
+ 2.2.0
17
+ =====
3
18
 
4
19
  * Remove `setImmediate` support check
5
20
  * Restore `debug` dependency
6
21
 
7
- 2.1.0 / 2025-02-10
8
- ==================
22
+ 2.1.0
23
+ =====
9
24
 
10
25
  * Updated `engines` field to Node@18 or higher
11
26
  * Remove `Object.setPrototypeOf` polyfill
@@ -16,8 +31,8 @@
16
31
  * Replace `utils-merge` dependency with `Object.assign`
17
32
  * deps: Remove unused dep `after`
18
33
 
19
- 2.0.0 / 2024-09-09
20
- ==================
34
+ 2.0.0
35
+ =====
21
36
 
22
37
  * Drop support for node <18
23
38
  * deps: path-to-regexp@^8.0.0
@@ -29,15 +44,15 @@
29
44
  - `:name+` becomes `*name` and thus equivalent to `*name` so I dropped those tests
30
45
  - Strings as regular expressions are fully removed, need to be converted to native regular expressions
31
46
 
32
- 2.0.0-beta.2 / 2024-03-20
33
- =========================
47
+ 2.0.0-beta.2
48
+ ============
34
49
 
35
50
  This incorporates all changes after 1.3.5 up to 1.3.8.
36
51
 
37
52
  * Add support for returned, rejected Promises to `router.param`
38
53
 
39
- 2.0.0-beta.1 / 2020-03-29
40
- =========================
54
+ 2.0.0-beta.1
55
+ ============
41
56
 
42
57
  This incorporates all changes after 1.3.3 up to 1.3.5.
43
58
 
@@ -60,8 +75,8 @@ This incorporates all changes after 1.3.3 up to 1.3.5.
60
75
  `/foo/*/bar` will match a literal `*` as the middle segment.
61
76
  * deps: setprototypeof@1.2.0
62
77
 
63
- 2.0.0-alpha.1 / 2018-07-27
64
- ==========================
78
+ 2.0.0-alpha.1
79
+ =============
65
80
 
66
81
  * Add basic support for returned, rejected Promises
67
82
  - Rejected Promises from middleware functions `next(error)`
@@ -73,42 +88,42 @@ This incorporates all changes after 1.3.3 up to 1.3.5.
73
88
  - Remove `DEBUG_FD` environment variable support
74
89
  - Support 256 namespace colors
75
90
 
76
- 1.3.8 / 2023-02-24
77
- ==================
91
+ 1.3.8
92
+ =====
78
93
 
79
94
  * Fix routing requests without method
80
95
 
81
- 1.3.7 / 2022-04-28
82
- ==================
96
+ 1.3.7
97
+ =====
83
98
 
84
99
  * Fix hanging on large stack of sync routes
85
100
 
86
- 1.3.6 / 2021-11-15
87
- ==================
101
+ 1.3.6
102
+ =====
88
103
 
89
104
  * Fix handling very large stacks of sync middleware
90
105
  * deps: safe-buffer@5.2.1
91
106
 
92
- 1.3.5 / 2020-03-24
93
- ==================
107
+ 1.3.5
108
+ =====
94
109
 
95
110
  * Fix incorrect middleware execution with unanchored `RegExp`s
96
111
  * perf: use plain object for internal method map
97
112
 
98
- 1.3.4 / 2020-01-24
99
- ==================
113
+ 1.3.4
114
+ =====
100
115
 
101
116
  * deps: array-flatten@3.0.0
102
117
  * deps: parseurl@~1.3.3
103
118
  * deps: setprototypeof@1.2.0
104
119
 
105
- 1.3.3 / 2018-07-06
106
- ==================
120
+ 1.3.3
121
+ =====
107
122
 
108
123
  * Fix JSDoc for `Router` constructor
109
124
 
110
- 1.3.2 / 2017-09-24
111
- ==================
125
+ 1.3.2
126
+ =====
112
127
 
113
128
  * deps: debug@2.6.9
114
129
  * deps: parseurl@~1.3.2
@@ -117,15 +132,15 @@ This incorporates all changes after 1.3.3 up to 1.3.5.
117
132
  * deps: setprototypeof@1.1.0
118
133
  * deps: utils-merge@1.0.1
119
134
 
120
- 1.3.1 / 2017-05-19
121
- ==================
135
+ 1.3.1
136
+ =====
122
137
 
123
138
  * deps: debug@2.6.8
124
139
  - Fix `DEBUG_MAX_ARRAY_LENGTH`
125
140
  - deps: ms@2.0.0
126
141
 
127
- 1.3.0 / 2017-02-25
128
- ==================
142
+ 1.3.0
143
+ =====
129
144
 
130
145
  * Add `next("router")` to exit from router
131
146
  * Fix case where `router.use` skipped requests routes did not
@@ -133,8 +148,8 @@ This incorporates all changes after 1.3.3 up to 1.3.5.
133
148
  * deps: setprototypeof@1.0.3
134
149
  * perf: add fast match path for `*` route
135
150
 
136
- 1.2.0 / 2017-02-17
137
- ==================
151
+ 1.2.0
152
+ =====
138
153
 
139
154
  * Skip routing when `req.url` is not set
140
155
  * deps: debug@2.6.1
@@ -144,15 +159,15 @@ This incorporates all changes after 1.3.3 up to 1.3.5.
144
159
  - Use same color for same namespace
145
160
  - deps: ms@0.7.2
146
161
 
147
- 1.1.5 / 2017-01-28
148
- ==================
162
+ 1.1.5
163
+ =====
149
164
 
150
165
  * deps: array-flatten@2.1.1
151
166
  * deps: setprototypeof@1.0.2
152
167
  - Fix using fallback even when native method exists
153
168
 
154
- 1.1.4 / 2016-01-21
155
- ==================
169
+ 1.1.4
170
+ =====
156
171
 
157
172
  * deps: array-flatten@2.0.0
158
173
  * deps: methods@~1.1.2
@@ -160,8 +175,8 @@ This incorporates all changes after 1.3.3 up to 1.3.5.
160
175
  * deps: parseurl@~1.3.1
161
176
  - perf: enable strict mode
162
177
 
163
- 1.1.3 / 2015-08-02
164
- ==================
178
+ 1.1.3
179
+ =====
165
180
 
166
181
  * Fix infinite loop condition using `mergeParams: true`
167
182
  * Fix inner numeric indices incorrectly altering parent `req.params`
@@ -170,8 +185,8 @@ This incorporates all changes after 1.3.3 up to 1.3.5.
170
185
  * deps: path-to-regexp@0.1.7
171
186
  - Fix regression with escaped round brackets and matching groups
172
187
 
173
- 1.1.2 / 2015-07-06
174
- ==================
188
+ 1.1.2
189
+ =====
175
190
 
176
191
  * Fix hiding platform issues with `decodeURIComponent`
177
192
  - Only `URIError`s are a 400
@@ -183,31 +198,31 @@ This incorporates all changes after 1.3.3 up to 1.3.5.
183
198
  * perf: skip attempting to decode zero length string
184
199
  * perf: use plain for loops
185
200
 
186
- 1.1.1 / 2015-05-25
187
- ==================
201
+ 1.1.1
202
+ =====
188
203
 
189
204
  * Fix issue where `next('route')` in `router.param` would incorrectly skip values
190
205
  * deps: array-flatten@1.1.0
191
206
  * deps: debug@~2.2.0
192
207
  - deps: ms@0.7.1
193
208
 
194
- 1.1.0 / 2015-04-22
195
- ==================
209
+ 1.1.0
210
+ =====
196
211
 
197
212
  * Use `setprototypeof` instead of `__proto__`
198
213
  * deps: debug@~2.1.3
199
214
  - Fix high intensity foreground color for bold
200
215
  - deps: ms@0.7.0
201
216
 
202
- 1.0.0 / 2015-01-13
203
- ==================
217
+ 1.0.0
218
+ =====
204
219
 
205
220
  * Fix crash from error within `OPTIONS` response handler
206
221
  * deps: array-flatten@1.0.2
207
222
  - Remove redundant code path
208
223
 
209
- 1.0.0-beta.3 / 2015-01-11
210
- =========================
224
+ 1.0.0-beta.3
225
+ ============
211
226
 
212
227
  * Fix duplicate methods appearing in OPTIONS responses
213
228
  * Fix OPTIONS responses to include the HEAD method properly
@@ -216,13 +231,13 @@ This incorporates all changes after 1.3.3 up to 1.3.5.
216
231
  * deps: debug@~2.1.1
217
232
  * deps: methods@~1.1.1
218
233
 
219
- 1.0.0-beta.2 / 2014-11-19
220
- =========================
234
+ 1.0.0-beta.2
235
+ ============
221
236
 
222
237
  * Match routes iteratively to prevent stack overflows
223
238
 
224
- 1.0.0-beta.1 / 2014-11-16
225
- =========================
239
+ 1.0.0-beta.1
240
+ ============
226
241
 
227
242
  * Initial release ported from Express 4.x
228
243
  - Altered to work without Express
@@ -18,6 +18,95 @@ This is a [Node.js](https://nodejs.org/en/) module available through the
18
18
  $ npm install router
19
19
  ```
20
20
 
21
+ ## TypeScript
22
+
23
+ TypeScript declarations are included. To describe properties added by your
24
+ middleware, augment the `Request` and `Response` interfaces in the `router` module:
25
+
26
+ ```ts
27
+ import Router from 'router'
28
+
29
+ declare module 'router' {
30
+ interface Request {
31
+ user?: { id: string }
32
+ }
33
+
34
+ interface Response {
35
+ requestId?: string
36
+ }
37
+ }
38
+
39
+ const router = Router()
40
+
41
+ router.use((req, res, next) => {
42
+ req.user = { id: '123' }
43
+ res.requestId = 'request-123'
44
+ next()
45
+ })
46
+
47
+ router.get('/me', (req, res) => {
48
+ if (res.requestId) res.setHeader('X-Request-Id', res.requestId)
49
+ res.end(req.user?.id)
50
+ })
51
+ ```
52
+
53
+ The augmentation applies to middleware, route handlers, error handlers, and
54
+ `router.param` callbacks. It only describes types; your middleware must assign
55
+ the property. Mark properties optional when they may not be present.
56
+
57
+ Literal route strings infer parameter names and values, following the approach
58
+ used by `@types/express-serve-static-core`:
59
+
60
+ ```ts
61
+ router.get('/users/:id', (req, res) => {
62
+ res.end(req.params.id.toUpperCase()) // id: string
63
+ })
64
+
65
+ router.get('/files{/*path}', (req, res) => {
66
+ res.end(req.params.path?.join('/')) // path: string[] | undefined
67
+ })
68
+ ```
69
+
70
+ Inference also applies to `router.use(path, ...)`, `router.route(path)`, and
71
+ `new Router.Route(path)`, including chained routing methods.
72
+
73
+ To declare route parameters explicitly, pass their type to a routing method or
74
+ to `Request`, `RequestHandler`, or `ErrorRequestHandler`:
75
+
76
+ ```ts
77
+ type UserParams = { id: string }
78
+
79
+ router.get<UserParams>('/users/:id', (req, res) => {
80
+ res.end(req.params.id.toUpperCase())
81
+ })
82
+
83
+ const showUser: Router.RequestHandler<UserParams> = (req, res) => {
84
+ res.end(req.params.id)
85
+ }
86
+
87
+ router.route('/users/:id').get<UserParams>(showUser)
88
+ ```
89
+
90
+ Dynamic strings, regular expressions, and path arrays keep the default parameter
91
+ values of `string | string[] | undefined` unless you supply an explicit type.
92
+ Use explicit types for syntax the inference does not cover, such as quoted
93
+ parameter names. These types do not validate the path or convert parameter values.
94
+
95
+ Path arrays can be mutable or readonly, including arrays declared with `as const`.
96
+
97
+ Use `RequestParamHandler` for reusable `router.param` callbacks:
98
+
99
+ ```ts
100
+ const loadUser: Router.RequestParamHandler = (req, res, next, value, name) => {
101
+ req.user = { id: String(value) }
102
+ next()
103
+ }
104
+
105
+ router.param('id', loadUser)
106
+ ```
107
+
108
+ Routing methods preserve extended router and route types when chaining.
109
+
21
110
  ## API
22
111
 
23
112
  ```js
@@ -65,6 +154,10 @@ consider it one for handling `OPTIONS` requests.
65
154
 
66
155
  * Note: If a `path` is specified, that `path` is stripped from the start of
67
156
  `req.url`.
157
+ * Note: The stripped `path` is added back to `req.url` when the middleware calls
158
+ `next()`. A `req.url` rewritten by the middleware is treated as relative to the
159
+ mount `path`, so rewriting `req.url` to `/index.html` inside a router mounted
160
+ on `/app` continues with `/app/index.html`.
68
161
 
69
162
  <!-- eslint-disable no-undef -->
70
163
 
@@ -143,6 +236,58 @@ router.param('user_id', function (req, res, next, id) {
143
236
  })
144
237
  ```
145
238
 
239
+ ### router.listRoutes()
240
+
241
+ Returns an array with one `{ path, methods, router }` object per path
242
+ registered on this router, in registration order.
243
+
244
+ - `path` is the path the route was registered with (a string or a `RegExp`).
245
+ Routes registered with an array of paths produce one entry per path.
246
+ - `methods` lists registered HTTP methods in uppercase, in the order they
247
+ were first registered. `.all()` is represented by `'*'` in that order to
248
+ indicate that the route accepts any HTTP method. Repeated registrations
249
+ do not add duplicate entries. The automatic `HEAD` for `GET` routes is
250
+ appended unless explicitly registered. For example, `.all(...).get(...)`
251
+ produces `['*', 'GET', 'HEAD']`, while `.get(...).all(...)` produces
252
+ `['GET', '*', 'HEAD']`. It is `undefined` for mounted routers, whose
253
+ internal routes determine the methods they handle.
254
+ An empty array means the route was created with
255
+ `router.route(path)` but has no handlers yet, so it matches no method.
256
+ - `router` is the mounted router instance for `.use(path, router)` entries,
257
+ otherwise `undefined`. Nested routes are not resolved recursively; consumers
258
+ can recurse themselves by calling `router.listRoutes()` when the mounted
259
+ router implements it. Note that `.use()`
260
+ entries match their path as a prefix, while route entries match the full
261
+ path.
262
+
263
+ Plain middleware functions registered with `.use()` are not listed.
264
+
265
+ ```js
266
+ const router = new Router()
267
+ const admin = new Router()
268
+
269
+ admin.get('/', (req, res) => {
270
+ res.end('Hello')
271
+ })
272
+
273
+ router.use('/admin', admin)
274
+
275
+ router.all('/:id', function (req, res) {
276
+ res.end('Hello')
277
+ })
278
+
279
+ console.log(router.listRoutes())
280
+ // [
281
+ // { path: '/admin', methods: undefined, router: admin },
282
+ // { path: '/:id', methods: ['*'], router: undefined }
283
+ // ]
284
+
285
+ console.log(admin.listRoutes())
286
+ // [
287
+ // { path: '/', methods: ['GET', 'HEAD'], router: undefined }
288
+ // ]
289
+ ```
290
+
146
291
  ### router.route(path)
147
292
 
148
293
  Creates an instance of a single `Route` for the given `path`.
@@ -316,7 +461,7 @@ var finalhandler = require('finalhandler')
316
461
  // this example is about the mergeParams option
317
462
  var opts = { mergeParams: true }
318
463
 
319
- // make a router with out special options
464
+ // make a router with our special options
320
465
  var router = Router(opts)
321
466
  var server = http.createServer(function onRequest (req, res) {
322
467
  // set something to be passed into the router
@@ -329,7 +474,7 @@ router.get('/', function (req, res) {
329
474
  res.statusCode = 200
330
475
  res.setHeader('Content-Type', 'text/plain; charset=utf-8')
331
476
 
332
- // with respond with the the params that were passed in
477
+ // with respond with the params that were passed in
333
478
  res.end(req.params.type + '\n')
334
479
  })
335
480
 
@@ -400,6 +545,81 @@ router.route('/pet/:id')
400
545
  server.listen(8080)
401
546
  ```
402
547
 
548
+ ## Diagnostics
549
+
550
+ `router` integrates with Node.js [`diagnostics_channel`](https://nodejs.org/api/diagnostics_channel.html)
551
+ via a [`TracingChannel`](https://nodejs.org/api/diagnostics_channel.html#class-tracingchannel)
552
+ named `express.router.request`. This lets observability tools (APMs, tracers,
553
+ loggers) hook into middleware and route handler execution without monkey-patching.
554
+
555
+ Each middleware, route handler, and `router.param()` callback invocation publishes
556
+ the standard tracing channel sub-events (`start`, `end`, `asyncStart`, `asyncEnd`,
557
+ `error`). The published context object contains:
558
+
559
+ - `req`: the incoming `http.IncomingMessage`
560
+ - `res`: the `http.ServerResponse`
561
+ - `layer`: the internal `Layer` associated with the invocation (exposes `.name`, `.rawPath`, `.handle`, etc.). For parameter callbacks, this is the layer whose parameters are being processed. Note that `Layer` is an internal implementation detail and its shape may change between releases.
562
+ - `handler`: the function being invoked. For parameter callbacks, this is the callback registered with `router.param()`, rather than `layer.handle`.
563
+ - `param`: the parameter name, such as `'id'`, present only for `router.param()` callbacks.
564
+ - `route`: the path pattern that matched, e.g. `'/users/:id'`. Route handlers get their route's path; middleware and mounted routers get the path they were registered with
565
+ - `error`: the error reported by the invocation, set when it calls `next(err)`, throws, or rejects. A throw or rejection always sets it, even when the error was already published upstream and isn't published again
566
+ - `incomingError`: the error an error handler received, only set for error handlers
567
+ - `errorHandler`: `true` when the layer is an error-handling middleware (4-arg signature)
568
+ - `result`: the value the invocation produced, as with `tracePromise`. A synchronous return value is set before `end`; for a promise it is the resolved value, set before `asyncStart`. It is not set when the invocation throws or rejects.
569
+
570
+ The `error` event is published once, on the handler or parameter callback where
571
+ the error originates, whether it calls `next(err)`, throws, or returns a rejected
572
+ promise, as soon as it happens. `result` or `error` being set at `end` means no
573
+ `asyncStart` or `asyncEnd` will follow. If an invocation calls `next(err)` and
574
+ then returns a promise, `error` is published before `end` but unset during it. An
575
+ error bubbling up through outer layers is not reported again. The `'route'` and
576
+ `'router'` routing signals are not treated as errors and will not publish to the
577
+ `error` channel.
578
+
579
+ Errors originating before an invocation is traced, or during route matching
580
+ (such as URI decoding), are not attributed to handlers that forward them. They
581
+ still reach error handlers and appear in those handlers' tracing contexts. If
582
+ an error handler creates a different error, that new error is published normally.
583
+
584
+ Parameter callbacks get the matched layer's path pattern in `route`. Use
585
+ `handler.name` to identify the callback; `layer.name` identifies the associated
586
+ layer. A cached parameter result does not invoke its callbacks again, so it does
587
+ not produce additional callback events.
588
+
589
+ Stores bound with `start.bindStore()` apply during handler invocation. Stores
590
+ bound with `asyncStart.bindStore()` apply during `asyncEnd` publication when a
591
+ returned promise settles.
592
+
593
+ When no subscribers are attached, handler execution skips tracing context
594
+ allocation and channel publishing. Error identities are tracked per request so
595
+ that subscribers attached later cannot attribute a forwarded error to its receiver.
596
+
597
+ ```js
598
+ const dc = require('node:diagnostics_channel')
599
+
600
+ const channel = dc.tracingChannel('express.router.request')
601
+
602
+ channel.subscribe({
603
+ start (ctx) {
604
+ ctx.startTime = process.hrtime.bigint()
605
+ },
606
+ end (ctx) {
607
+ // do whatever you need on synchronous completion
608
+ },
609
+ asyncStart (ctx) {
610
+ // do whatever you need when the async portion begins
611
+ },
612
+ asyncEnd (ctx) {
613
+ const durationNs = process.hrtime.bigint() - ctx.startTime
614
+ console.log('%s %s -> %s (%dns)',
615
+ ctx.req.method, ctx.req.url, ctx.handler.name || '<anonymous>', durationNs)
616
+ },
617
+ error (ctx) {
618
+ console.error('handler error in %s:', ctx.handler.name || '<anonymous>', ctx.error)
619
+ }
620
+ })
621
+ ```
622
+
403
623
  ## License
404
624
 
405
625
  [MIT](LICENSE)