hono 1.0.0 → 1.2.0

package/README.md

@@ -1,28 +1,22 @@
 <div align="center">
-  <a href="https://github.com/yusukebe/hono">
-    <img src="https://raw.githubusercontent.com/yusukebe/hono/master/docs/images/hono-title.png" width="500" height="auto" alt="Hono"/>
+  <a href="https://github.com/honojs/hono">
+    <img src="https://raw.githubusercontent.com/honojs/hono/master/docs/images/hono-title.png" width="500" height="auto" alt="Hono"/>
   </a>
 </div>
 
 <hr />
 
-<p>
-<a href="https://github.com/yusukebe/hono/blob/master/README.md">English</a>
-&#x000B7;
-<a href="https://github.com/yusukebe/hono/blob/master/docs/README.ja.md">日本語</a>
-</p>
-
-[![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)
+[![GitHub Workflow Status](https://img.shields.io/github/workflow/status/honojs/hono/ci)](https://github.com/honojs/hono/actions)
+[![GitHub](https://img.shields.io/github/license/honojs/hono)](https://github.com/honojs/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)
+[![GitHub commit activity](https://img.shields.io/github/commit-activity/m/honojs/hono)](https://github.com/honojs/hono/pulse)
+[![GitHub last commit](https://img.shields.io/github/last-commit/honojs/hono)](https://github.com/honojs/hono/commits/master)
 
-Hono - _**[炎] means flame🔥 in Japanese**_ - is small, simple, and ultrafast web framework for Cloudflare Workers and Fastly Compute@Edge.
+Hono - _**[炎] means flame🔥 in Japanese**_ - is a small, simple, and ultrafast web framework for Cloudflare Workers or Service Worker based serverless such as Fastly Compute@Edge.
 
-```js
+```ts
 import { Hono } from 'hono'
 const app = new Hono()
 
@@ -34,7 +28,7 @@ app.fire()
 ## Features
 
 - **Ultrafast** - the router does not use linear loops.
-- **Zero-dependencies** - using only Service Worker and Web standard API.
+- **Zero-dependencies** - using only Service Worker and Web Standard API.
 - **Middleware** - built-in middleware and ability to extend with your own middleware.
 - **TypeScript** - first-class TypeScript support.
 - **Optimized** - for Cloudflare Workers.
@@ -44,33 +38,97 @@ app.fire()
 **Hono is fastest**, compared to other routers for Cloudflare Workers.
 
 ```plain
-hono x 809,503 ops/sec ±6.94% (73 runs sampled)
-itty-router x 157,310 ops/sec ±4.31% (87 runs sampled)
-sunder x 328,350 ops/sec ±2.30% (95 runs sampled)
-worktop x 209,758 ops/sec ±4.28% (83 runs sampled)
-Fastest is hono
-✨  Done in 60.66s.
+hono - trie-router(default) x 737,602 ops/sec ±3.65% (67 runs sampled)
+hono - regexp-router x 1,188,203 ops/sec ±6.42% (60 runs sampled)
+itty-router x 163,970 ops/sec ±3.05% (91 runs sampled)
+sunder x 344,468 ops/sec ±0.87% (97 runs sampled)
+worktop x 222,044 ops/sec ±2.13% (85 runs sampled)
+Fastest is hono - regexp-router
+✨  Done in 84.04s.
 ```
 
+## Why so fast?
+
+Routers used in Hono are really smart.
+
+- **TrieRouter**(default) - Implemented with Trie tree structure.
+- **RegExpRouter** - Match routes with one big Regex made before dispatching at once.
+
 ## Hono in 1 minute
 
 A demonstration to create an application for 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.
+## Not only fast
 
-![Demo](https://user-images.githubusercontent.com/10682/154179671-9e491597-6778-44ac-a8e6-4483d7ad5393.png)
+Hono is fast. But not only fast.
 
-## Install
+### Write Less, do more
 
-You can install Hono from the npm registry.
+Built-in middleware make _"**Write Less, do more**"_ in reality. You can use a lot of middleware without writing code from scratch. Below are examples.
 
-```sh
-yarn add hono
+- [Basic Authentication](https://github.com/honojs/hono/tree/master/src/middleware/basic-auth/)
+- [Cookie parsing / serializing](https://github.com/honojs/hono/tree/master/src/middleware/cookie/)
+- [CORS](https://github.com/honojs/hono/tree/master/src/middleware/cors/)
+- [ETag](https://github.com/honojs/hono/tree/master/src/middleware/etag/)
+- [GraphQL Server](https://github.com/honojs/hono/tree/master/src/middleware/graphql-server/)
+- [JWT Authentication](https://github.com/honojs/hono/tree/master/src/middleware/jwt/)
+- [Logger](https://github.com/honojs/hono/tree/master/src/middleware/logger/)
+- [Mustache template engine](https://github.com/honojs/hono/tree/master/src/middleware/mustache/) (Only for Cloudflare Workers)
+- [JSON pretty printing](https://github.com/honojs/hono/tree/master/src/middleware/pretty-json/)
+- [Serving static files](https://github.com/honojs/hono/tree/master/src/middleware/serve-static/) (Only for Cloudflare Workers)
+
+To enable logger and Etag middleware with just this code.
+
+```ts
+import { Hono } from 'hono'
+import { etag } from 'hono/etag'
+import { logger } from 'hono/logger'
+
+const app = new Hono()
+app.use('*', etag(), (logger())
 ```
 
-or
+And, the routing of Hono is so flexible. It's easy to construct large web applications.
+
+```ts
+import { Hono, Route } from 'hono'
+import { cors } from 'hono/cors'
+
+const app = new Hono()
+
+const v1 = new Route()
+v1.get('/posts', (c) => {
+  return c.text('list pots')
+})
+  .post('/posts', cors(), (c) => {
+    return c.text('created!', 201)
+  })
+  .get('/posts/:id', (c) => {
+    const id = c.req.param('id')
+    return c.text(`your id is ${id}`)
+  })
+
+app.route('/v1', v1)
+```
+
+### Web Standard
+
+Request and Response object used in Hono are extensions of the Web Standard [Fetch API](https://developer.mozilla.org/ja/docs/Web/API/Fetch_API). If you are familiar with that, you don't need to know more than that.
+
+### Developer Experience
+
+Hono provides fine _"**Developer Experience**"_. Easy access to Request/Response thanks to the `Context` object.
+Above all, Hono is written in TypeScript. So, Hono has _"**Types**"_!
+
+For example, the named path parameters will be literal types.
+
+![Demo](https://user-images.githubusercontent.com/10682/154179671-9e491597-6778-44ac-a8e6-4483d7ad5393.png)
+
+## Install
+
+You can install Hono from the npm registry.
 
 ```sh
 npm install hono
@@ -80,21 +138,21 @@ npm install hono
 
 An instance of `Hono` has these methods.
 
-- app.**HTTP_METHOD**(path, handler)
-- app.**all**(path, handler)
-- app.**route**(path)
-- app.**use**(path, middleware)
+- app.**HTTP_METHOD**(\[path,\] handler|middleware...)
+- app.**all**(\[path,\] handler|middleware...)
+- app.**route**(path, \[Route\])
+- app.**use**(\[path,\] middleware)
 - app.**notFound**(handler)
 - app.**onError**(err, handler)
 - app.**fire**()
 - app.**fetch**(request, env, event)
-- app.**request**(path, option)
+- app.**request**(path, options)
 
 ## Routing
 
 ### Basic
 
-```js
+```ts
 // HTTP Methods
 app.get('/', (c) => c.text('GET /'))
 app.post('/', (c) => c.text('POST /'))
@@ -110,7 +168,7 @@ app.all('/hello', (c) => c.text('Any Method /hello'))
 
 ### Named Parameter
 
-```js
+```ts
 app.get('/user/:name', (c) => {
   const name = c.req.param('name')
   ...
@@ -119,7 +177,7 @@ app.get('/user/:name', (c) => {
 
 ### Regexp
 
-```js
+```ts
 app.get('/post/:date{[0-9]+}/:title{[a-z]+}', (c) => {
   const date = c.req.param('date')
   const title = c.req.param('title')
@@ -127,24 +185,26 @@ app.get('/post/:date{[0-9]+}/:title{[a-z]+}', (c) => {
 })
 ```
 
-### Nested route
+### Chained route
 
-```js
-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
+```ts
+app
+  .get('/endpoint', (c) => {
+    return c.text('GET /endpoint')
+  })
+  .post((c) => {
+    return c.text('POST /endpoint')
+  })
+  .delete((c) => {
+    return c.text('DELETE /endpoint')
+  })
 ```
 
 ### no strict
 
 If `strict` is set false, `/hello`and`/hello/` are treated the same.
 
-```js
+```ts
 const app = new Hono({ strict: false }) // Default is true
 
 app.get('/hello', (c) => c.text('/hello or /hello/'))
@@ -159,13 +219,38 @@ app.get('/fetch-url', async (c) => {
 })
 ```
 
+## Route
+
+`Route` object enables Nested route.
+
+```ts
+const book = new Route()
+
+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
+
+app.route('/book', book)
+```
+
 ## Middleware
 
+Middleware operate after/before executing Handler. We can get `Response` before dispatching or manipulate `Response` after dispatching.
+
+### Definition of Middleware
+
+- Handler - should return `Response` object.
+- Middleware - should return nothing, do `await next()`
+
 ### Built-in Middleware
 
 Hono has built-in middleware.
 
-```js
+```ts
 import { Hono } from 'hono'
 import { poweredBy } from 'hono/powered-by'
 import { logger } from 'hono/logger'
@@ -175,6 +260,7 @@ const app = new Hono()
 
 app.use('*', poweredBy())
 app.use('*', logger())
+
 app.use(
   '/auth/*',
   basicAuth({
@@ -184,13 +270,13 @@ app.use(
 )
 ```
 
-Available built-in middleware is listed on [src/middleware](https://github.com/yusukebe/hono/tree/master/src/middleware).
+Available built-in middleware is listed on [src/middleware](https://github.com/honojs/hono/tree/master/src/middleware).
 
 ### Custom Middleware
 
 You can write your own middleware.
 
-```js
+```ts
 // Custom logger
 app.use('*', async (c, next) => {
   console.log(`[${c.req.method}] ${c.req.url}`)
@@ -229,11 +315,11 @@ app.onError((err, c) => {
 
 ## Context
 
-To handle Request and Reponse, you can use `Context` object.
+To handle Request and Response, you can use `Context` object.
 
 ### c.req
 
-```js
+```ts
 // Get Request object
 app.get('/hello', (c) => {
   const userAgent = c.req.headers.get('User-Agent')
@@ -261,13 +347,15 @@ app.get('/entry/:id', (c) => {
 
 ### Shortcuts for Response
 
-```js
+```ts
 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')
 })
@@ -275,14 +363,13 @@ app.get('/welcome', (c) => {
 
 The Response is the same as below.
 
-```js
+```ts
 new Response('Thank you for comming', {
   status: 201,
   statusText: 'Created',
   headers: {
     'X-Message': 'Hello',
     'Content-Type': 'text/plain',
-    'Content-Length': '22',
   },
 })
 ```
@@ -291,7 +378,7 @@ new Response('Thank you for comming', {
 
 Render text as `Content-Type:text/plain`.
 
-```js
+```ts
 app.get('/say', (c) => {
   return c.text('Hello!')
 })
@@ -301,7 +388,7 @@ app.get('/say', (c) => {
 
 Render JSON as `Content-Type:application/json`.
 
-```js
+```ts
 app.get('/api', (c) => {
   return c.json({ message: 'Hello!' })
 })
@@ -311,7 +398,7 @@ app.get('/api', (c) => {
 
 Render HTML as `Content-Type:text/html`.
 
-```js
+```ts
 app.get('/', (c) => {
   return c.html('<h1>Hello! Hono!</h1>')
 })
@@ -321,7 +408,7 @@ app.get('/', (c) => {
 
 Return the `Not Found` Response.
 
-```js
+```ts
 app.get('/notfound', (c) => {
   return c.notFound()
 })
@@ -331,14 +418,14 @@ app.get('/notfound', (c) => {
 
 Redirect, default status code is `302`.
 
-```js
+```ts
 app.get('/redirect', (c) => c.redirect('/'))
 app.get('/redirect-permanently', (c) => c.redirect('/', 301))
 ```
 
 ### c.res
 
-```js
+```ts
 // Response object
 app.use('/', (c, next) => {
   next()
@@ -348,7 +435,7 @@ app.use('/', (c, next) => {
 
 ### c.event
 
-```js
+```ts
 // FetchEvent object
 app.use('*', async (c, next) => {
   c.event.waitUntil(
@@ -360,7 +447,7 @@ app.use('*', async (c, next) => {
 
 ### c.env
 
-```js
+```ts
 // Environment object for Cloudflare Workers
 app.get('*', async c => {
   const counter = c.env.COUNTER
@@ -372,7 +459,7 @@ app.get('*', async c => {
 
 `app.fire()` do this.
 
-```js
+```ts
 addEventListener('fetch', (event) => {
   event.respondWith(this.handleEvent(event))
 })
@@ -382,17 +469,18 @@ addEventListener('fetch', (event) => {
 
 `app.fetch` for Cloudflare Module Worker syntax.
 
-```js
+```ts
 export default {
   fetch(request: Request, env: Env, event: FetchEvent) {
     return app.fetch(request, env, event)
   },
 }
+```
 
-/*
 or just do:
+
+```ts
 export default app
-*/
 ```
 
 ## request
@@ -408,61 +496,35 @@ test('GET /hello is ok', async () => {
 
 ## Cloudflare Workers with Hono
 
-Using [Wrangler](https://developers.cloudflare.com/workers/cli-wrangler/) or [Miniflare](https://miniflare.dev), you can develop the application locally and publish it with few commands.
+Using [Wrangler](https://developers.cloudflare.com/workers/cli-wrangler/), you can develop the application locally and publish it with few commands.
 
 Let's write your first code for Cloudflare Workers with Hono.
 
----
-
-### Caution
-
-**Wrangler 1.x** does not support importing middleware. We recommend two ways:
-
-1. Use [Wragler 2.0 Beta](https://github.com/cloudflare/wrangler2).
-2. Build without webpack 4.x. For example, you can use esbuild. See [the starter template](https://github.com/yusukebe/hono-minimal).
-
----
-
-### 1. `npm init`
-
-Make a npm skeleton directory.
-
-```sh
-mkdir hono-example
-cd hono-example
-npm init -y
-```
-
-### 2. `wrangler init`
+### 1. `wrangler init`
 
 Initialize as a wrangler project.
 
-```sh
-npx wrangler@beta init
 ```
-
-Answer the questions. If you want, you can answer `y`.
-
-```
-Would you like to install wrangler into your package.json? (y/n) <--- n
-Would you like to use TypeScript? (y/n) <--- n
-Would you like to create a Worker at src/index.js? (y/n) <--- n
+mkdir hono-example
+cd hono-example
+npx wrangler init -y
 ```
 
-### 3. `npm install hono`
+### 2. `npm install hono`
 
 Install `hono` from the npm registry.
 
-```sh
+```
+npm init -y
 npm i hono
 ```
 
-### 4. Write your app
+### 3. Write your app
 
-Only 4 lines!!
+Edit `src/index.ts`. Only 4 lines!!
 
-```js
-// index.js
+```ts
+// src/index.ts
 import { Hono } from 'hono'
 const app = new Hono()
 
@@ -471,47 +533,51 @@ app.get('/', (c) => c.text('Hello! Hono!'))
 app.fire()
 ```
 
-### 5. Run
+### 4. Run
 
 Run the development server locally. Then, access `http://127.0.0.1:8787/` in your Web browser.
 
-```sh
-npx wrangler@beta dev index.js
+```
+npx wrangler dev
 ```
 
-### 6. Publish
+### 5. Publish
 
 Deploy to Cloudflare. That's all!
 
-```sh
-npx wrangler@beta publish index.js
+```
+npx wrangler publish index.ts
 ```
 
 ## Starter template
 
-You can start making your Cloudflare Workers application with [the starter template](https://github.com/yusukebe/hono-minimal). It is really minimal using TypeScript, esbuild, and Miniflare.
+You can start making your Cloudflare Workers application with [the starter template](https://github.com/honojs/hono-minimal). It is really minimal using TypeScript, esbuild, Miniflare, and Jest.
 
 To generate a project skelton, run this command.
 
-```sh
-wrangler generate my-app https://github.com/yusukebe/hono-minimal
+```
+npx create-cloudflare my-app https://github.com/honojs/hono-minimal
 ```
 
+## Examples
+
+- Hono Examples - <https://github.com/honojs/examples>
+
 ## Related projects
 
 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>
-- itty-router <https://github.com/kwhitley/itty-router>
-- 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>
+- express - <https://github.com/expressjs/express>
+- koa - <https://github.com/koajs/koa>
+- itty-router - <https://github.com/kwhitley/itty-router>
+- 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 in the following ways.
 
 - Write or fix documents
 - Write code of middleware
@@ -519,11 +585,9 @@ Contributions Welcome! You can contribute by the following way.
 - Refactor the code
 - etc.
 
-Let's make Hono together!
-
 ## Contributors
 
-Thanks to [all contributors](https://github.com/yusukebe/hono/graphs/contributors)!
+Thanks to [all contributors](https://github.com/honojs/hono/graphs/contributors)! Especially, [@metrue](https://github.com/metrue) and [@usualoma](https://github.com/usualoma)!
 
 ## Author
 

package/dist/compose.d.ts

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

package/dist/compose.js

@@ -3,26 +3,38 @@ 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, onError) => {
-    return function (context) {
+const compose = (middleware, onError, onNotFound) => {
+    return async (context, next) => {
         let index = -1;
         return dispatch(0);
         async function dispatch(i) {
-            if (i === middleware.length) {
-                return context;
-            }
             if (i <= index) {
                 return Promise.reject(new Error('next() called multiple times'));
             }
-            const handler = middleware[i];
+            let handler = middleware[i];
             index = i;
+            if (i === middleware.length)
+                handler = next;
+            if (handler === undefined) {
+                if (context instanceof context_1.Context && context.res === undefined) {
+                    context.res = onNotFound(context);
+                }
+                return Promise.resolve(context);
+            }
             return Promise.resolve(handler(context, dispatch.bind(null, i + 1)))
-                .then(() => {
+                .then(async (res) => {
+                // If handler return Response like `return c.text('foo')`
+                if (res && context instanceof context_1.Context) {
+                    context.res = res;
+                    dispatch(i + 1); // <--- Call next()
+                }
                 return context;
             })
                 .catch((err) => {
                 if (onError && context instanceof context_1.Context) {
-                    context.res = onError(err, context);
+                    if (err instanceof Error) {
+                        context.res = onError(err, context);
+                    }
                     return context;
                 }
                 else {

package/dist/context.d.ts

@@ -2,12 +2,11 @@
 import type { StatusCode } from './utils/http-status';
 declare type Headers = Record<string, string>;
 declare type Data = string | ArrayBuffer | ReadableStream;
-export interface Env {
-}
-export declare class Context<RequestParamKeyType = string> {
+export declare type Env = Record<string, any>;
+export declare class Context<RequestParamKeyType = string, E = Env> {
     req: Request<RequestParamKeyType>;
     res: Response;
-    env: Env;
+    env: E;
     event: FetchEvent;
     private _headers;
     private _status;
@@ -18,7 +17,7 @@ export declare class Context<RequestParamKeyType = string> {
     notFound: () => Response | Promise<Response>;
     constructor(req: Request<RequestParamKeyType>, opts?: {
         res: Response;
-        env: Env;
+        env: E;
         event: FetchEvent;
     });
     private initRequest;