feat: add router support (#64)

Author: pi0

README.md

@@ -21,6 +21,8 @@
 
 ✔️  **Extendable:** Ships with a set of composable utilities but can be extended
 
+✔️  **Router:** Super fast route matching using [unjs/radix3](https://github.com/unjs/radix3)
+
 ## Install
 
 ```bash
@@ -57,7 +59,29 @@ listen(app)
 ```
 </details>
 
-## Examples
+## Router
+
+The `app` instance created by `h3` uses a middleware stack (see [how it works](#how-it-works)) with the ability to match route prefix and apply matched middleware.
+
+To opt-in using a more advanced and convenient routing system, we can create a router instance and register it to app instance.
+
+```ts
+import { createApp, createRouter } from 'h3'
+
+const app = createApp()
+
+const router = createRouter()
+ .get('/', () => 'Hello World!')
+ .get('/hello/:name', req => `Hello ${req.params.name}!`)
+
+app.use(router)
+```
+
+**Tip:** We can register same route more than once with different methods.
+
+Routes are internally stored in a [Radix Tree](https://en.wikipedia.org/wiki/Radix_tree) and matched using [unjs/radix3](https://github.com/unjs/radix3).
+
+## More usage examples
 
 ```js
 // Handle can directly return object or Promise<object> for JSON response

package.json

@@ -28,6 +28,7 @@
   "dependencies": {
     "cookie": "^0.4.2",
     "destr": "^1.1.0",
+    "radix3": "^0.1.1",
     "ufo": "^0.7.11"
   },
   "devDependencies": {

playground/index.ts

@@ -1,11 +1,11 @@
 import { listen } from 'listhen'
-import { createApp } from '../src'
+import { createApp, createRouter } from '../src'
 
-const app = createApp({ debug: true })
+const app = createApp()
+const router = createRouter()
+  .get('/', () => 'Hello World!')
+  .get('/hello/:name', req => `Hello ${req.params.name}!`)
 
-app.use('/', () => {
-  // throw new Error('Foo bar')
-  return 'Hi!'
-})
+app.use(router)
 
 listen(app)

src/handle.ts

@@ -1,7 +1,7 @@
 import { withoutTrailingSlash, withoutBase } from 'ufo'
 import type { IncomingMessage, ServerResponse } from './types/node'
 
-export type Handle<T = any> = (req: IncomingMessage, res: ServerResponse) => T
+export type Handle<T = any, ReqT={}> = (req: IncomingMessage & ReqT, res: ServerResponse) => T
 export type PHandle = Handle<Promise<any>>
 export type Middleware = (req: IncomingMessage, res: ServerResponse, next: (err?: Error) => any) => any
 export type LazyHandle = () => Handle | Promise<Handle>

src/index.ts

@@ -2,3 +2,4 @@ export * from './app'
 export * from './error'
 export * from './handle'
 export * from './utils'
+export * from './router'

src/router.ts

@@ -0,0 +1,76 @@
+import { createRouter as _createRouter } from 'radix3'
+import type { Handle } from './handle'
+import type { HTTPMethod } from './types/http'
+import { createError } from './error'
+
+export type RouterMethod = Lowercase<HTTPMethod>
+const RouterMethods: Lowercase<RouterMethod>[] = ['connect', 'delete', 'get', 'head', 'options', 'post', 'put', 'trace']
+
+export type HandleWithParams = Handle<any, { params: Record<string, string> }>
+
+export type AddWithMethod = (path: string, handle: HandleWithParams) => Router
+export type AddRouteShortcuts = Record<Lowercase<HTTPMethod>, AddWithMethod>
+
+export interface Router extends AddRouteShortcuts {
+  add: (path: string, handle: HandleWithParams, method?: RouterMethod | 'all') => Router
+  handle: Handle
+}
+
+interface RouteNode {
+  handlers: Partial<Record<RouterMethod| 'all', HandleWithParams>>
+}
+
+export function createRouter (): Router {
+  const _router = _createRouter<RouteNode>({})
+  const routes: Record<string, RouteNode> = {}
+
+  const router: Router = {} as Router
+
+  // Utilities to add a new route
+  router.add = (path, handle, method = 'all') => {
+    let route = routes[path]
+    if (!route) {
+      routes[path] = route = { handlers: {} }
+      _router.insert(path, route)
+    }
+    route.handlers[method] = handle
+    return router
+  }
+  for (const method of RouterMethods) {
+    router[method] = (path, handle) => router.add(path, handle, method)
+  }
+
+  // Main handle
+  router.handle = (req, res) => {
+    // Match route
+    const matched = _router.lookup(req.url || '/')
+    if (!matched) {
+      throw createError({
+        statusCode: 404,
+        name: 'Not Found',
+        statusMessage: `Cannot find any route matching ${req.url || '/'}.`
+      })
+    }
+
+    // Match method
+    const method = (req.method || 'get').toLowerCase() as RouterMethod
+    const handler: HandleWithParams | undefined = matched.handlers[method] || matched.handlers.all
+    if (!handler) {
+      throw createError({
+        statusCode: 405,
+        name: 'Method Not Allowed',
+        statusMessage: `Method ${method} is not allowed on this route.`
+      })
+    }
+
+    // Add params
+    // @ts-ignore
+    req.params = matched.params || {}
+
+    // Call handler
+    // @ts-ignore
+    return handler(req, res)
+  }
+
+  return router
+}

src/types/http.ts

@@ -0,0 +1,2 @@
+// https://www.rfc-editor.org/rfc/rfc7231#section-4.1
+export type HTTPMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE'

src/utils/body.ts

@@ -1,7 +1,8 @@
 import type { IncomingMessage } from 'http'
 import destr from 'destr'
 import type { Encoding } from '../types/node'
-import { HTTPMethod, assertMethod } from './request'
+import type { HTTPMethod } from '../types/http'
+import { assertMethod } from './request'
 
 const RawBodySymbol = Symbol('h3RawBody')
 const ParsedBodySymbol = Symbol('h3RawBody')

src/utils/request.ts

@@ -1,14 +1,12 @@
 import type { IncomingMessage } from 'http'
 import { getQuery } from 'ufo'
 import { createError } from '../error'
+import type { HTTPMethod } from '../types/http'
 
 export function useQuery (req: IncomingMessage) {
   return getQuery(req.url || '')
 }
 
-// https://www.rfc-editor.org/rfc/rfc7231#section-4.1
-export type HTTPMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE'
-
 export function useMethod (req: IncomingMessage, defaultMethod: HTTPMethod = 'GET'): HTTPMethod {
   return (req.method || defaultMethod).toUpperCase() as HTTPMethod
 }

test/router.test.ts

@@ -0,0 +1,42 @@
+import supertest, { SuperTest, Test } from 'supertest'
+import { describe, it, expect, beforeEach } from 'vitest'
+import { createApp, createRouter, App, Router } from '../src'
+
+describe('router', () => {
+  let app: App
+  let router: Router
+  let request: SuperTest<Test>
+
+  beforeEach(() => {
+    app = createApp({ debug: false })
+    router = createRouter()
+      .add('/', () => 'Hello')
+      .get('/test', () => 'Test (GET)')
+      .post('/test', () => 'Test (POST)')
+
+    app.use(router)
+    request = supertest(app)
+  })
+
+  it('Handle route', async () => {
+    const res = await request.get('/')
+    expect(res.text).toEqual('Hello')
+  })
+
+  it('Handle different methods', async () => {
+    const res1 = await request.get('/test')
+    expect(res1.text).toEqual('Test (GET)')
+    const res2 = await request.post('/test')
+    expect(res2.text).toEqual('Test (POST)')
+  })
+
+  it('Not matching route', async () => {
+    const res = await request.get('/404')
+    expect(res.status).toEqual(404)
+  })
+
+  it('Not matching route method', async () => {
+    const res = await request.head('/test')
+    expect(res.status).toEqual(405)
+  })
+})