2.3.0

README.md

@@ -1,6 +1,6 @@
 # Cloudflare Workers Router
 
-Cloudflare Workers Router is a super lightweight router (2.30 KiB) with middleware support and **ZERO dependencies** for [Cloudflare Workers](https://workers.cloudflare.com/).
+Cloudflare Workers Router is a super lightweight router (1.3K gzipped) with middleware support and **ZERO dependencies** for [Cloudflare Workers](https://workers.cloudflare.com/).
 
 When I was trying out Cloudflare Workers I almost immediately noticed how fast it was compared to other serverless offerings. So I wanted to build a full-fledged API to see how it performs doing real work, but since I wasn't able to find a router that suited my needs I created my own.
 
@@ -9,17 +9,109 @@ I worked a lot with [Express.js](https://expressjs.com/) in the past and really
 
 ## Contents
 
+- [Features](#features)
 - [Usage](#usage)
 - [Reference](#reference)
 - [Setup](#setup)
 
 
+## Features
+
+- ZERO dependencies
+- Lightweight (1.3K gzipped)
+- Fully written in TypeScript
+- Integrated Debug-Mode & CORS helper
+- Built specifically around Middlewares
+
+
 ## Usage
 
-### Simple Example
+### TypeScript Example
+
+```typescript
+import { Router } from '@tsndr/cloudflare-worker-router'
+
+export interface Env {
+    // Example binding to KV. Learn more at https://developers.cloudflare.com/workers/runtime-apis/kv/
+    // MY_KV_NAMESPACE: KVNamespace
+    //
+    // Example binding to Durable Object. Learn more at https://developers.cloudflare.com/workers/runtime-apis/durable-objects/
+    // MY_DURABLE_OBJECT: DurableObjectNamespace
+    //
+    // Example binding to R2. Learn more at https://developers.cloudflare.com/workers/runtime-apis/r2/
+    // MY_BUCKET: R2Bucket
+}
+
+
+// Initialize router
+const router = new Router<Env>()
+
+// Enabling build in CORS support
+router.cors()
+
+// Register global middleware
+router.use(({ req, res, next }) => {
+    res.headers.set('X-Global-Middlewares', 'true')
+    next()
+})
+
+// Simple get
+router.get('/user', ({ req, res }) => {
+    res.body = {
+        data: {
+            id: 1,
+            name: 'John Doe'
+        }
+    }
+})
+
+// Post route with url parameter
+router.post('/user/:id', ({ req, res }) => {
+
+    const userId = req.params.id
+
+    // Do stuff...
+
+    if (errorDoingStuff) {
+        res.status = 400
+        res.body = {
+            error: 'User did stupid stuff!'
+        }
+        return
+    }
+
+    res.status = 204
+})
+
+// Delete route using a middleware
+router.delete('/user/:id', ({ req, res, next }) => {
+
+    if (!apiTokenIsCorrect) {
+        res.status = 401
+        return
+    }
+
+    await next()
+}, (req, res) => {
+
+    const userId = req.params.id
+
+    // Do stuff...
+})
+
+// Listen Cloudflare Workers Fetch Event
+export default {
+    async fetch(request: Request, env: Env): Promise<Response> {
+        return router.handle(env, request)
+    }
+}
+```
+
+<details>
+    <summary>JavaScript Example</summary>
 
 ```javascript
-import Router from '@tsndr/cloudflare-worker-router'
+import { Router } from '@tsndr/cloudflare-worker-router'
 
 // Initialize router
 const router = new Router()
@@ -84,6 +176,7 @@ export default {
     }
 }
 ```
+</details>
 
 
 ## Reference
@@ -96,6 +189,10 @@ Enable or disable debug mode. Which will return the `error.stack` in case of an
 #### `state`
 State is a `boolean` which determines if debug mode should be enabled or not (default: `true`)
 
+Key                    | Type      | Default Value
+---------------------- | --------- | -------------
+`state`                | `boolean` | `true`
+
 
 ### `router.use([...handlers])`
 
@@ -106,7 +203,9 @@ Register a global middleware handler.
 
 Handler is a `function` which will be called for every request.
 
+
 #### `ctx`
+
 Object containing `env`, [`req`](#req-object), [`res`](#res-object), `next`
 
 
@@ -126,16 +225,19 @@ Key                    | Type      | Default Value
 `optionsSuccessStatus` | `integer` | `204`
 
 
-### `router.any(url, [...handlers])`
+### Supported Methods
-### `router.connect(url, [...handlers])`
+
-### `router.delete(url, [...handlers])`
+- `router.any(url, [...handlers])`
-### `router.get(url, [...handlers])`
+- `router.connect(url, [...handlers])`
-### `router.head(url, [...handlers])`
+- `router.delete(url, [...handlers])`
-### `router.options(url, [...handlers])`
+- `router.get(url, [...handlers])`
-### `router.patch(url, [...handlers])`
+- `router.head(url, [...handlers])`
-### `router.post(url, [...handlers])`
+- `router.options(url, [...handlers])`
-### `router.put(url, [...handlers])`
+- `router.patch(url, [...handlers])`
-### `router.trace(url, [...handlers])`
+- `router.post(url, [...handlers])`
+- `router.put(url, [...handlers])`
+- `router.trace(url, [...handlers])`
+
 
 #### `url` (string)
 
@@ -180,32 +282,55 @@ Key         | Type                | Description
 
 ## Setup
 
-Please follow Cloudflare's [Get started guide](https://developers.cloudflare.com/workers/get-started/guide/) to install wrangler, then install the router using this command:
+Please follow Cloudflare's [Get started guide](https://developers.cloudflare.com/workers/get-started/guide/) to install wrangler.
+
+
+#### Initialize Project
+
+```bash
+wrangler init <name>
+```
+
+Use of TypeScript is strongly encouraged :)
 
 ```bash
 npm i -D @tsndr/cloudflare-worker-router
 ```
 
-and replace your `index.ts` / `index.js` with one of the following scripts
 
-<details>
+### TypeScript (<code>src/index.ts</code>)
-<summary>TypeScript (<code>src/index.ts</code>)</summary>
 
 ```typescript
-import Router from '@tsndr/cloudflare-worker-router'
+import { Router } from '@tsndr/cloudflare-worker-router'
 
 export interface Env {
   // Example binding to KV. Learn more at https://developers.cloudflare.com/workers/runtime-apis/kv/
-  // MY_KV_NAMESPACE: KVNamespace;
+  // MY_KV_NAMESPACE: KVNamespace
   //
   // Example binding to Durable Object. Learn more at https://developers.cloudflare.com/workers/runtime-apis/durable-objects/
-  // MY_DURABLE_OBJECT: DurableObjectNamespace;
+  // MY_DURABLE_OBJECT: DurableObjectNamespace
   //
   // Example binding to R2. Learn more at https://developers.cloudflare.com/workers/runtime-apis/r2/
-  // MY_BUCKET: R2Bucket;
+  // MY_BUCKET: R2Bucket
 }
 
-const router = new Router()
+const router = new Router<Env>()
+
+/// Example Route
+//
+// router.get(/'hi', ({ res }) => {
+//    res.body = 'Hello World'
+//}
+
+
+/// Example Route for splitting into multiple files
+//
+// const hiHandler: RouteHandler<Env> = ({ res }) => {
+//     res.body = 'Hello World'
+// }
+//
+// router.get('/hi', hiHandler)
+
 
 // TODO: add your routes here
 
@@ -215,16 +340,22 @@ export default {
     }
 }
 ```
-</details>
+
+
+### JavaScript (<code>src/index.js</code>)
 
 <details>
-<summary>JavaScript (<code>src/index.js</code>)</summary>
+    <summary>Consider using TypeScript instead :)</summary>
 
 ```javascript
-import Router from '@tsndr/cloudflare-worker-router'
+import { Router } from '@tsndr/cloudflare-worker-router'
 
 const router = new Router()
 
+// router.get(/'hi', ({ res }) => {
+//    res.body = 'Hello World'
+//}
+
 // TODO: add your routes here
 
 export default {
@@ -233,4 +364,3 @@ export default {
     }
 }
 ```
-</details>

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@tsndr/cloudflare-worker-router",
-  "version": "2.1.2",
+  "version": "2.3.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@tsndr/cloudflare-worker-router",
-      "version": "2.1.2",
+      "version": "2.3.0",
       "license": "MIT",
       "devDependencies": {
         "@cloudflare/workers-types": "^3.13.0",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tsndr/cloudflare-worker-router",
-  "version": "2.1.2",
+  "version": "2.3.0",
   "description": "",
   "main": "index.js",
   "types": "index.d.ts",

src/index.ts

@@ -6,10 +6,10 @@
  * @property {string} url URL String
  * @property {RouterHandler[]} handlers Array of handler functions
  */
- export interface Route {
+ export interface Route<TEnv> {
     method: string
     url: string
-    handlers: RouterHandler[]
+    handlers: RouterHandler<TEnv>[]
 }
 
 /**
@@ -21,8 +21,8 @@
  * @property {RouterResponse} res Response Object
  * @property {RouterNext} next Next Handler
  */
-export interface RouterContext {
+export interface RouterContext<TEnv> {
-    env: any
+    env: TEnv
     req: RouterRequest
     res: RouterResponse
     next: RouterNext
@@ -103,8 +103,8 @@ export interface RouterNext {
  * @param {RouterContext} ctx
  * @returns {Promise<void> | void}
  */
-export interface RouterHandler {
+export interface RouterHandler<TEnv = any> {
-    (ctx: RouterContext): Promise<void> | void
+    (ctx: RouterContext<TEnv>): Promise<void> | void
 }
 
 /**
@@ -131,7 +131,7 @@ export interface RouterCorsConfig {
  * @public
  * @class
  */
-export default class Router {
+export class Router<TEnv = any> {
 
     /**
      * Router Array
@@ -139,7 +139,7 @@ export default class Router {
      * @protected
      * @type {Route[]}
      */
-    protected routes: Route[] = []
+    protected routes: Route<TEnv>[] = []
 
     /**
      * Global Handlers
@@ -147,7 +147,7 @@ export default class Router {
      * @protected
      * @type {RouterHandler[]}
      */
-    protected globalHandlers: RouterHandler[] = []
+    protected globalHandlers: RouterHandler<TEnv>[] = []
 
     /**
      * Debug Mode
@@ -179,7 +179,7 @@ export default class Router {
      * @param {RouterHandler[]} handlers
      * @returns {Router}
      */
-    public use(...handlers: RouterHandler[]): Router {
+    public use(...handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         for (let handler of handlers) {
             this.globalHandlers.push(handler)
         }
@@ -193,7 +193,7 @@ export default class Router {
      * @param  {RouterHandler[]} handlers
      * @returns {Router}
      */
-    public connect(url: string, ...handlers: RouterHandler[]): Router {
+    public connect(url: string, ...handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         return this.register('CONNECT', url, handlers)
     }
 
@@ -204,7 +204,7 @@ export default class Router {
      * @param  {RouterHandler[]} handlers
      * @returns {Router}
      */
-    public delete(url: string, ...handlers: RouterHandler[]): Router {
+    public delete(url: string, ...handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         return this.register('DELETE', url, handlers)
     }
 
@@ -215,7 +215,7 @@ export default class Router {
      * @param  {RouterHandler[]} handlers
      * @returns {Router}
      */
-    public get(url: string, ...handlers: RouterHandler[]): Router {
+    public get(url: string, ...handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         return this.register('GET', url, handlers)
     }
 
@@ -226,7 +226,7 @@ export default class Router {
      * @param  {RouterHandler[]} handlers
      * @returns {Router}
      */
-    public head(url: string, ...handlers: RouterHandler[]): Router {
+    public head(url: string, ...handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         return this.register('HEAD', url, handlers)
     }
 
@@ -237,7 +237,7 @@ export default class Router {
      * @param  {RouterHandler[]} handlers
      * @returns {Router}
      */
-    public options(url: string, ...handlers: RouterHandler[]): Router {
+    public options(url: string, ...handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         return this.register('OPTIONS', url, handlers)
     }
 
@@ -248,7 +248,7 @@ export default class Router {
      * @param  {RouterHandler[]} handlers
      * @returns {Router}
      */
-    public patch(url: string, ...handlers: RouterHandler[]): Router {
+    public patch(url: string, ...handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         return this.register('PATCH', url, handlers)
     }
 
@@ -259,7 +259,7 @@ export default class Router {
      * @param  {RouterHandler[]} handlers
      * @returns {Router}
      */
-    public post(url: string, ...handlers: RouterHandler[]): Router {
+    public post(url: string, ...handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         return this.register('POST', url, handlers)
     }
 
@@ -270,7 +270,7 @@ export default class Router {
      * @param  {RouterHandler[]} handlers
      * @returns {Router}
      */
-    public put(url: string, ...handlers: RouterHandler[]): Router {
+    public put(url: string, ...handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         return this.register('PUT', url, handlers)
     }
 
@@ -281,7 +281,7 @@ export default class Router {
      * @param  {RouterHandler[]} handlers
      * @returns {Router}
      */
-    public trace(url: string, ...handlers: RouterHandler[]): Router {
+    public trace(url: string, ...handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         return this.register('TRACE', url, handlers)
     }
 
@@ -292,7 +292,7 @@ export default class Router {
      * @param  {RouterHandler[]} handlers
      * @returns {Router}
      */
-    public any(url: string, ...handlers: RouterHandler[]): Router {
+    public any(url: string, ...handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         return this.register('*', url, handlers)
     }
 
@@ -302,7 +302,7 @@ export default class Router {
      * @param {boolean} [state=true] Whether to turn on or off debug mode (default: true)
      * @returns {Router}
      */
-    public debug(state: boolean = true): Router {
+    public debug(state: boolean = true): Router<TEnv> {
         this.debugMode = state
         return this
     }
@@ -313,7 +313,7 @@ export default class Router {
      * @param {RouterCorsConfig} [config]
      * @returns {Router}
      */
-    public cors(config?: RouterCorsConfig): Router {
+    public cors(config?: RouterCorsConfig): Router<TEnv> {
         this.corsEnabled = true
         this.corsConfig = {
             allowOrigin: config?.allowOrigin || '*',
@@ -334,7 +334,7 @@ export default class Router {
      * @param {RouterHandler[]} handlers Arrar of handler functions
      * @returns {Router}
      */
-    private register(method: string, url: string, handlers: RouterHandler[]): Router {
+    private register(method: string, url: string, handlers: RouterHandler<TEnv>[]): Router<TEnv> {
         this.routes.push({
             method,
             url,
@@ -351,7 +351,7 @@ export default class Router {
      * @param {RouterRequest} request
      * @returns {Route | undefined}
      */
-    private getRoute(request: RouterRequest): Route | undefined {
+    private getRoute(request: RouterRequest): Route<TEnv> | undefined {
         const url = new URL(request.url)
         const pathArr = url.pathname.split('/').filter(i => i)
 
@@ -388,12 +388,12 @@ export default class Router {
     /**
      * Handle requests
      *
-     * @param {any} env
+     * @param {TEnv} env
      * @param {Request} request
      * @param {any} [extend]
      * @returns {Promise<Response>}
      */
-    public async handle(env: any, request: Request, extend: any = {}): Promise<Response> {
+    public async handle(env: TEnv, request: Request, extend: any = {}): Promise<Response> {
         try {
             const req: RouterRequest = {
                 ...extend,