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,22 +9,114 @@ 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()
 
-// Enabling buildin CORS support
+// Enabling build in CORS support
 router.cors()
 
 // Register global middleware
@@ -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,46 +282,55 @@ Key         | Type                | Description
 
 ## Setup
 
----
+Please follow Cloudflare's [Get started guide](https://developers.cloudflare.com/workers/get-started/guide/) to install wrangler.
-### ❗️ Compatibility ❗️
 
-CLI Tool | Router
--------- | ------
-[wrangler2](https://github.com/cloudflare/wrangler2#readme) | Use `v2.x.x` or later.
-[@cloudflare/wrangler](https://github.com/cloudflare/wrangler#readme) | Use `v1.x.x`, [here](https://github.com/tsndr/cloudflare-worker-router/tree/legacy#readme).
 
-See [Migration from v1.x.x to v2.x.x](https://github.com/tsndr/cloudflare-worker-router/blob/main/MIGRATION.md#migration-guide) if you want to update.
+#### Initialize Project
 
----
+```bash
+wrangler init <name>
+```
 
-### **[Wrangler2](https://github.com/cloudflare/wrangler2#readme)**
+Use of TypeScript is strongly encouraged :)
-
-Please follow Cloudflare's [Get started guide](https://developers.cloudflare.com/workers/get-started/guide/), then install the router using this command
 
 ```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
 
@@ -229,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 {
@@ -247,4 +364,3 @@ export default {
     }
 }
 ```
-</details>

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@tsndr/cloudflare-worker-router",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "lockfileVersion": 2,
   "requires": true,
   "packages": {
     "": {
       "name": "@tsndr/cloudflare-worker-router",
-      "version": "2.1.0",
+      "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.0",
+  "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
@@ -165,13 +165,21 @@ export default class Router {
      */
     protected corsConfig: RouterCorsConfig = {}
 
+    /**
+     * CORS enabled
+     *-
+     * @protected
+     * @type {boolean}
+     */
+    protected corsEnabled: boolean = false
+
     /**
      * Register global handlers
      *
      * @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)
         }
@@ -185,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)
     }
 
@@ -196,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)
     }
 
@@ -207,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)
     }
 
@@ -218,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)
     }
 
@@ -229,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)
     }
 
@@ -240,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)
     }
 
@@ -251,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)
     }
 
@@ -262,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)
     }
 
@@ -273,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)
     }
 
@@ -284,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)
     }
 
@@ -294,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
     }
@@ -305,11 +313,12 @@ 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 || '*',
             allowMethods: config?.allowMethods || '*',
-            allowHeaders: config?.allowHeaders || '*, Authorization',
+            allowHeaders: config?.allowHeaders || '*',
             maxAge: config?.maxAge || 86400,
             optionsSuccessStatus: config?.optionsSuccessStatus || 204
         }
@@ -325,12 +334,13 @@ 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,
             handlers
         })
+
         return this
     }
 
@@ -341,26 +351,36 @@ 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)
+
         return this.routes.find(r => {
             const routeArr = r.url.split('/').filter(i => i)
+
             if (![request.method, '*'].includes(r.method) || routeArr.length !== pathArr.length)
                 return false
+
             const params: RouterRequestParams = {}
+
             for (let i = 0; i < routeArr.length; i++) {
                 if (routeArr[i] !== pathArr[i] && routeArr[i][0] !== ':')
                     return false
+
                 if (routeArr[i][0] === ':')
                     params[routeArr[i].substring(1)] = pathArr[i]
             }
+
             request.params = params
+
             const query: any = {}
+
             for (const [k, v] of url.searchParams.entries()) {
                 query[k] = v
             }
+
             request.query = query
+
             return true
         }) || this.routes.find(r => r.url === '*' && [request.method, '*'].includes(r.method))
     }
@@ -368,12 +388,12 @@ export default class Router {
     /**
      * Handle requests
      *
-     * @param {any} env
+     * @param {TEnv} env
      * @param {Request} request
      * @param {any} [extend]
-     * @returns {Response}
+     * @returns {Promise<Response>}
      */
-    public async handle(env: any, request: Request, extend: any = {}) {
+    public async handle(env: TEnv, request: Request, extend: any = {}): Promise<Response> {
         try {
             const req: RouterRequest = {
                 ...extend,
@@ -387,7 +407,9 @@ export default class Router {
             }
 
             const headers = new Headers()
+            const route = this.getRoute(req)
 
+            if (this.corsEnabled) {
                 if (this.corsConfig.allowOrigin)
                     headers.set('Access-Control-Allow-Origin', this.corsConfig.allowOrigin)
                 if (this.corsConfig.allowMethods)
@@ -397,12 +419,17 @@ export default class Router {
                 if (this.corsConfig.maxAge)
                     headers.set('Access-Control-Max-Age', this.corsConfig.maxAge.toString())
 
-            if (req.method === 'OPTIONS') {
+                if (!route && req.method === 'OPTIONS') {
                     return new Response(null, {
                         headers,
                         status: this.corsConfig.optionsSuccessStatus
                     })
                 }
+            }
+
+            if (!route)
+                return new Response(this.debugMode ? 'Route not found!' : null, { status: 404 })
+
             if (['POST', 'PUT', 'PATCH'].includes(req.method)) {
                 if (req.headers.has('Content-Type') && req.headers.get('Content-Type')!.includes('json')) {
                     try {
@@ -418,27 +445,33 @@ export default class Router {
                     }
                 }
             }
-            const route = this.getRoute(req)
+
-            if (!route)
-                return new Response(this.debugMode ? 'Route not found!' : null, { status: 404 })
             const res: RouterResponse = { headers }
             const handlers = [...this.globalHandlers, ...route.handlers]
             let prevIndex = -1
+
             const runner = async (index: number) => {
                 if (index === prevIndex)
                     throw new Error('next() called multiple times')
+
                 prevIndex = index
+
                 if (typeof handlers[index] === 'function')
                     await handlers[index]({ env, req, res, next: async () => await runner(index + 1) })
             }
+
             await runner(0)
+
             if (typeof res.body === 'object') {
                 if (!res.headers.has('Content-Type'))
                     res.headers.set('Content-Type', 'application/json')
+
                 res.body = JSON.stringify(res.body)
             }
+
             if (res.raw)
                 return res.raw
+
             return new Response([101, 204, 205, 304].includes(res.status || (res.body ? 200 : 204)) ? null : res.body, { status: res.status, headers: res.headers, webSocket: res.webSocket || null })
         } catch(err) {
             console.error(err)