v5.x DRAFT

[kwhitley]

Release Progress

• Finalize API
• 100% test coverage
• Fully type additions
• Document @ itty.dev
  • add section for Routers
  • add comparison chart for Router features
  • add to API page
  • add examples for each Router type
• Document @ README.md
  • rebrand to itty.dev
  • modify examples
  • simplify feature set

Changes

Router (adding features) ~550 bytes

• OBJECTIVE: by adding these stages as config-based, we allow clean exports leveraging the default router.fetch signature to match up to various runtimes (e.g. Bun, Cloudflare Workers). We also make the possibility of AutoRouter that adds sane defaults. Previously, this control flow was only possible using the .then chain after router.fetch, or by monkey-patching/intercepting the fetch method itself.
• fully backwards compatible with the previous Router (now IttyRouter)
• added option before - array of before handlers/middleware
• added option catch - a single error handler to catch thrown exceptions
• added option finally - array of response handlers
  • each after handler is passed the following args: (response: any, request: IRequest, ...args), where ...args are anything additional passed to the original fetch function. This allows the after stage to easily have access to Cloudflare environment and context.
  • each of these may optionally modify the response
  • if nothing is returned, the previous successful response is passed through - this allows pass-through functions (e.g. logging) to function without forcing a return

Example:

import { Router, error, json, withParams } from 'itty-router'

const router = Router({ 
  port: 3001,
  before: [withParams],
  catch: error,
  finally: [json],  
})

router
  .get('/basic', () => new Response('Success!'))
  .get('/text', () => 'Success!')
  .get('/params/:foo', ({ foo }) => foo)
  .get('/json', () => ({ foo: 'bar' }))
  .get('/throw', (a) => a.b.c)
  .all('*', () => error(404))

export default router

AutoRouter (new) ~1kB

• creates Router with sane defaults and a few modified behaviors
• added option: format (a single response formatter, such as json) to control default formatter
  • to skip this stage, enter a no-op: format: () => {}
• added option: missing (a single request handler that will be passed the request and any additional args)
  • to skip this stage, enter a no-op: missing: () => {}
• added withParams as a forced before stage entry
• modified option: finally always uses the following pattern:

  finally: [
    (r: any, ...args) => r ?? missing(r, ...args),
    format,
    ...finally,
  ],

  This means you lose complete control over replacing the missing and format stage.

Example:

import { AutoRouter } from 'itty-router'

const router = AutoRouter({ port: 3001 })

router
  .get('/basic', () => new Response('Success!'))
  .get('/text', () => 'Success!')
  .get('/params/:foo', ({ foo }) => foo)
  .get('/json', () => ({ foo: 'bar' }))
  .get('/throw', (a) => a.b.c)

export default router

IttyRouter (new) ~460 bytes

• moves the original Router to IttyRouter
• NOTE - .handle is fully deprecated here (in favor of router.fetch) to save bytes

Example:

import { IttyRouter, error, json, withParams } from 'itty-router'

const router = IttyRouter({ port: 3001 })

router
  .all('*', withParams)
  .get('/basic', () => new Response('Success!'))
  .get('/text', () => 'Success!')
  .get('/params/:foo', ({ foo }) => foo)
  .get('/json', () => ({ foo: 'bar' }))
  .get('/throw', (a) => a.b.c)
  .all('*', () => error(404))

export default {
  fetch: (request, ...args) => router
                                 .fetch(request, ...args)
                                 .then(json)
                                 .catch(error)
}

Type of Change (select one and follow subtasks)

• Documentation (README.md)
• Maintenance or repo-level work (e.g. linting, build, tests, refactoring, etc.)
• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
  • I have included test coverage
• Breaking change (fix or feature that would cause existing functionality/userland code to not work as expected)
  • Explain why a breaking change is necessary:
• This change requires (or is) a documentation update
  • I have added necessary local documentation (if appropriate)
  • I have added necessary itty.dev documentation (if appropriate)