hono 0.3.8 → 0.4.2

package/README.md

@@ -1,6 +1,14 @@
 # Hono
 
-Hono[炎] - _**means flame🔥 in Japanese**_ - is small, simple, and ultrafast web framework for a Service Workers API based serverless such as Cloudflare Workers and Fastly Compute@Edge.
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/yusukebe/hono/ci)](https://github.com/yusukebe/hono/actions)
+[![GitHub](https://img.shields.io/github/license/yusukebe/hono)](https://github.com/yusukebe/hono/blob/master/LICENSE)
+[![npm](https://img.shields.io/npm/v/hono)](https://www.npmjs.com/package/hono)
+[![npm](https://img.shields.io/npm/dm/hono)](https://www.npmjs.com/package/hono)
+[![npm type definitions](https://img.shields.io/npm/types/hono)](https://www.npmjs.com/package/hono)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/yusukebe/hono)](https://github.com/yusukebe/hono/pulse)
+[![GitHub last commit](https://img.shields.io/github/last-commit/yusukebe/hono)](https://github.com/yusukebe/hono/commits/master)
+
+Hono[炎] - _**means flame🔥 in Japanese**_ - is small, simple, and ultrafast web framework for Service Worker based serverless applications like Cloudflare Workers and Fastly Compute@Edge.
 
 ```js
 import { Hono } from 'hono'
@@ -13,9 +21,9 @@ app.fire()
 
 ## Features
 
-- **Ultra fast** - the router is implemented with Trie-Tree structure. Not use loops.
-- **Zero dependencies** - using only Web standard API.
-- **Middleware** - builtin middleware, and you can make your own middleware.
+- **Ultrafast** - the router does not use linear loops.
+- **Zero-dependencies** - using only Web standard API.
+- **Middleware** - builtin middleware and your own middleware.
 - **Optimized** - for Cloudflare Workers.
 
 ## Benchmark
@@ -23,37 +31,41 @@ app.fire()
 **Hono is fastest** compared to other routers for Cloudflare Workers.
 
 ```plain
-hono x 708,671 ops/sec ±2.58% (58 runs sampled)
-itty-router x 159,610 ops/sec ±2.86% (87 runs sampled)
-sunder x 322,846 ops/sec ±2.24% (86 runs sampled)
-worktop x 223,625 ops/sec ±2.01% (95 runs sampled)
+hono x 779,197 ops/sec ±6.55% (78 runs sampled)
+itty-router x 161,813 ops/sec ±3.87% (87 runs sampled)
+sunder x 334,096 ops/sec ±1.33% (93 runs sampled)
+worktop x 212,661 ops/sec ±4.40% (81 runs sampled)
 Fastest is hono
-✨  Done in 57.83s.
+✨  Done in 58.29s.
 ```
 
 ## Hono in 1 minute
 
-Below is a demonstration to create an application of Cloudflare Workers with Hono.
+A demonstration to create an application of Cloudflare Workers with Hono.
 
 ![Demo](https://user-images.githubusercontent.com/10682/151973526-342644f9-71c5-4fee-81f4-64a7558bb192.gif)
 
+Now, the named path parameter has types.
+
+![Demo](https://user-images.githubusercontent.com/10682/154179671-9e491597-6778-44ac-a8e6-4483d7ad5393.png)
+
 ## Install
 
-You can install from npm registry:
+You can install Hono from the npm registry.
 
 ```sh
-yarn add hono
+$ yarn add hono
 ```
 
 or
 
 ```sh
-npm install hono
+$ npm install hono
 ```
 
 ## Methods
 
-Instance of `Hono` has these methods:
+An instance of `Hono` has these methods.
 
 - app.**HTTP_METHOD**(path, handler)
 - app.**all**(path, handler)
@@ -66,8 +78,6 @@ Instance of `Hono` has these methods:
 
 ### Basic
 
-`app.HTTP_METHOD`
-
 ```js
 // HTTP Methods
 app.get('/', (c) => c.text('GET /'))
@@ -77,11 +87,7 @@ app.post('/', (c) => c.text('POST /'))
 app.get('/wild/*/card', (c) => {
   return c.text('GET /wild/*/card')
 })
-```
-
-`app.all`
 
-```js
 // Any HTTP methods
 app.all('/hello', (c) => c.text('Any Method /hello'))
 ```
@@ -102,29 +108,33 @@ app.get('/post/:date{[0-9]+}/:title{[a-z]+}', (c) => {
   const date = c.req.param('date')
   const title = c.req.param('title')
   ...
+})
 ```
 
-### Chained Route
+### Nested route
 
 ```js
-app
-  .route('/api/book')
-    .get(() => {...})
-    .post(() => {...})
-    .put(() => {...})
+const book = app.route('/book')
+book.get('/', (c) => c.text('List Books')) // GET /book
+book.get('/:id', (c) => {
+  // GET /book/:id
+  const id = c.req.param('id')
+  return c.text('Get Book: ' + id)
+})
+book.post('/', (c) => c.text('Create Book')) // POST /book
 ```
 
-### Custom 404 Response
+### no strict
 
-You can customize 404 Not Found response:
+If `strict` is set `false`, `/hello`and`/hello/` are treated the same. Default is `true`.
 
 ```js
-app.get('*', (c) => {
-  return c.text('Custom 404 Error', 404)
-})
+const app = new Hono({ strict: false })
+
+app.get('/hello', (c) => c.text('/hello or /hello/'))
 ```
 
-## async/await
+### async/await
 
 ```js
 app.get('/fetch-url', async (c) => {
@@ -154,15 +164,13 @@ app.use(
     password: 'acoolproject',
   })
 )
-
-...
 ```
 
 Available builtin middleware are listed on [src/middleware](https://github.com/yusukebe/hono/tree/master/src/middleware).
 
 ### Custom Middleware
 
-You can write your own middleware:
+You can write your own middleware.
 
 ```js
 // Custom logger
@@ -180,22 +188,9 @@ app.use('/message/*', async (c, next) => {
 app.get('/message/hello', (c) => c.text('Hello Middleware!'))
 ```
 
-### Handling Error
-
-```js
-app.use('*', async (c, next) => {
-  try {
-    await next()
-  } catch (err) {
-    console.error(`${err}`)
-    c.res = c.text('Custom Error Message', { status: 500 })
-  }
-})
-```
-
 ## Context
 
-To handle Request and Reponse, you can use Context object:
+To handle Request and Reponse, you can use Context object.
 
 ### c.req
 
@@ -234,25 +229,26 @@ app.get('/welcome', (c) => {
   c.status(201)
 
   return c.body('Thank you for comming')
+})
+```
 
-  /*
-  Same as:
-  return new Response('Thank you for comming', {
-    status: 201,
-    statusText: 'Created',
-    headers: {
-      'X-Message': 'Hello',
-      'Content-Type': 'text/plain',
-      'Content-Length: '22'
-    }
-  })
-  */
+The Response is the same as below.
+
+```js
+new Response('Thank you for comming', {
+  status: 201,
+  statusText: 'Created',
+  headers: {
+    'X-Message': 'Hello',
+    'Content-Type': 'text/plain',
+    'Content-Length': '22',
+  },
 })
 ```
 
 ### c.text()
 
-Render text as `Content-Type:text/plain`:
+Render texts as `Content-Type:text/plain`.
 
 ```js
 app.get('/say', (c) => {
@@ -262,7 +258,7 @@ app.get('/say', (c) => {
 
 ### c.json()
 
-Render JSON as `Content-Type:application/json`:
+Render JSON as `Content-Type:application/json`.
 
 ```js
 app.get('/api', (c) => {
@@ -272,7 +268,7 @@ app.get('/api', (c) => {
 
 ### c.html()
 
-Render HTML as `Content-Type:text/html`:
+Render HTML as `Content-Type:text/html`.
 
 ```js
 app.get('/', (c) => {
@@ -280,9 +276,19 @@ app.get('/', (c) => {
 })
 ```
 
+### c.notFound()
+
+Return the default `404 Not Found` Response.
+
+```js
+app.get('/notfound', (c) => {
+  return c.notFound()
+})
+```
+
 ### c.redirect()
 
-Redirect, default status code is `302`:
+Redirect, default status code is `302`.
 
 ```js
 app.get('/redirect', (c) => c.redirect('/'))
@@ -321,9 +327,29 @@ app.get('*', async c => {
 })
 ```
 
+## Not Found
+
+You can write the default `404 Not Found` Response.
+
+```js
+app.notFound = (c) => {
+  return c.text('This is default 404 Not Found', 404)
+}
+```
+
+## Error handling
+
+You can handle errors in your way.
+
+```js
+app.onError = (err, c) => {
+  return c.text(`This is error message: ${err.mssage}`, 500)
+}
+```
+
 ## fire
 
-`app.fire()` do:
+`app.fire()` do this.
 
 ```js
 addEventListener('fetch', (event) => {
@@ -343,7 +369,7 @@ export default {
 }
 
 /*
-or just do this:
+or just do:
 export default app
 */
 ```
@@ -356,15 +382,15 @@ Let's write your first code for Cloudflare Workers with Hono.
 
 ### 1. Install Wrangler
 
-Install Cloudflare Command Line "[Wrangler](https://github.com/cloudflare/wrangler)"
+Install Cloudflare Command Line "[Wrangler](https://github.com/cloudflare/wrangler)".
 
 ```sh
-npm i @cloudflare/wrangler -g
+$ npm i @cloudflare/wrangler -g
 ```
 
 ### 2. `npm init`
 
-Make npm skeleton directory.
+Make a npm skeleton directory.
 
 ```sh
 mkdir hono-example
@@ -377,15 +403,15 @@ npm init -y
 Init as a wrangler project.
 
 ```sh
-wrangler init
+$ wrangler init
 ```
 
 ### 4. `npm install hono`
 
-Install `hono` from npm registry.
+Install `hono` from the npm registry.
 
 ```sh
-npm i hono
+$ npm i hono
 ```
 
 ### 5. Write your app
@@ -403,10 +429,10 @@ app.fire()
 
 ### 6. Run
 
-Run the development server locally. Then, access like `http://127.0.0.1:8787/` in your Web browser.
+Run the development server locally. Then, access `http://127.0.0.1:8787/` in your Web browser.
 
 ```sh
-wrangler dev
+$ wrangler dev
 ```
 
 ### 7. Publish
@@ -414,12 +440,22 @@ wrangler dev
 Deploy to Cloudflare. That's all!
 
 ```sh
-wrangler publish
+$ wrangler publish
+```
+
+## Starter template
+
+You can start making your application of Cloudflare Workers with [the starter template](https://github.com/yusukebe/hono-minimal). It is a realy minimal using TypeScript, esbuild, and Miniflare.
+
+To generate a project skelton, run this command.
+
+```
+$ wrangler generate my-app https://github.com/yusukebe/hono-minimal
 ```
 
 ## Related projects
 
-Implementation of the router is inspired by [goblin](https://github.com/bmf-san/goblin). API design is inspired by [express](https://github.com/expressjs/express) and [koa](https://github.com/koajs/koa). [itty-router](https://github.com/kwhitley/itty-router), [Sunder](https://github.com/SunderJS/sunder), and [worktop](https://github.com/lukeed/worktop) are the other routers or frameworks for Cloudflare Workers.
+Implementation of the original router `TrieRouter` is inspired by [goblin](https://github.com/bmf-san/goblin). `RegExpRouter` is inspired by [Router::Boom](https://github.com/tokuhirom/Router-Boom). API design is inspired by [express](https://github.com/expressjs/express) and [koa](https://github.com/koajs/koa). [itty-router](https://github.com/kwhitley/itty-router), [Sunder](https://github.com/SunderJS/sunder), and [worktop](https://github.com/lukeed/worktop) are the other routers or frameworks for Cloudflare Workers.
 
 - express <https://github.com/expressjs/express>
 - koa <https://github.com/koajs/koa>
@@ -427,10 +463,11 @@ Implementation of the router is inspired by [goblin](https://github.com/bmf-san/
 - Sunder <https://github.com/SunderJS/sunder>
 - goblin <https://github.com/bmf-san/goblin>
 - worktop <https://github.com/lukeed/worktop>
+- Router::Boom <https://github.com/tokuhirom/Router-Boom>
 
 ## Contributing
 
-Contributions Welcome! You can contribute by the following way:
+Contributions Welcome! You can contribute by the following way.
 
 - Write or fix documents
 - Write code of middleware
@@ -438,7 +475,11 @@ Contributions Welcome! You can contribute by the following way:
 - Refactor the code
 - etc.
 
-If you can, let's make Hono together!
+Let's make Hono together!
+
+## Contributors
+
+Thanks to [all contributors](https://github.com/yusukebe/hono/graphs/contributors)!
 
 ## Author
 

package/dist/compose.d.ts

@@ -1 +1 @@
-export declare const compose: <T>(middleware: Function[]) => (context: T, next?: Function) => Promise<void | object>;
+export declare const compose: <T>(middleware: Function[], onError?: Function) => (context: T, next?: Function) => Promise<void | object>;

package/dist/compose.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.compose = void 0;
+const context_1 = require("./context");
 // Based on the code in the MIT licensed `koa-compose` package.
-const compose = (middleware) => {
+const compose = (middleware, onError) => {
     const errors = [];
     return function (context, next) {
         let index = -1;
@@ -19,7 +20,12 @@ const compose = (middleware) => {
             try {
                 return Promise.resolve(fn(context, dispatch.bind(null, i + 1))).catch((e) => {
                     errors.push(e);
-                    throw errors[0]; // XXX
+                    if (onError && context instanceof context_1.Context) {
+                        context.res = onError(errors[0], context);
+                    }
+                    else {
+                        throw errors[0];
+                    }
                 });
             }
             catch (err) {

package/dist/context.d.ts

@@ -1,7 +1,5 @@
 /// <reference types="@cloudflare/workers-types" />
-declare type Headers = {
-    [key: string]: string;
-};
+declare type Headers = Record<string, string>;
 declare type Data = string | ArrayBuffer | ReadableStream;
 export interface Env {
 }
@@ -14,6 +12,7 @@ export declare class Context<RequestParamKeyType = string> {
     private _status;
     private _statusText;
     render: (template: string, params?: object, options?: object) => Promise<Response>;
+    notFound: () => Response;
     constructor(req: Request<RequestParamKeyType>, opts?: {
         res: Response;
         env: Env;

package/dist/hono.d.ts

@@ -1,8 +1,7 @@
 /// <reference types="@cloudflare/workers-types" />
-import type { Result } from './node';
-import { Node } from './node';
 import { Context } from './context';
 import type { Env } from './context';
+import type { Result, Router } from './router';
 declare global {
     interface Request<ParamKeyType = string> {
         param: (key: ParamKeyType) => string;
@@ -16,42 +15,32 @@ export declare type MiddlewareHandler = (c: Context, next: Function) => Promise<
 declare type ParamKeyName<NameWithPattern> = NameWithPattern extends `${infer Name}{${infer _Pattern}` ? Name : NameWithPattern;
 declare type ParamKey<Component> = Component extends `:${infer NameWithPattern}` ? ParamKeyName<NameWithPattern> : never;
 declare type ParamKeys<Path> = Path extends `${infer Component}/${infer Rest}` ? ParamKey<Component> | ParamKeys<Rest> : ParamKey<Path>;
-export declare class Router<T> {
-    node: Node<T>;
-    constructor();
-    add(method: string, path: string, handler: T): void;
-    match(method: string, path: string): Result<T> | null;
-}
 export declare class Hono {
-    router: Router<Handler[]>;
+    routerClass: {
+        new (): Router<any>;
+    };
+    strict: boolean;
+    router: Router<Handler>;
     middlewareRouters: Router<MiddlewareHandler>[];
     tempPath: string;
-    constructor();
-    get<Path extends string>(arg: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    get(arg: Handler<never>, ...args: Handler<never>[]): Hono;
-    post<Path extends string>(arg: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    post(arg: Handler, ...args: Handler[]): Hono;
-    put<Path extends string>(arg: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    put(arg: Handler, ...args: Handler[]): Hono;
-    head<Path extends string>(arg: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    head(arg: Handler, ...args: Handler[]): Hono;
-    delete<Path extends string>(arg: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    delete(arg: Handler, ...args: Handler[]): Hono;
-    options<Path extends string>(arg: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    options(arg: Handler, ...args: Handler[]): Hono;
-    patch<Path extends string>(arg: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    patch(arg: Handler, ...args: Handler[]): Hono;
-    all<Path extends string>(arg: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    all(arg: Handler<never>, ...args: Handler<never>[]): Hono;
+    constructor(init?: Partial<Pick<Hono, 'routerClass' | 'strict'>>);
+    get<Path extends string>(path: Path, handler: Handler<ParamKeys<Path>>): Hono;
+    post<Path extends string>(path: Path, handler: Handler<ParamKeys<Path>>): Hono;
+    put<Path extends string>(path: Path, handler: Handler<ParamKeys<Path>>): Hono;
+    head<Path extends string>(path: Path, handler: Handler<ParamKeys<Path>>): Hono;
+    delete<Path extends string>(path: Path, handler: Handler<ParamKeys<Path>>): Hono;
+    options<Path extends string>(path: Path, handler: Handler<ParamKeys<Path>>): Hono;
+    patch<Path extends string>(path: Path, handler: Handler<ParamKeys<Path>>): Hono;
+    all<Path extends string>(path: Path, handler: Handler<ParamKeys<Path>>): Hono;
     route(path: string): Hono;
     use(path: string, middleware: MiddlewareHandler): void;
-    addRoute(method: string, arg: string | Handler, ...args: Handler[]): Hono;
-    matchRoute(method: string, path: string): Promise<Result<Handler[]>>;
+    addRoute(method: string, path: string, handler: Handler): Hono;
+    matchRoute(method: string, path: string): Promise<Result<Handler>>;
     dispatch(request: Request, env?: Env, event?: FetchEvent): Promise<Response>;
     handleEvent(event: FetchEvent): Promise<Response>;
     fetch(request: Request, env?: Env, event?: FetchEvent): Promise<Response>;
     fire(): void;
-    onError(err: Error): Response;
-    notFound(): Response;
+    onError(err: Error, c: Context): Response;
+    notFound(c: Context): Response;
 }
 export {};