itty-router 3.0.3 → 3.0.5

package/README.md

@@ -2,8 +2,8 @@
 
 [![Version](https://img.shields.io/npm/v/itty-router.svg?style=flat-square)](https://npmjs.com/package/itty-router)
 [![Bundle Size](https://img.shields.io/bundlephobia/minzip/itty-router?style=flat-square)](https://bundlephobia.com/result?p=itty-router)
-[![Build Status](https://img.shields.io/github/actions/workflow/status/kwhitley/itty-router/verify.yml?branch=v2.x&style=flat-square)](https://github.com/kwhitley/itty-router/actions/workflows/verify.yml)
-[![Coverage Status](https://img.shields.io/coveralls/github/kwhitley/itty-router/v2.x?style=flat-square)](https://coveralls.io/github/kwhitley/itty-router?branch=v2.x)
+[![Build Status](https://img.shields.io/github/actions/workflow/status/kwhitley/itty-router/verify.yml?branch=v3.x&style=flat-square)](https://github.com/kwhitley/itty-router/actions/workflows/verify.yml)
+[![Coverage Status](https://img.shields.io/coveralls/github/kwhitley/itty-router/v3.x?style=flat-square)](https://coveralls.io/github/kwhitley/itty-router?branch=v3.x)
 [![NPM Weekly Downloads](https://img.shields.io/npm/dw/itty-router?style=flat-square)](https://npmjs.com/package/itty-router)
 [![Open Issues](https://img.shields.io/github/issues/kwhitley/itty-router?style=flat-square)](https://github.com/kwhitley/itty-router/issues)
 
@@ -14,13 +14,10 @@
 Tiny, zero-dependency router with route param and query parsing - built for [Cloudflare Workers](https://developers.cloudflare.com/workers/), but works everywhere!
 
 # Major Announcement: v3.x is Live!  
-Due to an NPM hiccup, `3.0.0` went live early (instead of staying on `next`). The immediate NPM unpublish (normally fine) was rejected, so rather than deprecate the version (super dirty), it's going to stay live on the main v3 path, and we'll smoke test the issues to address them rapidly. Please [join the discussion on Discord](https://discord.gg/53vyrZAu9u) to assist in this rollout!  In the meantime, thanks everyone for your patience!
+Version 3 introduces itty as a TypeScript-first library.  This version should break no existing JS users, but TS users will likely need to [update their types](#typescript).  Please [join the discussion on Discord](https://discord.gg/53vyrZAu9u) to assist in this rollout!  In the meantime, thanks everyone for your patience!  
 
-This comes with a couple major changes, and is now a TS-first lib. 
+Here are the major changes in version 3, with `itty-router-extras` (certainly) and likely `itty-cors` to be added into core as upcoming minor releases:
 
-### Increase in bundle size (~250 bytes)
-This was sadly overdue (and hopefully can be golfed down a bit), but as a result addressed the following issues from v2.x:
- 
 1 . Routes can now capture complex/unknown paths using the trailing `+` modifier.  As a result, this is now possible:
   ```js
   router.handle('/get-file/:path+', ({ params }) => params)
@@ -35,9 +32,6 @@ This was sadly overdue (and hopefully can be golfed down a bit), but as a result
   // GET /foo?pets=mittens&pets=fluffy&pets=rex&bar=baz => { bar: "baz", pets: ["mittens", "fluffy", "rex"] }
   ```
   
-### Breaking TS changes
-I've been forced to rewrite the TS types.  This will need a bit of documentation...
-
 ### 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-cors](https://www.npmjs.com/package/itty-cors) (early access/alpha) - Easy CORS handling for itty APIs.
@@ -48,7 +42,8 @@ I've been forced to rewrite the TS types.  This will need a bit of documentation
 - [x] [Fully typed/TypeScript support](#typescript)
 - [x] Supports sync/async handlers/middleware.
 - [x] Parses route params, with wildcards and optionals (e.g. `/api/:collection/:id?`)
-- [x] Query parsing (e.g. `?page=3&foo=bar`)
+- [x] ["Greedy" route captures](#greedy) (e.g. `/api/:path+`)
+- [x] Query parsing (e.g. `?page=3&foo=bar&foo=baz`)
 - [x] [Middleware support](#middleware). Any number of sync/async handlers may be passed to a route.
 - [x] [Nestable](#nested-routers-with-404-handling). Supports nesting routers for API branching.
 - [x] [Base path](#nested-routers-with-404-handling) for prefixing all routes.
@@ -153,14 +148,15 @@ GET /todos/jane
   query: {}
 }
 
-GET /todos/jane?limit=2&page=1
+GET /todos/jane?limit=2&page=1&foo=bar&foo=baz
 {
   params: {
     user: 'jane'
   },
   query: {
     limit: '2',
-    page: '2'
+    page: '2',
+    foo: ['bar', 'baz],
   }
 }
 */
@@ -317,16 +313,16 @@ export default {
 
 // 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
-                        })
+  fetch: (request, env, context) => router
+                                      .handle(request, env, context)
+                                      .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
+                                      })
 }
 ```
 
@@ -415,104 +411,49 @@ await router.handle({ method: 'GET', url: 'https:nowhere.com/custom-a123' })
 
 ### Typescript
 
-For Typescript projects, the Router can be adorned with two generics: A custom request interface and a custom methods interface.
+As of version `3.x`, itty-router is TypeScript-first, meaning it has full hinting out of the box.
 
 ```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
+import {
+  Router,               // the router itself
+  IRequest,             // lightweight/generic Request type
+  RouterType,           // generic Router type
+  Route,                // generic Route type
+} from './itty-router'
+
+// declare a custom Router type with used methods
+interface CustomRouter extends RouterType {
+  all: Route,
+  get: Route,
+  puppy: Route,
 }
 
-interface IMethods {
-  get: Route
-  post: Route
-  puppy: Route
+// declare a custom Request type to allow request injection from middleware
+type RequestWithAuthors = {
+  authors?: string[]
+} & IRequest
+
+// middleware that modifies the request
+const withAuthors = (request: IRequest) => {
+  request.authors = ['foo', 'bar']
 }
 
-const router = Router<IRequest, IMethods>()
+const router = <CustomRouter>Router({ base: '/' })
 
-router.get('/', (request: IRequest) => {})
-router.post('/', (request: IRequest) => {})
-router.puppy('/', (request: IRequest) => {})
+router
+  .all<CustomRouter>('*', () => {})
+  .get<CustomRouter>('/authors', withAuthors, (request: RequestWithAuthors) => {
+    return request.authors?.[0]
+  })
+  .puppy('*', (request) => {
+    const foo = request.query.foo
+  })
 
 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`

package/dist/itty-router.d.ts

@@ -1,20 +1,22 @@
-declare type RequestTraps = {
+declare type GenericTraps = {
     [key: string]: any;
 };
-declare type RequestLike = {
+declare type IRequest = {
     method: string;
     url: string;
-} & RequestTraps;
+    params: GenericTraps;
+    query: GenericTraps;
+} & GenericTraps;
 interface RouterOptions {
     base?: string;
     routes?: RouteEntry[];
 }
 interface RouteHandler {
-    (request: RequestLike, ...args: any): any;
+    (request: IRequest, ...args: any): any;
 }
 declare type RouteEntry = [string, RegExp, RouteHandler[]];
-declare type Route = (path: string, ...handlers: RouteHandler[]) => RouterType;
-declare type RouterTraps = {
+declare type Route = <T extends RouterType>(path: string, ...handlers: RouteHandler[]) => T;
+declare type RouterHints = {
     all?: Route;
     delete?: Route;
     get?: Route;
@@ -26,8 +28,8 @@ declare type RouterTraps = {
 declare type RouterType = {
     __proto__: RouterType;
     routes: RouteEntry[];
-    handle: (request: RequestLike, ...extra: any) => Promise<any>;
-} & RouterTraps;
+    handle: (request: IRequest, ...extra: any) => Promise<any>;
+} & RouterHints;
 declare const Router: ({ base, routes }?: RouterOptions) => RouterType;
 
-export { RequestLike, RequestTraps, Route, RouteEntry, RouteHandler, Router, RouterOptions, RouterTraps, RouterType };
+export { GenericTraps, IRequest, Route, RouteEntry, RouteHandler, Router, RouterHints, RouterOptions, RouterType };

package/dist/itty-router.js

@@ -1 +1 @@
-var u=Object.defineProperty;var i=Object.getOwnPropertyDescriptor;var d=Object.getOwnPropertyNames;var g=Object.prototype.hasOwnProperty;var h=(r,e)=>{for(var t in e)u(r,t,{get:e[t],enumerable:!0})},x=(r,e,t,p)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of d(e))!g.call(r,o)&&o!==t&&u(r,o,{get:()=>e[o],enumerable:!(p=i(e,o))||p.enumerable});return r};var f=r=>x(u({},"__esModule",{value:!0}),r);var T={};h(T,{Router:()=>m});module.exports=f(T);var $=r=>[...r.entries()].reduce((e,[t,p])=>(e[t]===void 0?e[t]=p:e[t]=[e[t],p].flat())&&e||e,{}),m=({base:r="",routes:e=[]}={})=>({__proto__:new Proxy({},{get:(t,p,o)=>(a,...n)=>e.push([p.toUpperCase(),RegExp(`^${(r+a).replace(/(\/?)\*/g,"($1.*)?").replace(/(\/$)|((?<=\/)\/)/,"").replace(/(:(\w+)\+)/,"(?<$2>.*)").replace(/:(\w+)(\?)?(\.)?/g,"$2(?<$1>[^/]+)$2$3").replace(/\.(?=[\w(])/,"\\.").replace(/\)\.\?\(([^\[]+)\[\^/g,"?)\\.?($1(?<=\\.)[^\\.")}/*$`),n])&&o}),routes:e,async handle(t,...p){let o,a,n=new URL(t.url);t.query=$(n.searchParams);for(let[s,R,l]of e)if((s===t.method||s==="ALL")&&(a=n.pathname.match(R))){t.params=a.groups;for(let y of l)if((o=await y(t.proxy||t,...p))!==void 0)return o}}});0&&(module.exports={Router});
+"use strict";var u=Object.defineProperty;var l=Object.getOwnPropertyDescriptor;var d=Object.getOwnPropertyNames;var g=Object.prototype.hasOwnProperty;var h=(r,e)=>{for(var t in e)u(r,t,{get:e[t],enumerable:!0})},x=(r,e,t,n)=>{if(e&&typeof e=="object"||typeof e=="function")for(let o of d(e))!g.call(r,o)&&o!==t&&u(r,o,{get:()=>e[o],enumerable:!(n=l(e,o))||n.enumerable});return r};var f=r=>x(u({},"__esModule",{value:!0}),r);var m={};h(m,{Router:()=>c});module.exports=f(m);var T=r=>[...r.entries()].reduce((e,[t,n])=>(e[t]===void 0?e[t]=n:e[t]=[e[t],n].flat())&&e||e,{}),c=({base:r="",routes:e=[]}={})=>({__proto__:new Proxy({},{get:(t,n,o)=>(p,...a)=>e.push([n.toUpperCase(),RegExp(`^${(r+p).replace(/(\/?)\*/g,"($1.*)?").replace(/(\/$)|((?<=\/)\/)/,"").replace(/(:(\w+)\+)/,"(?<$2>.*)").replace(/:(\w+)(\?)?(\.)?/g,"$2(?<$1>[^/]+)$2$3").replace(/\.(?=[\w(])/,"\\.").replace(/\)\.\?\(([^\[]+)\[\^/g,"?)\\.?($1(?<=\\.)[^\\.")}/*$`),a])&&o}),routes:e,async handle(t,...n){let o,p,a=new URL(t.url);t.query=T(a.searchParams);for(let[s,R,y]of e)if((s===t.method||s==="ALL")&&(p=a.pathname.match(R))){t.params=p.groups||{};for(let i of y)if((o=await i(t.proxy||t,...n))!==void 0)return o}}});0&&(module.exports={Router});

package/dist/itty-router.mjs

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itty-router",
-  "version": "3.0.3",
+  "version": "3.0.5",
   "description": "Tiny, zero-dependency API router - built for Cloudflare Workers, but works everywhere!",
   "sourceType": "module",
   "main": "./dist/itty-router.js",