Repository navigation
Highlights
router now has built-in tracing 🎉
Until now, observability tools had to monkey-patch the router to see what happens inside a request. That breaks easily and every tool did it in its own way.
router now publishes to the Node.js diagnostics_channel through a TracingChannel named express.router.request. Every middleware, route handler, error handler and router.param() callback is traced, and the context includes the matched route pattern (/users/:id, not /users/42). With no subscribers, the tracing work is skipped.
const dc = require('node:diagnostics_channel')
function report (ctx) {
const ms = (performance.now() - ctx.startTime).toFixed(1)
const name = ctx.handler.name || '<anonymous>'
console.log(`${ctx.req.method} ${ctx.route} ${name} ${ms}ms`, ctx.error ? 'failed' : 'ok')
}
dc.tracingChannel('express.router.request').subscribe({
start (ctx) { ctx.startTime = performance.now() },
// `result` or `error` at `end` means the handler was synchronous
end (ctx) { if ('result' in ctx || 'error' in ctx) report(ctx) },
asyncEnd (ctx) { report(ctx) }
})
// GET /users/:id getUser 23.1ms ok
// DELETE /users/:id removeUser 0.1ms failedExpress 5 uses this router, so Express apps get the same channel once they update. The full context and the event rules are in the Diagnostics section of the README.
Thanks to @logaretm for driving this work (#196, #207, #223) and to @bjohansebas for the param callbacks and error attribution (#215).
List the registered routes with router.listRoutes()
A long requested feature: you can now ask a router what it has registered, without reading its internal stack.
const router = Router()
const admin = Router()
admin.get('/stats', (req, res) => res.end('ok'))
router.use('/admin', admin)
router.route('/users/:id').get(getUser).delete(removeUser)
router.listRoutes()
// [
// { path: '/admin', methods: undefined, router: admin },
// { path: '/users/:id', methods: ['GET', 'DELETE', 'HEAD'], router: undefined }
// ]
admin.listRoutes()
// [ { path: '/stats', methods: ['GET', 'HEAD'], router: undefined } ]Mounted routers are not resolved for you, call listRoutes() on the router property to go deeper. Thanks to @bjohansebas (#174).
TypeScript declarations are included
Router and Route now ship with their own types, and you can describe what your middleware adds by augmenting Request and Response in the router module. Thanks to @gameroman (#197).
Also in this release
- Malformed route parameters now set
err.statusCodeto 400 (#171) req.urlkeeps its path separator when a mounted layer rewrites it (#206)- Route parameters without
%are no longer decoded, which is faster (#188) - Layer match results are now local to each request (#216). If you rely on the internal
Layer, note that it no longer storeskeys,paramsorpath, andlayer.match()returns an object orfalse
What's Changed
- [StepSecurity] Apply security best practices by @step-security-bot in #161
- chore: add funding to package.json by @bjohansebas in #172
- Fix: Correct typos in README by @triplechecker-com in #173
- ci: add node 24 by @bjohansebas in #175
- feat(test): allow dispatch trigger on ci test workflow by @wesleytodd in #177
- build(deps): bump github/codeql-action from 3.27.9 to 3.30.5 by @dependabot[bot] in #182
- feat: add request layer lifecycle TracingChannels by @logaretm in #196
- build(deps): bump actions/checkout from 4.2.2 to 6.0.2 by @dependabot[bot] in #198
- build(deps): bump actions/download-artifact from 4.3.0 to 8.0.1 by @dependabot[bot] in #201
- build(deps-dev): bump mocha from 10.2.0 to 10.8.2 by @dependabot[bot] in #166
- build(deps): bump ossf/scorecard-action from 2.4.0 to 2.4.3 by @dependabot[bot] in #179
- build(deps): bump github/codeql-action from 3.30.5 to 4.36.0 by @dependabot[bot] in #200
- fix: set statusCode property on error in layer.js to ensure proper error handling by @ale-grosselle in #171
- perf: enhance decodeParam to check for encoded values by @nigrosimone in #188
- ci: expand Node.js matrix and group Dependabot updates by @bjohansebas in #208
- build(deps): bump actions/upload-artifact from 4.5.0 to 7.0.1 by @dependabot[bot] in #199
- build(deps): bump the github-actions group across 1 directory with 10 updates by @dependabot[bot] in #209
- feat: add typescript types by @gameroman in #197
- feat: add listRoutes method to list registered routes by @bjohansebas in #174
- feat: expose the matched route pattern on the tracing context by @logaretm in #207
- fix: trace parameter callbacks and preserve error attribution by @bjohansebas in #215
- build(deps-dev): bump the npm group with 2 updates by @dependabot[bot] in #220
- build(deps): bump the github-actions group with 6 updates by @dependabot[bot] in #219
- refactor: keep layer match results local to each request by @bjohansebas in #216
- fix: preserve a req.url rewritten inside a mounted layer by @bilashcse in #206
- feat: disambiguate terminal end event and error handler thrown errors by @logaretm in #223
- chore(ci): npm-publish via stage publish by @UlisesGascon in #224
- 2.3.0 by @UlisesGascon in #222
New Contributors
- @step-security-bot made their first contribution in #161
- @triplechecker-com made their first contribution in #173
- @dependabot[bot] made their first contribution in #182
- @logaretm made their first contribution in #196
- @ale-grosselle made their first contribution in #171
- @nigrosimone made their first contribution in #188
- @gameroman made their first contribution in #197
- @bilashcse made their first contribution in #206
Full Changelog: v2.2.0...v2.3.0