feat: add getRoutes method to list registered routes

index.js

@@ -17,6 +17,7 @@ const Layer = require('./lib/layer')
 const { METHODS } = require('node:http')
 const parseUrl = require('parseurl')
 const Route = require('./lib/route')
+const pathRegexp = require('path-to-regexp')
 const debug = require('debug')('router')
 const deprecate = require('depd')('router')
 
@@ -441,6 +442,33 @@ Router.prototype.route = function route (path) {
   return route
 }
 
+/**
+ * List all registered routes.
+ *
+ * @return {Array} An array of route paths
+ * @public
+ */
+Router.prototype.mapRoutes = function mapRoutes () {
+  const routes = []
+  const stack = this.stack
+
+  const options = {
+    strict: this.strict,
+    caseSensitive: this.caseSensitive
+  }
+
+  const routeMap = new Map()
+
+  collectRoutes(stack, '', routeMap, options)
+
+  // Convert Map to array of route objects
+  for (const [path, methods] of routeMap.entries()) {
+    routes.push({ path, ...methods })
+  }
+
+  return routes
+}
+
 // create Router#VERB functions
 methods.concat('all').forEach(function (method) {
   Router.prototype[method] = function (path) {
@@ -450,6 +478,101 @@ methods.concat('all').forEach(function (method) {
   }
 })
 
+/**
+ * Add a route to the map with the given path and methods.
+ * @param {Map} routeMap
+ * @param {string} path
+ * @param {Array} methods
+ * @private
+ */
+function addRouteToMap (routeMap, path, methods, options) {
+  if (routeMap.has(path)) {
+    const existingMethods = routeMap.get(path)
+    for (const method of methods) {
+      if (!existingMethods.methods.includes(method)) {
+        existingMethods.methods.push(method)
+      }
+    }
+  } else {
+    const { keys } = pathRegexp.pathToRegexp(path)
+
+    routeMap.set(
+      path,
+      {
+        methods: [...methods],
+        keys,
+        options: { strict: options.strict, caseSensitive: options.caseSensitive }
+      }
+    )
+  }
+}
+
+/**
+ * Normalize a path by removing trailing slashes.
+ * @param {string} path
+ * @return {string} normalized path
+ * @private
+ */
+function normalizePath (path) {
+  if (typeof path !== 'string') {
+    return path
+  }
+
+  if (path.endsWith('/') && path.length > 1) {
+    return path.slice(0, -1)
+  }
+
+  return path
+}
+
+/**
+ * Collect routes from a router stack recursively.
+ *
+ * @param {Array} stack - The router stack to collect routes from
+ * @param {string} prefix - The path prefix to prepend to routes
+ * @param {Map} routeMap - The map to store collected routes
+ * @private
+ */
+function collectRoutes (stack, prefix, routeMap, options) {
+  for (const layer of stack) {
+    // for routes without a .use
+    if (layer.pathPatterns && layer.route) {
+      const methods = Object.keys(layer.route.methods).map((method) => method.toUpperCase())
+
+      if (Array.isArray(layer.pathPatterns)) {
+        for (const pathPattern of layer.pathPatterns) {
+          const fullPath = prefix === '/' ? pathPattern : normalizePath(prefix) + pathPattern
+          addRouteToMap(routeMap, fullPath, methods, options)
+        }
+      } else {
+        const fullPath = prefix === '/' ? layer.pathPatterns : prefix + layer.pathPatterns
+        addRouteToMap(routeMap, fullPath, methods, options)
+      }
+    }
+
+    // for layers with a .use (mounted routers)
+    if (layer.pathPatterns && layer.handle && layer.handle.stack && !layer.route) {
+      if (Array.isArray(layer.pathPatterns)) {
+        for (const pathPattern of layer.pathPatterns) {
+          const pathPrefix = prefix === '/' ? normalizePath(pathPattern) : prefix + normalizePath(pathPattern)
+
+          collectRoutes(layer.handle.stack, pathPrefix, routeMap, {
+            strict: layer.handle.strict,
+            caseSensitive: layer.handle.caseSensitive
+          })
+        }
+      } else {
+        const pathPrefix = prefix === '/' ? normalizePath(layer.pathPatterns) : prefix + normalizePath(layer.pathPatterns)
+
+        collectRoutes(layer.handle.stack, pathPrefix, routeMap, {
+          strict: layer.handle.strict,
+          caseSensitive: layer.handle.caseSensitive
+        })
+      }
+    }
+  }
+}
+
 /**
  * Generate a callback that will make an OPTIONS response.
  *

lib/layer.js

@@ -43,7 +43,10 @@ function Layer (path, options, fn) {
   this.keys = []
   this.name = fn.name || '<anonymous>'
   this.params = undefined
+  // path is determinate in runtime execution
   this.path = undefined
+
+  this.pathPatterns = path
   this.slash = path === '/' && opts.end === false
 
   function matcher (_path) {

test/mapRoutes.js

@@ -0,0 +1,189 @@
+const { it, describe } = require('mocha')
+const Router = require('..')
+const utils = require('./support/utils')
+
+const assert = utils.assert
+
+describe('mapRoutes', function () {
+  it('should return empty array for router with no registered routes', function () {
+    const router = new Router()
+
+    assert.deepStrictEqual(router.mapRoutes(), [])
+  })
+
+  it('should map different route types including strings, regex patterns, and parameter routes', function () {
+    const router = new Router()
+
+    router.all('/', noop)
+    router.route('/test2/')
+    router.route('/test/').get(noop)
+    // With regex patterns path-to-regexp fail
+    // router.all(/^\/[a-z]oo$/, noop)
+    router.get(['/foo', '/bar'], noop)
+    router.post('/:id/setting/:thing', noop)
+
+    assert.deepStrictEqual(router.mapRoutes(),
+      [
+        { path: '/', methods: ['_ALL'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+        { path: '/test2/', methods: [], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+        { path: '/test/', methods: ['GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+        // { path: '/^\\/[a-z]oo$/', methods: ['_ALL'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+        { path: '/foo', methods: ['GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+        { path: '/bar', methods: ['GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+        { path: '/:id/setting/:thing', methods: ['POST'], keys: [{ name: 'id', type: 'param' }, { name: 'thing', type: 'param' }], options: { strict: undefined, caseSensitive: undefined } }
+      ])
+  })
+
+  it('should consolidate HTTP methods for routes registered multiple times', function () {
+    const router = new Router()
+    router.post(['/test', '/test2'], noop)
+
+    for (let i = 0; i < 20; i++) {
+      router.get(['/test', '/test3'], noop)
+    }
+
+    router.put('/test3', noop)
+
+    assert.deepStrictEqual(router.mapRoutes(), [
+      { path: '/test', methods: ['POST', 'GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/test2', methods: ['POST'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/test3', methods: ['GET', 'PUT'], keys: [], options: { strict: undefined, caseSensitive: undefined } }
+    ])
+  })
+
+  it('should deduplicate routes and flatten nested router paths correctly', function () {
+    const router = new Router()
+    const inner = new Router()
+    router.post('/test', noop)
+
+    for (let i = 0; i < 100; i++) {
+      router.get('/test', noop)
+    }
+
+    for (let i = 0; i < 20; i++) {
+      inner.get('/test', noop)
+    }
+
+    router.use(['/test/', '/test2', '/test3'], inner)
+    router.use('/test4/', inner)
+
+    assert.deepStrictEqual(router.mapRoutes(), [
+      { path: '/test', methods: ['POST', 'GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/test/test', methods: ['GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/test2/test', methods: ['GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/test3/test', methods: ['GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/test4/test', methods: ['GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } }
+    ])
+  })
+
+  it('should handle complex nested router hierarchies with multiple mount points', function () {
+    const router = new Router()
+    const inner = new Router()
+    const subinner = new Router()
+
+    subinner.put('/t5', noop)
+    // subinner.all(/^\/[a-z]oo$/, noop)
+    subinner.use(noop)
+
+    inner.use('/t3', subinner)
+    inner.all('/t4', noop)
+    inner.get('/', noop)
+    inner.use(noop)
+
+    router.use('/t2', inner)
+    router.use(['/t5', '/t7'], inner)
+
+    router.use(noop)
+    router.use('/test1', noop)
+
+    assert.deepStrictEqual(router.mapRoutes(), [
+      { path: '/t2/t3/t5', methods: ['PUT'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      // { path: '/t2/t3/^\\/[a-z]oo$/', methods: ['_ALL'], keys: [],options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/t2/t4', methods: ['_ALL'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/t2/', methods: ['GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/t5/t3/t5', methods: ['PUT'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      // { path: '/t5/t3/^\\/[a-z]oo$/', methods: ['_ALL'], keys: [],options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/t5/t4', methods: ['_ALL'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/t5/', methods: ['GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/t7/t3/t5', methods: ['PUT'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      // { path: '/t7/t3/^\\/[a-z]oo$/', methods: ['_ALL'], keys: [],options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/t7/t4', methods: ['_ALL'], keys: [], options: { strict: undefined, caseSensitive: undefined } },
+      { path: '/t7/', methods: ['GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } }
+    ])
+  })
+
+  it('should avoid double slashes when mounting routers at root path', function () {
+    const router = new Router()
+    const subRouter = new Router()
+
+    subRouter.get('/api', () => {})
+    router.use('/', subRouter)
+
+    const routes = router.mapRoutes()
+
+    assert.deepStrictEqual(routes, [
+      { path: '/api', methods: ['GET'], keys: [], options: { strict: undefined, caseSensitive: undefined } }
+    ])
+  })
+
+  it('should inherit router options correctly through nested hierarchies', function () {
+    const router = new Router({ strict: true, caseSensitive: true })
+    const inner = new Router({ strict: true, caseSensitive: false })
+    const subinner = new Router({ strict: false, caseSensitive: false })
+
+    subinner.put('/t5', noop)
+    subinner.use(noop)
+
+    inner.use('/t3', subinner)
+    inner.all('/t4', noop)
+    inner.get('/', noop)
+    inner.use(noop)
+
+    router.use('/t2', inner)
+    router.use(['/t5', '/t7'], inner)
+
+    router.use(noop)
+    router.get('/test', noop)
+
+    assert.deepStrictEqual(router.mapRoutes(), [
+      { path: '/t2/t3/t5', methods: ['PUT'], keys: [], options: { strict: false, caseSensitive: false } },
+      { path: '/t2/t4', methods: ['_ALL'], keys: [], options: { strict: true, caseSensitive: false } },
+      { path: '/t2/', methods: ['GET'], keys: [], options: { strict: true, caseSensitive: false } },
+      { path: '/t5/t3/t5', methods: ['PUT'], keys: [], options: { strict: false, caseSensitive: false } },
+      { path: '/t5/t4', methods: ['_ALL'], keys: [], options: { strict: true, caseSensitive: false } },
+      { path: '/t5/', methods: ['GET'], keys: [], options: { strict: true, caseSensitive: false } },
+      { path: '/t7/t3/t5', methods: ['PUT'], keys: [], options: { strict: false, caseSensitive: false } },
+      { path: '/t7/t4', methods: ['_ALL'], keys: [], options: { strict: true, caseSensitive: false } },
+      { path: '/t7/', methods: ['GET'], keys: [], options: { strict: true, caseSensitive: false } },
+      { path: '/test', methods: ['GET'], keys: [], options: { strict: true, caseSensitive: true } }
+    ])
+  })
+
+  it('should handle routers with mixed options when mounted at same path', function () {
+    const router = new Router({ strict: true, caseSensitive: true })
+    const inner = new Router({ strict: true, caseSensitive: false })
+    const otherInner = new Router({ strict: true, caseSensitive: true })
+    const otherInner2 = new Router({ strict: true, caseSensitive: false })
+
+    otherInner2.put('/:t5', noop)
+    otherInner2.get('/:t6', noop)
+
+    otherInner.put('/:t5', noop)
+    otherInner.post('/:t6', noop)
+
+    inner.use('/t2', otherInner)
+    inner.use('/t2', otherInner2)
+
+    router.use(inner)
+
+    assert.deepStrictEqual(router.mapRoutes(), [
+      { path: '/t2/:t5', methods: ['PUT'], keys: [{ name: 't5', type: 'param' }], options: { strict: true, caseSensitive: true } },
+      // The current implementation merges methods for the same path, even if options differ. It shouldn't
+      { path: '/t2/:t6', methods: ['POST', 'GET'], keys: [{ name: 't6', type: 'param' }], options: { strict: true, caseSensitive: true } }
+      // { path: '/t2/t6', methods: ['POST'], options: { strict: true, caseSensitive: true } }
+      // { path: '/t2/t6', methods: ['GET'], options: { strict: true, caseSensitive: false } },
+    ])
+  })
+})
+
+function noop () {}