hono 0.4.0 → 0.5.0

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,17 +31,17 @@ 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)
 
@@ -43,26 +51,28 @@ Now, the named path parameter has types.
 
 ## Install
 
-You can install Hono 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
 
-An instance of `Hono` has these methods:
+An instance of `Hono` has these methods.
 
 - app.**HTTP_METHOD**(path, handler)
 - app.**all**(path, handler)
 - app.**route**(path)
 - app.**use**(path, middleware)
+- app.**notFound**(handler)
+- app.**onError**(err, handler)
 - app.**fire**()
 - app.**fetch**(request, env, event)
 
@@ -70,8 +80,6 @@ An instance of `Hono` has these methods:
 
 ### Basic
 
-`app.HTTP_METHOD`
-
 ```js
 // HTTP Methods
 app.get('/', (c) => c.text('GET /'))
@@ -81,11 +89,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'))
 ```
@@ -106,44 +110,33 @@ app.get('/post/:date{[0-9]+}/:title{[a-z]+}', (c) => {
   const date = c.req.param('date')
   const title = c.req.param('title')
   ...
+})
 ```
 
 ### Nested route
 
 ```js
 const book = app.route('/book')
-book.get('/', (c) => c.text('List Books')) // => GET /book
+book.get('/', (c) => c.text('List Books')) // GET /book
 book.get('/:id', (c) => {
-  // => GET /book/:id
+  // 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
-
-You can customize 404 Not Found response:
-
-```js
-app.get('*', (c) => {
-  return c.text('Custom 404 Error', 404)
-})
+book.post('/', (c) => c.text('Create Book')) // POST /book
 ```
 
 ### no strict
 
-If `strict` is set `false`, `/hello`and`/hello/` are treated the same:
+If `strict` is set false, `/hello`and`/hello/` are treated the same.
 
 ```js
-const app = new Hono({ strict: false })
+const app = new Hono({ strict: false }) // Default is true
 
 app.get('/hello', (c) => c.text('/hello or /hello/'))
 ```
 
-Default is `true`.
-
-## async/await
+### async/await
 
 ```js
 app.get('/fetch-url', async (c) => {
@@ -166,14 +159,20 @@ const app = new Hono()
 
 app.use('*', poweredBy())
 app.use('*', logger())
-app.use('/auth/*', basicAuth({ username: 'hono', password: 'acoolproject' }))
+app.use(
+  '/auth/*',
+  basicAuth({
+    username: 'hono',
+    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
@@ -191,22 +190,32 @@ app.use('/message/*', async (c, next) => {
 app.get('/message/hello', (c) => c.text('Hello Middleware!'))
 ```
 
-### Handling Error
+## Error
+
+### Not Found
+
+`app.notFound` for customizing Not Found Response.
 
 ```js
-app.use('*', async (c, next) => {
-  try {
-    await next()
-  } catch (err) {
-    console.error(`${err}`)
-    c.res = c.text('Custom Error Message', { status: 500 })
-  }
+app.notFound((c) => {
+  return c.text('Custom 404 Message', 404)
+})
+```
+
+### Error Handling
+
+`app.onError` handle the error and return the customized Response.
+
+```js
+app.onError((err, c) => {
+  console.error(`${err}`)
+  return c.text('Custom Error Message', 500)
 })
 ```
 
 ## Context
 
-To handle Request and Reponse, you can use Context object:
+To handle Request and Reponse, you can use Context object.
 
 ### c.req
 
@@ -240,30 +249,33 @@ app.get('/entry/:id', (c) => {
 
 ```js
 app.get('/welcome', (c) => {
+  // Set headers
   c.header('X-Message', 'Hello!')
   c.header('Content-Type', 'text/plain')
+  // Set HTTP status code
   c.status(201)
-
+  // Return the response body
   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) => {
@@ -273,7 +285,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) => {
@@ -283,7 +295,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) => {
@@ -291,9 +303,19 @@ app.get('/', (c) => {
 })
 ```
 
+### c.notFound()
+
+Return the `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('/'))
@@ -334,7 +356,7 @@ app.get('*', async c => {
 
 ## fire
 
-`app.fire()` do:
+`app.fire()` do this.
 
 ```js
 addEventListener('fetch', (event) => {
@@ -344,7 +366,7 @@ addEventListener('fetch', (event) => {
 
 ## fetch
 
-`app.fetch()` is for Cloudflare Module Worker syntax.
+`app.fetch` for Cloudflare Module Worker syntax.
 
 ```js
 export default {
@@ -354,7 +376,7 @@ export default {
 }
 
 /*
-or just do this:
+or just do:
 export default app
 */
 ```
@@ -367,15 +389,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
@@ -388,15 +410,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
@@ -414,10 +436,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
@@ -425,12 +447,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>
@@ -438,10 +470,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
@@ -449,7 +482,7 @@ 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
 

package/dist/compose.d.ts

@@ -1 +1,2 @@
-export declare const compose: <T>(middleware: Function[]) => (context: T, next?: Function) => Promise<void | object>;
+import type { ErrorHandler } from './hono';
+export declare const compose: <T>(middleware: Function[], onError?: ErrorHandler) => (context: T, next?: Function) => Promise<T>;

package/dist/compose.js

@@ -1,9 +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 errors = [];
+const compose = (middleware, onError) => {
     return function (context, next) {
         let index = -1;
         return dispatch(0);
@@ -15,11 +15,20 @@ const compose = (middleware) => {
             if (i === middleware.length)
                 fn = next;
             if (!fn)
-                return Promise.resolve();
+                return context;
             try {
-                return Promise.resolve(fn(context, dispatch.bind(null, i + 1))).catch((e) => {
-                    errors.push(e);
-                    throw errors[0]; // XXX
+                return Promise.resolve(fn(context, dispatch.bind(null, i + 1)))
+                    .then(() => {
+                    return context;
+                })
+                    .catch((err) => {
+                    if (onError && context instanceof context_1.Context) {
+                        context.res = onError(err, context);
+                        return context;
+                    }
+                    else {
+                        throw err;
+                    }
                 });
             }
             catch (err) {

package/dist/context.d.ts

@@ -12,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;
@@ -13,41 +12,39 @@ declare global {
 }
 export declare type Handler<RequestParamKeyType = string> = (c: Context<RequestParamKeyType>, next?: Function) => Response | Promise<Response>;
 export declare type MiddlewareHandler = (c: Context, next: Function) => Promise<void>;
+export declare type NotFoundHandler = (c: Context) => Response;
+export declare type ErrorHandler = (err: Error, c: Context) => Response;
 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;
-}
-declare type Init = {
-    strict?: boolean;
-};
 export declare class Hono {
-    router: Router<Handler[]>;
+    routerClass: {
+        new (): Router<any>;
+    };
+    strict: boolean;
+    router: Router<Handler>;
     middlewareRouters: Router<MiddlewareHandler>[];
     tempPath: string;
-    strict: boolean;
-    constructor(init?: Init);
-    get<Path extends string>(path: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    post<Path extends string>(path: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    put<Path extends string>(path: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    head<Path extends string>(path: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    delete<Path extends string>(path: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    options<Path extends string>(path: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    patch<Path extends string>(path: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
-    all<Path extends string>(path: Path, ...args: Handler<ParamKeys<Path>>[]): Hono;
+    constructor(init?: Partial<Pick<Hono, 'routerClass' | 'strict'>>);
+    notFoundHandler: NotFoundHandler;
+    errorHandler: ErrorHandler;
+    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, path: string, ...args: Handler[]): Hono;
-    matchRoute(method: string, path: string): Promise<Result<Handler[]>>;
+    onError(handler: ErrorHandler): Hono;
+    notFound(handler: NotFoundHandler): Hono;
+    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;
 }
 export {};