itty-router 2.4.9 → 2.5.1

package/CHANGELOG.md

@@ -1,7 +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.
 
-- **v2.4.7** - fixed the cursed "optional" file format capturing bug - RIP all the bytes lost
+[@SupremeTechnopriest)(https://github.com/SupremeTechnopriest) - improved TypeScript support and documentation! :D\
+
+- **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
 - **v2.4.0** - HUGE internal code-golfing refactor thanks to [@taralx](https://github.com/taralx)!  Super cool work on this!!!

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`
@@ -436,8 +554,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 +569,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "itty-router",
-  "version": "2.4.9",
+  "version": "2.5.1",
   "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",