@ditojs/router 1.24.0 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ditojs/router",
-  "version": "1.24.0",
+  "version": "1.25.0",
   "type": "module",
   "description": "Dito.js Router – Dito.js is a declarative and modern web framework, based on Objection.js, Koa.js and Vue.js",
   "repository": "https://github.com/ditojs/dito/tree/master/packages/router",
@@ -21,7 +21,7 @@
     "node >= 18"
   ],
   "dependencies": {
-    "@ditojs/utils": "^1.24.0"
+    "@ditojs/utils": "^1.25.0"
   },
   "keywords": [
     "route",
@@ -30,6 +30,6 @@
     "koa",
     "dito"
   ],
-  "gitHead": "0ca96ce0335509daa9ebbac278ae2d346015baad",
+  "gitHead": "29e7f8d8c613c48a856d90d1ee876e85c8d84c08",
   "readme": "# Dito.js Router\n\nDito.js is a declarative and modern web framework with a focus on API driven\ndevelopment, based on Koa.js, Objection.js and Vue.js\n\nReleased in 2018 under the MIT license, with support by https://lineto.com/\n\nDito.js Router is a high performance, tree-based, framework agnostic HTTP\nrouter, based on [trek-router](https://github.com/trekjs/router), which in turn\nis inspired by [Echo](https://github.com/labstack/echo)'s Router.\n\n## How does it work?\n\nThe router relies on a tree structure which makes heavy use of common\nprefixes, essentially a [prefix tree](https://en.wikipedia.org/wiki/Trie).\n\n## Usage\n\n```js\nimport Koa from 'koa'\nimport compose from 'koa-compose'\nimport Router from '@ditojs/router'\n\nconst app = new Koa()\nconst router = new Router()\n\n// static route\nrouter.get('/folders/files/bolt.gif', ctx => {\n  ctx.body = `this ain't no GIF!`\n})\n\n// param route\nrouter.get('/users/:id', ctx => {\n  ctx.body = `requesting user ${ctx.params.id}`\n})\n\n// match-any route\nrouter.get('/books/*', ctx => {\n  ctx.body = `sub-route: ${ctx.params['*']}`\n})\n\n// Handler found\nlet { handler, params } = router.find('get', '/users/233')\nconsole.log(handler) // ctx => { ... }\n\n// Entry not Found\nlet { handler, params } = router.find('get', '/photos/233')\nconsole.log(handler) // null\n\n// Install router middleware\napp.use(async (ctx, next) => {\n  const { method, path } = ctx\n  const result = router.find(method, path)\n  const { handler, params } = result\n  if (handler) {\n    ctx.params = params || {}\n    return handler(ctx, next)\n  } else {\n    try {\n      await next()\n    } finally {\n      if (ctx.body === undefined && ctx.status === 404) {\n        ctx.status = result.status || 404\n        if (ctx.status !== 404 && result.allowed) {\n          ctx.set('Allow', result.allowed.join(', '))\n        }\n      }\n    }\n  }\n})\n\napp.listen(4040, () => console.log('Koa app listening on 4040'))\n```\n"
 }

package/src/Node.js

@@ -1,14 +1,15 @@
 import { getCommonOffset } from '@ditojs/utils'
 
 // Node Types:
-const TYPE_STATIC = 0
-const TYPE_PARAM = 1
-const TYPE_MATCH_ANY = 2
+const TYPE_STATIC = 0 //       /static/patch
+const TYPE_PARAM = 1 //        /prefix/:param/suffix
+const TYPE_PLACEHOLDER = 2 //  /prefix/*/suffix  (a.k.a shallow wildcard)
+const TYPE_MATCH_ANY = 3 //    /prefix/**/suffix (a.k.a deep wildcard)
 
 // Char Codes
