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()
@@ -29,61 +121,62 @@ router.cors()
 
 // Register global middleware
 router.use(({ req, res, next }) => {
-  res.headers.set('X-Global-Middlewares', 'true')
+    res.headers.set('X-Global-Middlewares', 'true')
-  next()
+    next()
 })
 
 // Simple get
 router.get('/user', ({ req, res }) => {
-  res.body = {
+    res.body = {
-    data: {
+        data: {
-      id: 1,
+            id: 1,
-      name: 'John Doe'
+            name: 'John Doe'
+        }
     }
-  }
 })
 
 // Post route with url parameter
 router.post('/user/:id', ({ req, res }) => {
 
-  const userId = req.params.id
+    const userId = req.params.id
-  
+
-  // Do stuff...
+    // Do stuff...
-  
+
-  if (errorDoingStuff) {
+        if (errorDoingStuff) {
-    res.status = 400
+            res.status = 400
-    res.body = {
+            res.body = {
-      error: 'User did stupid stuff!'
+                error: 'User did stupid stuff!'
-    }
+            }
-    return
+            return
-  }
+        }
-  
+
-  res.status = 204
+    res.status = 204
 })
 
 // Delete route using a middleware
 router.delete('/user/:id', ({ req, res, next }) => {
 
-  if (!apiTokenIsCorrect) {
+    if (!apiTokenIsCorrect) {
-    res.status = 401
+        res.status = 401
-    return
+        return
-  }
+    }
-  
+
-  await next()
+    await next()
 }, (req, res) => {
 
-  const userId = req.params.id
+    const userId = req.params.id
-  
+
-  // Do stuff...
+    // Do stuff...
 })
 
 // Listen Cloudflare Workers Fetch Event
 export default {
-  async fetch(request, env) {
+    async fetch(request, env) {
-    return router.handle(env, request)
+        return router.handle(env, request)
-  }
+    }
 }
 ```
+</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

@@ -1,28 +1,28 @@
 /**
  * Route Object
- * 
+ *
  * @typedef Route
  * @property {string} method HTTP request method
  * @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>[]
 }
 
 /**
  * Router Context
- * 
+ *
  * @typedef RouterContext
  * @property {RouterEnv} env Environment
  * @property {RouterRequest} req Request Object
  * @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
@@ -30,7 +30,7 @@ export interface RouterContext {
 
 /**
  * Request Object
- * 
+ *
  * @typedef RouterRequest
  * @property {string} url URL
  * @property {string} method HTTP request method
@@ -53,7 +53,7 @@ export interface RouterRequest {
 
 /**
  * Request Parameters
- * 
+ *
  * @typedef RouterRequestParams
  */
 export interface RouterRequestParams {
@@ -62,7 +62,7 @@ export interface RouterRequestParams {
 
 /**
  * Request Query
- * 
+ *
  * @typedef RouterRequestQuery
  */
 export interface RouterRequestQuery {
@@ -71,7 +71,7 @@ export interface RouterRequestQuery {
 
 /**
  * Response Object
- * 
+ *
  * @typedef RouterResponse
  * @property {Headers} headers Response headers object
  * @property {number} [status=204] Return status code (default: `204`)
@@ -88,7 +88,7 @@ export interface RouterResponse {
 
 /**
  * Next Function
- * 
+ *
  * @callback RouterNext
  * @returns {Promise<void>}
  */
@@ -98,18 +98,18 @@ export interface RouterNext {
 
 /**
  * Handler Function
- * 
+ *
  * @callback RouterHandler
  * @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
 }
 
 /**
  * CORS Config
- * 
+ *
  * @typedef RouterCorsConfig
  * @property {string} [allowOrigin="*"] Access-Control-Allow-Origin (default: `*`)
  * @property {string} [allowMethods="*"] Access-Control-Allow-Methods (default: `*`)
@@ -127,31 +127,31 @@ export interface RouterCorsConfig {
 
 /**
  * Router
- * 
+ *
  * @public
  * @class
  */
-export default class Router {
+export class Router<TEnv = any> {
 
     /**
      * Router Array
-     * 
+     *
      * @protected
      * @type {Route[]}
      */
-    protected routes: Route[] = []
+    protected routes: Route<TEnv>[] = []
 
     /**
      * Global Handlers
-     * 
+     *
      * @protected
      * @type {RouterHandler[]}
      */
-    protected globalHandlers: RouterHandler[] = []
+    protected globalHandlers: RouterHandler<TEnv>[] = []
 
     /**
      * Debug Mode
-     * 
+     *
      * @protected
      * @type {boolean}
      */
@@ -159,7 +159,7 @@ export default class Router {
 
     /**
      * CORS Config
-     * 
+     *
      * @protected
      * @type {RouterCorsConfig}
      */
@@ -175,11 +175,11 @@ export default class Router {
 
     /**
      * 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)
         }
@@ -188,132 +188,132 @@ export default class Router {
 
     /**
      * Register CONNECT route
-     * 
+     *
-     * @param {string} url 
+     * @param {string} url
-     * @param  {RouterHandler[]} handlers 
+     * @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)
     }
 
     /**
      * Register DELETE route
-     * 
+     *
-     * @param {string} url 
+     * @param {string} url
-     * @param  {RouterHandler[]} handlers 
+     * @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)
     }
 
     /**
      * Register GET route
-     * 
+     *
-     * @param {string} url 
+     * @param {string} url
-     * @param  {RouterHandler[]} handlers 
+     * @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)
     }
 
     /**
      * Register HEAD route
-     * 
+     *
-     * @param {string} url 
+     * @param {string} url
-     * @param  {RouterHandler[]} handlers 
+     * @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)
     }
 
     /**
      * Register OPTIONS route
-     * 
+     *
-     * @param {string} url 
+     * @param {string} url
-     * @param  {RouterHandler[]} handlers 
+     * @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)
     }
 
     /**
      * Register PATCH route
-     * 
+     *
-     * @param {string} url 
+     * @param {string} url
-     * @param  {RouterHandler[]} handlers 
+     * @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)
     }
 
     /**
      * Register POST route
-     * 
+     *
-     * @param {string} url 
+     * @param {string} url
-     * @param  {RouterHandler[]} handlers 
+     * @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)
     }
 
     /**
      * Register PUT route
-     * 
+     *
-     * @param {string} url 
+     * @param {string} url
-     * @param  {RouterHandler[]} handlers 
+     * @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)
     }
 
     /**
      * Register TRACE route
-     * 
+     *
-     * @param {string} url 
+     * @param {string} url
-     * @param  {RouterHandler[]} handlers 
+     * @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)
     }
 
     /**
      * Register route, ignoring method
-     * 
+     *
-     * @param {string} url 
+     * @param {string} url
-     * @param  {RouterHandler[]} handlers 
+     * @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)
     }
 
     /**
      * Debug Mode
-     * 
+     *
      * @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
     }
 
     /**
      * Enable CORS support
-     * 
+     *
      * @param {RouterCorsConfig} [config]
      * @returns {Router}
      */
-    public cors(config?: RouterCorsConfig): Router {
+    public cors(config?: RouterCorsConfig): Router<TEnv> {
         this.corsEnabled = true
         this.corsConfig = {
             allowOrigin: config?.allowOrigin || '*',
@@ -327,14 +327,14 @@ export default class Router {
 
     /**
      * Register route
-     * 
+     *
      * @private
      * @param {string} method HTTP request method
      * @param {string} url URL String
      * @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,
@@ -346,12 +346,12 @@ export default class Router {
 
     /**
      * Get Route by request
-     * 
+     *
      * @private
      * @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)
 
@@ -387,13 +387,13 @@ 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,