itty-router 3.0.2 → 3.0.4

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)
 
@@ -13,17 +13,41 @@
 
 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!  
+Version 3 introduces itty as a TypeScript-first library.  This version should break no existing JS users, but TS users may have to update their types, as shown below.  Please [join the discussion on Discord](https://discord.gg/53vyrZAu9u) to assist in this rollout!  In the meantime, thanks everyone for your patience!  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 v3.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)
+  
+  // GET /get-file/with/a/long/path.png => { path: "with/a/long/path.png" }
+  ```
+    
+2. Query params with multiple same-name values now operate as you would expect (previously, they overwrote each other)
+  ```js
+  router.handle('/foo', ({ query }) => query)
+  
+  // 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.
 2. [itty-durable](https://www.npmjs.com/package/itty-durable) - 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 ([~500 bytes](https://bundlephobia.com/package/itty-router) compressed), with zero dependencies.
+- [x] Tiny ([~780 bytes](https://bundlephobia.com/package/itty-router) compressed), with zero dependencies.
 - [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.
@@ -128,14 +152,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],
   }
 }
 */
@@ -292,16 +317,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
+                                      })
 }
 ```
 
@@ -390,104 +415,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.2",
+  "version": "3.0.4",
   "description": "Tiny, zero-dependency API router - built for Cloudflare Workers, but works everywhere!",
   "sourceType": "module",
   "main": "./dist/itty-router.js",