itty-router 2.4.10 → 2.5.2

package/CHANGELOG.md

@@ -1,6 +1,11 @@
 ## Changelog
 Until this library makes it to a production release of v1.x, **minor versions may contain breaking changes to the API**.  After v1.x, semantic versioning will be honored, and breaking changes will only occur under the umbrella of a major version bump.
 
+[@SupremeTechnopriest)(https://github.com/SupremeTechnopriest) - improved TypeScript support and documentation! :D\
+
+- **v2.5.2** - fixes issue with arrow functions in CommonJS named exports (rare issue)
+- **v2.5.1** - added context to Cloudflare ES module syntax example (credit [@jcapogna](https://github.com/jcapogna))
+- **v2.5.0** - improved TypeScript docs/types (thanks [@SupremeTechnopriest](https://github.com/SupremeTechnopriest)!)
 - **v2.4.9** - fixed the cursed "optional" file format capturing bug - RIP all the bytes lost
 - **v2.4.6** - fixed README issues
 - **v2.4.1** - fixed type errors introduced with 2.4.0

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm package][npm-image]][npm-url]
 [![minified + gzipped size][gzip-image]][gzip-url]
-[![Build Status][travis-image]][travis-url]
+![Build Status](https://github.com/kwhitley/itty-router/actions/workflows/verify.yml/badge.svg)
 [![Coverage Status][coveralls-image]][coveralls-url]
 [![Open Issues][issues-image]][issues-url]
 <a href="https://npmjs.com/package/itty-router" target="\_parent">
@@ -19,14 +19,15 @@
   <img alt="Join the discussion on Github" src="https://img.shields.io/badge/Github%20Discussions%20%26%20Support-Chat%20now!-blue" />
 </a>-->
 
-It's an itty bitty router, designed for express-like routing within [Cloudflare Workers](https://developers.cloudflare.com/workers/) (or anywhere else). Like... it's super tiny ([~4xx bytes](https://bundlephobia.com/package/itty-router)), with zero dependencies. For reals.
+It's an itty bitty router, designed for express-like routing within [Cloudflare Workers](https://developers.cloudflare.com/workers/) (or anywhere else). Like... it's super tiny ([~500 bytes](https://bundlephobia.com/package/itty-router)), with zero dependencies. For reals.
 
 ### Addons & Related Libraries
 1. [itty-router-extras](https://www.npmjs.com/package/itty-router-extras) - adds quality-of-life improvements and utility functions for simplifying request/response code (e.g. middleware, cookies, body parsing, json handling, errors, and an itty version with automatic exception handling)!
 2. [itty-durable](https://github.com/kwhitley/itty-durable) - (EXPERIMENTAL/alpha) creates a more direct object-like API for interacting with [Cloudflare Durable Objects](https://developers.cloudflare.com/workers/learning/using-durable-objects).
 
 ## Features
-- [x] Tiny ([~4xx bytes](https://bundlephobia.com/package/itty-router) compressed) with zero dependencies.
+- [x] Tiny ([~500 bytes](https://bundlephobia.com/package/itty-router) compressed), with zero dependencies.
+- [x] [TypeScript support](#typescript)!
 - [x] Full sync/async support.  Use it when you need it!
 - [x] Route params, with wildcards and optionals (e.g. `/api/:collection/:id?`)
 - [x] Query parsing (e.g. `?page=3&foo=bar`)
@@ -282,16 +283,33 @@ router.get('/todos/:id.:format?', request => {
 ```
 
 ### Cloudflare ES6 Module Syntax (required for Durable Objects) <a id="cf-es6-module-syntax"></a>
+See https://developers.cloudflare.com/workers/runtime-apis/fetch-event#syntax-module-worker
 ```js
+import { Router } from 'itty-router'
+
 const router = Router()
 
-router.get('/', (request, env) => {
+router.get('/', (request, env, context) => {
   // now have access to the env (where CF bindings like durables, KV, etc now are)
 })
 
 export default {
   fetch: router.handle // yep, it's this easy.
 }
+
+// alternative advanced/manual approach for downstream control
+export default {
+  fetch: (...args) => router
+                        .handle(...args)
+                        .then(response =>
+                          // can modify response here before final return, e.g. CORS headers
+
+                          return response
+                        })
+                        .catch(err => {
+                          // and do something with the errors here, like logging, error status, etc
+                        })
+}
 ```
 
 ### Extending itty router
@@ -377,6 +395,106 @@ router.get('/test', () => new Response('You can still define routes normally as
 await router.handle({ method: 'GET', url: 'https:nowhere.com/custom-a123' })    // { id: "a123" }
 ```
 
+### Typescript
+
+For Typescript projects, the Router can be adorned with two generics: A custom request interface and a custom methods interface.
+
+```ts
+import { Router, Route, Request } from 'itty-router'
+
+type MethodType = 'GET' | 'POST' | 'PUPPY'
+
+interface IRequest extends Request {
+  method: MethodType // method is required to be on the interface
+  url: string // url is required to be on the interface
+  optional?: string
+}
+
+interface IMethods {
+  get: Route
+  post: Route
+  puppy: Route
+}
+
+const router = Router<IRequest, IMethods>()
+
+router.get('/', (request: IRequest) => {})
+router.post('/', (request: IRequest) => {})
+router.puppy('/', (request: IRequest) => {})
+
+addEventListener('fetch', (event: FetchEvent) => {
+  event.respondWith(router.handle(event.request))
+})
+```
+
+Both generics are optional. `TRequest` defaults to `Request` and `TMethods` defaults to `{}`.
+
+```ts
+import { Router, Route } from 'itty-router'
+
+type MethodType = 'GET' | 'POST' | 'PUPPY'
+
+interface IRequest extends Request {
+  method: MethodType
+  url: string
+  optional?: string
+}
+
+interface IMethods {
+  get: Route
+  post: Route
+  puppy: Route
+}
+
+const router = Router() // Valid
+const router = Router<IRequest>() // Valid
+const router = Router<Request, IMethods>() // Valid
+const router = Router<void, IMethods>() // Valid
+```
+
+The router will also accept any string as a method, not just those provided on the `TMethods` type.
+
+```ts
+import { Router, Route } from 'itty-router'
+
+interface IMethods {
+  get: Route
+  post: Route
+  puppy: Route
+}
+
+const router = Router<void, IMethods>()
+
+router.puppy('/', request => {}) // Valid
+router.kitten('/', request => {}) // Also Valid
+```
+
+The `itty-router` package also exports an interface containing all of the HTTP methods.
+
+```ts
+import { Router, Route, IHTTPMethods } from 'itty-router'
+
+const router = Router<void, IHTTPMethods>()
+
+router.get('/', request => {}) // Exposed via IHTTPMethods
+router.puppy('/', request => {}) // Valid but not strongly typed
+```
+
+You can also extend `IHTTPMethods` with your own custom methods so they will be strongly typed.
+
+```ts
+import { Router, Route, IHTTPMethods } from 'itty-router'
+
+interface IMethods extends IHTTPMethods {
+  puppy: Route
+}
+
+const router = Router<void, IMethods>()
+
+router.get('/', request => {}) // Exposed via IHTTPMethods
+router.puppy('/', request => {}) // Strongly typed
+```
+
 ## Testing and Contributing
 1. Fork repo
 1. Install dev dependencies via `yarn`
@@ -389,36 +507,38 @@ await router.handle({ method: 'GET', url: 'https:nowhere.com/custom-a123' })
 
 ### The Entire Code (for more legibility, [see src on GitHub](https://github.com/kwhitley/itty-router/blob/v2.x/src/itty-router.js))
 ```js
-const Router = ({ base = '', routes = [] } = {}) => ({
-  __proto__: new Proxy({}, {
-    get: (t, k, c) => (p, ...H) =>
-      routes.push([
-        k.toUpperCase(),
-        RegExp(`^${(base + p)
-          .replace(/(\/?)\*/g, '($1.*)?')
-          .replace(/\/$/, '')
-          .replace(/:(\w+)(\?)?(\.)?/g, '$2(?<$1>[^/]+)$2$3')
-          .replace(/\.(?=[\w(])/, '\\.')
-          .replace(/\)\.\?\(([^\[]+)\[\^/g, '?)\\.?($1(?<=\\.)[^\\.')
-        }/*$`),
-        H,
-      ]) && c
-  }),
-  routes,
-  async handle (q, ...a) {
-    let s, m,
-        u = new URL(q.url)
-    q.query = Object.fromEntries(u.searchParams)
-    for (let [M, p, H] of routes) {
-      if ((M === q.method || M === 'ALL') && (m = u.pathname.match(p))) {
-        q.params = m.groups
-        for (let h of H) {
-          if ((s = await h(q.proxy || q, ...a)) !== undefined) return s
+function Router({ base = '', routes = [] } = {}) {
+  return {
+    __proto__: new Proxy({}, {
+      get: (t, k, c) => (p, ...H) =>
+        routes.push([
+          k.toUpperCase(),
+          RegExp(`^${(base + p)
+            .replace(/(\/?)\*/g, '($1.*)?')
+            .replace(/\/$/, '')
+            .replace(/:(\w+)(\?)?(\.)?/g, '$2(?<$1>[^/]+)$2$3')
+            .replace(/\.(?=[\w(])/, '\\.')
+            .replace(/\)\.\?\(([^\[]+)\[\^/g, '?)\\.?($1(?<=\\.)[^\\.') // RIP all the bytes lost :'(
+          }/*$`),
+          H,
+        ]) && c
+    }),
+    routes,
+    async handle (q, ...a) {
+      let s, m,
+          u = new URL(q.url)
+      q.query = Object.fromEntries(u.searchParams)
+      for (let [M, p, H] of routes) {
+        if ((M === q.method || M === 'ALL') && (m = u.pathname.match(p))) {
+          q.params = m.groups
+          for (let h of H) {
+            if ((s = await h(q.proxy || q, ...a)) !== undefined) return s
+          }
         }
       }
     }
   }
-})
+}
 ```
 
 ## Special Thanks
@@ -436,8 +556,6 @@ This trick allows methods (e.g. "get", "post") to by defined dynamically by the
 [issues-url]:https://github.com/kwhitley/itty-router/issues
 [npm-image]:https://img.shields.io/npm/v/itty-router.svg
 [npm-url]:http://npmjs.org/package/itty-router
-[travis-image]:https://app.travis-ci.com/kwhitley/itty-router.svg?branch=v2.x
-[travis-url]:https://travis-ci.org/kwhitley/itty-router
 [david-image]:https://david-dm.org/kwhitley/itty-router/status.svg
 [david-url]:https://david-dm.org/kwhitley/itty-router
 [coveralls-image]:https://coveralls.io/repos/github/kwhitley/itty-router/badge.svg?branch=v2.x
@@ -453,9 +571,14 @@ These folks are the real heroes, making open source the powerhouse that it is!
 - [@mvasigh](https://github.com/mvasigh) - proxy hack wizard behind itty, coding partner in crime, maker of the entire doc site, etc, etc.
 - [@taralx](https://github.com/taralx) - router internal code-golfing refactor for performance and character savings
 - [@hunterloftis](https://github.com/hunterloftis) - router.handle() method now accepts extra arguments and passed them to route functions
+- [@SupremeTechnopriest](https://github.com/SupremeTechnopriest) - improved TypeScript support and documentation! :D
 #### Fixes
 - [@taralx](https://github.com/taralx) - QOL fixes for contributing (dev dep fix and test file consistency) <3
 - [@technoyes](https://github.com/technoyes) - three kind-of-a-big-deal errors fixed.  Imagine the look on my face... thanks man!! :)
 - [@roojay520](https://github.com/roojay520) - TS interface fixes
 #### Documentation
-- [@arunsathiya](https://github.com/arunsathiya), [@poacher2k](https://github.com/poacher2k), [@ddarkr](https://github.com/ddarkr), [@kclauson](https://github.com/kclauson)
+- [@arunsathiya](https://github.com/arunsathiya),
+  [@poacher2k](https://github.com/poacher2k),
+  [@ddarkr](https://github.com/ddarkr),
+  [@kclauson](https://github.com/kclauson),
+  [@jcapogna](https://github.com/jcapogna)

package/dist/itty-router.d.ts

@@ -3,7 +3,7 @@ export type Obj = {
 }
 
 export interface RouteHandler<TRequest> {
-  (request: TRequest & Request, ...args: any): any
+  (request: TRequest, ...args: any): any
 }
 
 export interface Route {
@@ -29,10 +29,23 @@ export interface Request {
   text?(): Promise<any>
 }
 
-export type Router<TRequest> = {
-  handle: (request: Request, ...extra: any) => any
+export interface IHTTPMethods {
+  get: Route
+  head: Route
+  post: Route
+  put: Route
+  delete: Route
+  connect: Route
+  options: Route
+  trace: Route
+  patch: Route
+}
+
+export type Router<TRequest = Request, TMethods = {}> = {
+  handle: (request: TRequest, ...extra: any) => any
   routes: RouteEntry<TRequest>[]
-} & {
+  all: Route
+} & TMethods & {
   [any:string]: Route
 }
 
@@ -41,4 +54,4 @@ export interface RouterOptions<TRequest> {
   routes?: RouteEntry<TRequest>[]
 }
 
-export function Router<TRequest>(options?:RouterOptions<TRequest>): Router<TRequest>
+export function Router<TRequest = Request, TMethods = {}>(options?:RouterOptions<TRequest>): Router<TRequest, TMethods>

package/dist/itty-router.min.js

@@ -1 +1 @@
-module.exports={Router:({base:p="",routes:u=[]}={})=>({__proto__:new Proxy({},{get:(e,a,o)=>(e,...r)=>u.push([a.toUpperCase(),RegExp(`^${(p+e).replace(/(\/?)\*/g,"($1.*)?").replace(/\/$/,"").replace(/:(\w+)(\?)?(\.)?/g,"$2(?<$1>[^/]+)$2$3").replace(/\.(?=[\w(])/,"\\.").replace(/\)\.\?\(([^\[]+)\[\^/g,"?)\\.?($1(?<=\\.)[^\\.")}/*$`),r])&&o}),routes:u,async handle(e,...r){let a,o,p=new URL(e.url);e.query=Object.fromEntries(p.searchParams);for(var[t,s,c]of u)if((t===e.method||"ALL"===t)&&(o=p.pathname.match(s))){e.params=o.groups;for(var l of c)if(void 0!==(a=await l(e.proxy||e,...r)))return a}}})};
+module.exports={Router:function({base:t="",routes:n=[]}={}){return{__proto__:new Proxy({},{get:(e,a,o)=>(e,...r)=>n.push([a.toUpperCase(),RegExp(`^${(t+e).replace(/(\/?)\*/g,"($1.*)?").replace(/\/$/,"").replace(/:(\w+)(\?)?(\.)?/g,"$2(?<$1>[^/]+)$2$3").replace(/\.(?=[\w(])/,"\\.").replace(/\)\.\?\(([^\[]+)\[\^/g,"?)\\.?($1(?<=\\.)[^\\.")}/*$`),r])&&o}),routes:n,async handle(e,...r){let a,o,t=new URL(e.url);e.query=Object.fromEntries(t.searchParams);for(var[p,s,u]of n)if((p===e.method||"ALL"===p)&&(o=t.pathname.match(s))){e.params=o.groups;for(var c of u)if(void 0!==(a=await c(e.proxy||e,...r)))return a}}}}};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itty-router",
-  "version": "2.4.10",
+  "version": "2.5.2",
   "description": "Tiny, zero-dependency router with route param and query parsing - built for Cloudflare Workers, but works everywhere!",
   "main": "./dist/itty-router.min.js",
   "types": "./dist/itty-router.d.ts",