unrouted

Unrouted is a batteries included router built for making epic development APIs

Features

• Built on top of h3, radix3
• Comes with serve
• Cors enabled by default

✔️ Compatibility: Works with Express, Connect, H3 and Koa

✔️ Developer Experience:

• Named URL parameters
• Grouping with prefix
• Responds to OPTIONS requests with allowed methods.
• Support for 405 Method Not Allowed and 501 Not Implemented.

✔️ Modern: TypeScript and Native promise support

Install

# Using npm
npm install unrouted

# Using yarn
yarn add unrouted

Usage

import { createServer } from 'http'
import { createApp } from 'h3'

const h3 = createApp()
const { get, handle, group } = createRouter()

get('/', 'Hello World')
h3.use(handle)

createServer(app).listen(process.env.PORT || 3000)

Examples

// Handle can directly return object or Promise<object> for JSON response
app.use('/api', (req) => ({ url: req.url }))

// We can have better matching other than quick prefix match
app.use('/odd', () => 'Is odd!', { match: url => url.substr(1) % 2 })

// Handle can directly return string for HTML response
app.use(() => '<h1>Hello world!</h1>')

// We can chain calls to .use()
app.use('/1', () => '<h1>Hello world!</h1>')
   .use('/2', () => '<h1>Goodbye!</h1>')

// Legacy middleware with 3rd argument are automatically promisified
app.use((req, res, next) => { req.setHeader('X-Foo', 'bar'); next() })

// Force promisify a legacy middleware
// app.use(someMiddleware, { promisify: true })

// Lazy loaded routes using { lazy: true }
// app.use('/big', () => import('./big'), { lazy: true })

Utilities

Instead of adding helpers to req and res, h3 exposes them as composable utilities.

• useRawBody(req, encoding?)
• useBody(req)
• useCookies(req)
• useCookie(req, name)
• setCookie(req, name, value, opts?)
• useQuery(req)
• send(res, data, type?)
• sendRedirect(res, location, code=302)
• appendHeader(res, name, value)
• createError({ statusCode, statusMessage, data? }
• sendError(res, error, debug?)

How it works?

Using createApp, it returns a standard (req, res) handler function and internally an array called middleware stack. usinguse() method we can to add an item to this internal stack.

When a request comes, each stack item that matches the route will be called and resolved until res.writableEnded flag is set, which means the response is sent. If writableEnded is not set after all middleware, a 404 error will be thrown. And if one of the stack items resolves to a value, it will be serialized and sent as response as a shorthand method to sending responses.

For maximum compatibility with connect/express middleware (req, res, next? signature), h3 converts classic middleware into a promisified version ready to use with stack runner:

• If middleware has 3rd next/callback param, promise will resolve/reject when called
• If middleware returns a promise, it will be chained to the main promise
• If calling middleware throws an immediate error, promise will be rejected
• On close and error events of res, promise will resolve/reject (to ensure if middleware simply calls res.end)

License

MIT