-const CHAR_PARAM = ':'.charCodeAt(0)
-const CHAR_MATCH_ANY = '*'.charCodeAt(0)
-const CHAR_SLASH = '/'.charCodeAt(0)
+const CHAR_SLASH = '/'[0]
+const CHAR_PARAM = ':'[0]
+const CHAR_WILDCARD = '*'[0]
 
 export default class Node {
   constructor(...args) {
@@ -16,124 +17,117 @@ export default class Node {
   }
 
   initialize(
-    prefix = '/',
     type = TYPE_STATIC,
+    prefix = '/',
     children = [],
-    handler = null,
-    paramNames = null
+    parameters = null,
+    handler = null
   ) {
-    this.label = prefix.charCodeAt(0)
-    this.prefix = prefix
     this.type = type
+    this.label = prefix[0]
+    this.prefix = prefix
     this.children = children
+    this.parameters = parameters
     this.handler = handler
-    this.paramNames = paramNames
-    this.paramName = null
-  }
-
-  addChild(child) {
-    this.children.push(child)
-  }
-
-  findChild(label, type) {
-    for (const child of this.children) {
-      if (child.label === label && child.type === type) {
-        return child
-      }
-    }
+    this.paramKey = null
+    this.hasMatchAny = false
   }
 
-  findChildWithLabel(label) {
-    for (const child of this.children) {
-      if (child.label === label) {
-        return child
-      }
+  setup(parameters, handler) {
+    this.parameters = parameters
+    this.handler = handler
+    if (this.type === TYPE_MATCH_ANY) {
+      parameters.setupPathPattern(this.prefix)
     }
   }
 
-  findChildWithType(type) {
-    for (const child of this.children) {
-      if (child.type === type) {
-        return child
-      }
-    }
+  addChild(child) {
+    this.children.push(child)
+    this.hasMatchAny ||= child.type === TYPE_MATCH_ANY
   }
 
   add(path, handler) {
-    const paramNames = []
+    const parameters = new Parameters()
     for (let pos = 0, length = path.length; pos < length; pos++) {
-      const ch = path.charCodeAt(pos)
-      if (ch === CHAR_PARAM) {
-        this.insert(path.slice(0, pos), TYPE_STATIC)
-        pos++ // Skip colon.
+      const ch = path[pos]
+      if (ch === CHAR_WILDCARD && path[pos + 1] === CHAR_WILDCARD) {
+        // Deep wildcard (**): matches any path, with a optional suffix:
+        this.insert(TYPE_STATIC, path.slice(0, pos))
+        pos += 2 // Skip '**'.
+        this.insert(TYPE_MATCH_ANY, path, parameters, handler)
+        return
+      } else if (ch === CHAR_PARAM || ch === CHAR_WILDCARD) {
+        // Param (:param) or shallow wildcard (*):
+        const isWildcard = ch === CHAR_WILDCARD
+        const type = isWildcard ? TYPE_PLACEHOLDER : TYPE_PARAM
+        this.insert(TYPE_STATIC, path.slice(0, pos))
+        pos++ // Skip colon or wildcard.
         const start = pos
         // Move pos to the next occurrence of the slash or the end:
         pos += path.slice(pos).match(/^([^/]*)/)[1].length
-
-        paramNames.push(path.slice(start, pos))
+        parameters.add(
+          isWildcard ? parameters.getPlaceholderKey() : path.slice(start, pos)
+        )
         // Chop out param name from path, but keep colon.
         path = path.slice(0, start) + path.slice(pos)
         length = path.length // Update length after changing path.
 
         if (start === length) {
-          return this.insert(path, TYPE_PARAM, paramNames, handler)
+          this.insert(type, path, parameters, handler)
+          return
         }
         pos = start
-        this.insert(path.slice(0, pos), TYPE_PARAM, paramNames)
-      } else if (ch === CHAR_MATCH_ANY) {
-        this.insert(path.slice(0, pos), TYPE_STATIC)
-        paramNames.push('*')
-        return this.insert(path, TYPE_MATCH_ANY, paramNames, handler)
+        this.insert(type, path.slice(0, pos), parameters)
       }
     }
-    this.insert(path, TYPE_STATIC, paramNames, handler)
+    this.insert(TYPE_STATIC, path, parameters, handler)
   }
 
-  insert(path, type, paramNames, handler) {
+  insert(type, prefix, parameters = null, handler = null) {
     let current = this
     while (true) {
       // Find the position where the path and the node's prefix start diverging.
-      const pos = getCommonOffset(current.prefix, path)
-      const { prefix } = current
-      if (pos < prefix.length) {
+      const curPrefix = current.prefix
+      const pos = getCommonOffset(curPrefix, prefix)
+      if (pos < curPrefix.length) {
         // Split node
         const node = new Node(
-          prefix.slice(pos),
           current.type,
+          curPrefix.slice(pos),
           current.children,
-          current.handler,
-          current.paramNames
+          current.parameters,
+          current.handler
         )
-        // Reset parent node and add new node as child to it:
-        current.initialize(prefix.slice(0, pos))
+        // Reset parent node to a static and add new node as child to it:
+        current.initialize(TYPE_STATIC, curPrefix.slice(0, pos))
         current.addChild(node)
-        if (pos < path.length) {
+        if (pos < prefix.length) {
           // Create child node
-          const node = new Node(path.slice(pos), type)
+          const node = new Node(type, prefix.slice(pos))
           current.addChild(node)
-          current = node // Switch to child to set handler and paramNames
+          current = node // Switch to child to set handler and parameters
         }
-      } else if (pos < path.length) {
-        path = path.slice(pos)
-        const child = current.findChildWithLabel(path.charCodeAt(0))
-        if (child !== undefined) {
+      } else if (pos < prefix.length) {
+        prefix = prefix.slice(pos)
+        const label = prefix[0]
+        const child = current.children.find(child => child.label === label)
+        if (child !== undefined && child.type !== TYPE_MATCH_ANY) {
           // Go deeper
           current = child
           continue
         }
         // Create child node
-        const node = new Node(path, type)
+        const node = new Node(type, prefix)
         current.addChild(node)
-        current = node // Switch to child to set handler and paramNames
+        current = node // Switch to child to set handler and parameters
       }
       if (handler) {
-        current.handler = handler
-        current.paramNames = paramNames
+        current.setup(parameters, handler)
       }
-      if (paramNames) {
+      if (parameters) {
         // Remember the last entry from the list of param names that keeps
         // growing during parsing as the name of the current node.
-        current.paramName = paramNames[paramNames.length - 1]
+        current.paramKey = parameters.getLastKey()
       }
       break
     }
@@ -145,12 +139,7 @@ export default class Node {
       // It's a match!
       const { handler } = this
       if (handler) {
-        // Convert paramNames and values to params.
-        const params = {}
-        let i = 0
-        for (const name of this.paramNames) {
-          params[name] = paramValues[i++]
-        }
+        const params = this.parameters.getObject(paramValues)
         // Support HTTP status on found entries.
         return { handler, params, status: 200 }
       }
@@ -162,7 +151,7 @@ export default class Node {
     const fullMatch = pos === prefixLength
     if (fullMatch) {
       path = path.slice(prefixLength)
-    } else if (this.type !== TYPE_PARAM) {
+    } else if (this.type !== TYPE_PARAM && this.type !== TYPE_PLACEHOLDER) {
       // If the path doesn't fully match the prefix, we only need to look
       // further on param nodes, which can have overlapping static children.
       return null
@@ -171,7 +160,10 @@ export default class Node {
     // Search order: Static > Param > Match-any
 
     // Static node
-    const staticChild = this.findChild(path.charCodeAt(0), TYPE_STATIC)
+    const label = path[0]
+    const staticChild = this.children.find(
+      child => child.type === TYPE_STATIC && child.label === label
+    )
     if (staticChild) {
       const result = staticChild.find(path, paramValues)
       if (result) {
@@ -180,17 +172,17 @@ export default class Node {
     }
 
     // Node not found
-    if (!fullMatch) {
-      return null
-    }
+    if (!fullMatch) return null
 
-    // Param node
-    const paramChild = this.findChildWithType(TYPE_PARAM)
+    // Param / placeholder node
+    const paramChild = this.children.find(
+      child => child.type === TYPE_PARAM || child.type === TYPE_PLACEHOLDER
+    )
     if (paramChild) {
       // Find the position of the next slash:
       let pos = 0
       const max = path.length
-      while (pos < max && path.charCodeAt(pos) !== CHAR_SLASH) {
+      while (pos < max && path[pos] !== CHAR_SLASH) {
         pos++
       }
       paramValues.push(path.slice(0, pos))
@@ -201,11 +193,15 @@ export default class Node {
       paramValues.pop()
     }
 
-    // Match-any node
-    const matchAnyChild = this.findChildWithType(TYPE_MATCH_ANY)
-    if (matchAnyChild) {
-      paramValues.push(path)
-      return matchAnyChild.find('', paramValues) // '' == End
+    // Match-any nodes
+    if (this.hasMatchAny) {
+      for (const child of this.children) {
+        const match = child.parameters?.matchPathPattern(path)
+        if (match) {
+          paramValues.push(...Object.values(match.groups))
+          return child.find('', paramValues) // '' == End
+        }
+      }
     }
 
     return null
@@ -219,7 +215,7 @@ export default class Node {
     const lines = [
       `${format(prefix, tail, '└── ', '├── ')}${
         this.type === TYPE_PARAM
-          ? `${this.prefix}${this.paramName}`
+          ? `${this.prefix}${this.paramKey}`
           : this.prefix
       }${
         handler ? ` ${handler}` : ''
@@ -235,3 +231,78 @@ export default class Node {
     return lines.join('\n')
   }
 }
+
+class Parameters {
+  constructor() {
+    this.keys = []
+    this.pathPattern = null
+    this.matchAnyIndex = 0
+    this.placeholderIndex = 0
+  }
+
+  add(...keys) {
+    this.keys.push(...keys)
+  }
+
+  getMatchAnyKey() {
+    return `$$${this.matchAnyIndex++}`
+  }
+
+  getPlaceholderKey() {
+    return `$${this.placeholderIndex++}`
+  }
+
+  getLastKey() {
+    return this.keys[this.keys.length - 1]
+  }
+
+  matchPathPattern(path) {
+    return this.pathPattern?.exec(path)
+  }
+
+  setupPathPattern(path) {
+    // Replace all '**' with '.+?' and all '*' with '[^/]+'.
+    // Use named groups to merge multiple ** or * into one.
+    const pattern = []
+    const keys = []
+    for (const token of path.split('/')) {
+      if (token === '**') {
+        const key = this.getMatchAnyKey()
+        pattern.push(`(?<${key}>.+?)`)
+        keys.push(key)
+      } else if (token === '*') {
+        const key = this.getPlaceholderKey()
+        pattern.push(`(?<${key}>[^/]+)`)
+        keys.push(key)
+      } else if (token.startsWith(':')) {
+        const key = token.slice(1)
+        pattern.push(`(?<${key}>[^/]+)`)
+        keys.push(key)
+      } else {
+        pattern.push(token)
+      }
+    }
+    this.pathPattern = new RegExp(`^${pattern.join('/')}$`)
+    this.add(...keys)
+  }
+
+  getObject(values) {
+    // Convert parameters and values to a params object, but rename path pattern
+    // groups back to param names
+    const params = {}
+    let i = 0
+    for (const key of this.keys) {
+      const name = key.startsWith('$$')
+        ? this.matchAnyIndex === 1
+          ? '$$'
+          : key
+        : key.startsWith('$')
+          ? this.placeholderIndex === 1
+            ? '$'
+            : key
+          : key
+      params[name] = values[i++]
+    }
+    return params
+  }
+}

package/src/Router.test.js

@@ -121,13 +121,13 @@ describe('Router', () => {
     expect(result.allowed).toStrictEqual(['GET', 'PUT'])
   })
 
-  it('handles match-any nodes (catch-all / wildcard)', () => {
-    router.add('GET', '/static/*', handler)
+  it('handles match-any nodes (catch-all)', () => {
+    router.add('GET', '/static/**', handler)
 
     expect(router.toString()).toBe(deindent`
       / children=1
       └── static/ children=1
-          └── * handler() children=0
+          └── ** handler() children=0
     `.trim())
 
     result = router.find('GET', '/static')
@@ -139,13 +139,109 @@ describe('Router', () => {
     result = router.find('GET', '/static/js')
     expect(result.handler).toBe(handler)
     expect(result.params).toEqual({
-      '*': 'js'
+      $$: 'js'
     })
 
     result = router.find('GET', '/static/css')
     expect(result.handler).toBe(handler)
     expect(result.params).toEqual({
-      '*': 'css'
+      $$: 'css'
+    })
+  })
+
+  it('handles match-any nodes (wildcard)', () => {
+    router.add('GET', '/prefix/*/suffix', handler)
+
+    expect(router.toString()).toBe(deindent`
+      / children=1
+      └── prefix/ children=1
+          └── * children=1
+              └── /suffix handler() children=0
+    `.trim())
+
+    result = router.find('GET', '/prefix')
+    expect(result.handler).toBeUndefined()
+
+    result = router.find('GET', '/prefix/*')
+    expect(result.handler).toBeUndefined()
+
+    result = router.find('GET', '/prefix/hello/there')
+    expect(result.handler).toBeUndefined()
+
+    result = router.find('GET', '/prefix/hello/suffix')
+    expect(result.handler).toBe(handler)
+    expect(result.params).toEqual({
+      $: 'hello'
+    })
+  })
+
+  it('handles match-any nodes with suffixes', () => {
+    router.add('GET', '/static/**/suffix', handler)
+    router.add('GET', '/static/**/suffix/**/more', handler)
+    router.add('GET', '/static/**/suffix/*/1/:param/2', handler)
+    router.add('GET', '/static/**/suffix/*/1/:param/2/**/end', handler)
+
+    expect(router.toString()).toBe(deindent`
+      / children=1
+      └── static/ children=4
+          ├── **/suffix handler() children=0
+          ├── **/suffix/**/more handler() children=0
+          ├── **/suffix/*/1/:param/2 handler() children=0
+          └── **/suffix/*/1/:param/2/**/end handler() children=0
+    `.trim())
+
+    result = router.find('GET', '/static')
+    expect(result.handler).toBeUndefined()
+
+    result = router.find('GET', '/static/js')
+    expect(result.handler).toBeUndefined()
+
+    result = router.find('GET', '/static/one/prefix')
+    expect(result.handler).toBeUndefined()
+
+    result = router.find('GET', '/static/one/two/prefix')
+    expect(result.handler).toBeUndefined()
+
+    result = router.find('GET', '/static/one/suffix')
+    expect(result.handler).toBe(handler)
+    expect(result.params).toEqual({
+      $$: 'one'
+    })
+
+    result = router.find('GET', '/static/one/two/suffix')
+    expect(result.handler).toBe(handler)
+    expect(result.params).toEqual({
+      $$: 'one/two'
+    })
+
+    result = router.find('GET', '/static/one/two/suffix/three/four')
+    expect(result.handler).toBeUndefined()
+
+    result = router.find('GET', '/static/one/two/suffix/three/four/more')
+    expect(result.handler).toBe(handler)
+    expect(result.params).toEqual({
+      $$0: 'one/two',
+      $$1: 'three/four'
+    })
+
+    result = router.find('GET', '/static/one/two/suffix/three/1/bla/2')
+    expect(result.handler).toBe(handler)
+    expect(result.params).toEqual({
+      $$: 'one/two',
+      $: 'three',
+      param: 'bla'
+    })
+
+    result = router.find('GET', '/static/one/two/suffix/three/1/bla/3')
+    expect(result.handler).toBeUndefined()
+
+    result = router.find('GET', `/static/one/two/suffix/three/1/bla/2/what/ever/end`)
+    expect(result.handler).toBe(handler)
+    expect(result.params).toEqual({
+      $: 'three',
+      param: 'bla',
+      $$0: 'one/two',
+      $$1: 'what/ever'
     })
   })
 
@@ -164,7 +260,7 @@ describe('Router', () => {
       ['/geocoder/exchange/:item', 'exchangeItemGeocoder'],
       ['/geocoder/:id/echo', 'echoGeocoder'],
       ['/geocoder/:action', 'actionGeocoder'],
-      ['/geocoder/*', 'anyGeocoder']
+      ['/geocoder/**', 'anyGeocoder']
     ])
 
     expect(router.toString()).toBe(deindent`
@@ -185,7 +281,7 @@ describe('Router', () => {
               │           └── :item exchangeItemGeocoder() children=0
               ├── :action actionGeocoder() children=1
               │   └── /echo echoGeocoder() children=0
-              └── * anyGeocoder() children=0
+              └── ** anyGeocoder() children=0
     `.trim())
     result = router.find('GET', '')
     expect(result.handler).not.toBeUndefined()
@@ -203,12 +299,12 @@ describe('Router', () => {
 
     result = router.find('GET', '/geocoder/delete/any')
     expect(result.handler.name).toBe('anyGeocoder')
-    expect(result.params).toEqual({ '*': 'delete/any' })
+    expect(result.params).toEqual({ $$: 'delete/any' })
 
     result = router.find('GET', '/geocoder/any/action')
     expect(result.handler).not.toBeUndefined()
     expect(result.handler.name).toBe('anyGeocoder')
-    expect(result.params).toEqual({ '*': 'any/action' })
+    expect(result.params).toEqual({ $$: 'any/action' })
 
     result = router.find('GET', '/geocoder/exchange/trekjs')
     expect(result.handler).not.toBeUndefined()
@@ -270,14 +366,15 @@ describe('Router', () => {
     createRoutes(router, [
       ['/users', 'users'],
       ['/users/new', 'newUser'],
-      ['/users/nnw', 'newUser'],
+      ['/users/noi', 'newUser'],
+      ['/users/nei', 'newUser'],
       ['/users/:id', 'user'],
       ['/users/:id/edit', 'editUser'],
       ['/users/:id/:hello/:good/:bad/ddd', 'editUser'],
       ['/users/:id/:action', 'actionUser'],
       ['/users/:userId/photos/:id', 'photo'],
       ['/users/:userId/books/:id', 'book'],
-      ['/users/*', 'anyUser']
+      ['/users/**', 'anyUser']
     ])
 
     expect(router.toString()).toBe(deindent`
@@ -285,8 +382,10 @@ describe('Router', () => {
       └── users users() children=1
           └── / children=3
               ├── n children=2
-              │   ├── ew newUser() children=0
-              │   └── nw newUser() children=0
+              │   ├── e children=2
+              │   │   ├── w newUser() children=0
+              │   │   └── i newUser() children=0
+              │   └── oi newUser() children=0
               ├── :userId user() children=1
               │   └── / children=4
               │       ├── edit editUser() children=0
@@ -300,13 +399,13 @@ describe('Router', () => {
               │       │   └── :id photo() children=0
               │       └── books/ children=1
               │           └── :id book() children=0
-              └── * anyUser() children=0
+              └── ** anyUser() children=0
     `.trim())
 
     result = router.find('GET', '/users/610/books/987/edit')
     expect(result.handler).not.toBeUndefined()
     expect(result.handler.name).toBe('anyUser')
-    expect(result.params).toEqual({ '*': '610/books/987/edit' })
+    expect(result.params).toEqual({ $$: '610/books/987/edit' })
 
     result = router.find('GET', '/users/610/books/987')
     expect(result.handler).not.toBeUndefined()