hono 0.0.9 → 0.0.13

package/README.md

@@ -1,52 +1,66 @@
 # Hono
 
-Hono [炎] - Tiny web framework for Cloudflare Workers and others.
+Hono[炎] - _**means flame🔥 in Japanese**_ - is small, simple, and ultrafast web flamework for a Service Workers API based serverless such as Cloudflare Workers and Fastly Compute@Edge.
 
 ```js
-const { Hono } = require('hono')
+import { Hono } from 'hono'
 const app = new Hono()
 
-app.get('/', () => new Response('Hono!!'))
+app.get('/', (c) => c.text('Hono!!'))
 
 app.fire()
 ```
 
-## Feature
+## Features
 
-- Fast - the router is implemented with Trie-Tree structure.
-- Tiny - use only standard API.
-- Portable - zero dependencies.
-- Flexible - you can make your own middlewares.
-- Optimized - for Cloudflare Workers and Fastly Compute@Edge.
+- **Ultra Fast** - the router is implemented with Trie-Tree structure.
+- **Zero dependencies** - using only Web standard API.
+- **Middleware** - builtin middleware, and you can make your own middleware.
+- **Optimized** - for Cloudflare Workers.
 
 ## Benchmark
 
-```
-hono x 813,001 ops/sec ±2.96% (75 runs sampled)
-itty-router x 160,415 ops/sec ±3.31% (85 runs sampled)
-sunder x 307,438 ops/sec ±4.77% (73 runs sampled)
+**Hono is fastest** compared to other routers for Cloudflare Workers.
+
+```plain
+hono x 748,188 ops/sec ±5.40% (77 runs sampled)
+itty-router x 158,817 ops/sec ±3.62% (87 runs sampled)
+sunder x 332,339 ops/sec ±1.11% (95 runs sampled)
+worktop x 205,906 ops/sec ±4.43% (83 runs sampled)
 Fastest is hono
-✨  Done in 37.03s.
+✨  Done in 52.79s.
 ```
 
+## Hono in 1 minute
+
+Below is a demonstration to create an application of Cloudflare Workers with Hono.
+
+![Demo](https://user-images.githubusercontent.com/10682/148223268-2484a891-57c1-472f-9df3-936a5586f002.gif)
+
 ## Install
 
-```
-$ yarn add hono
+You can install from npm registry:
+
+```sh
+yarn add hono
 ```
 
 or
 
 ```sh
-$ npm install hono
+npm install hono
 ```
 
 ## Methods
 
-- app.**HTTP_METHOD**(path, callback)
-- app.**all**(path, callback)
+Instance of `Hono` has these methods:
+
+- app.**HTTP_METHOD**(path, handler)
+- app.**all**(path, handler)
 - app.**route**(path)
 - app.**use**(path, middleware)
+- app.**fire**()
+- app.**fetch**(request, env, event)
 
 ## Routing
 
@@ -100,99 +114,302 @@ app
     .put(() => {...})
 ```
 
+## async/await
+
+```js
+app.get('/fetch-url', async () => {
+  const response = await fetch('https://example.com/')
+  return new Response(`Status is ${response.status}`)
+})
+```
+
 ## Middleware
 
 ### Builtin Middleware
 
 ```js
-const { Hono, Middleware } = require('hono')
+import { Hono, Middleware } from 'hono'
 
 ...
 
-app.use('*', Middleware.poweredBy)
-
+app.use('*', Middleware.poweredBy())
+app.use('*', Middleware.logger())
+app.use(
+  '/auth/*',
+  Middleware.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:
+
 ```js
-const logger = (c, next) => {
+// Custom logger
+app.use('*', async (c, next) => {
   console.log(`[${c.req.method}] ${c.req.url}`)
-  next()
-}
-
-const addHeader = (c, next) => {
-  next()
-  c.res.headers.add('x-message', 'This is middleware!')
-}
+  await next()
+})
 
-app.use('*', logger)
-app.use('/message/*', addHeader)
+// Add a custom header
+app.use('/message/*', async (c, next) => {
+  await next()
+  await c.res.headers.add('x-message', 'This is middleware!')
+})
 
 app.get('/message/hello', () => 'Hello Middleware!')
 ```
 
 ### Custom 404 Response
 
+You can customize 404 Not Found response:
+
 ```js
-const customNotFound = (c, next) => {
-  next()
+app.use('*', async (c, next) => {
+  await next()
   if (c.res.status === 404) {
     c.res = new Response('Custom 404 Not Found', { status: 404 })
   }
-}
+})
+```
+
+### Complex Pattern
+
+You can also do this:
+
+```js
+// Output response time
+app.use('*', async (c, next) => {
+  await next()
+  const responseTime = await c.res.headers.get('X-Response-Time')
+  console.log(`X-Response-Time: ${responseTime}`)
+})
 
-app.use('*', customNotFound)
+// Add X-Response-Time header
+app.use('*', async (c, next) => {
+  const start = Date.now()
+  await next()
+  const ms = Date.now() - start
+  await c.res.headers.append('X-Response-Time', `${ms}ms`)
+})
 ```
 
 ## Context
 
-### req
+To handle Request and Reponse easily, you can use Context object:
+
+### c.req
 
 ```js
+
+// Get Request object
 app.get('/hello', (c) => {
-  const userAgent = c.req.headers('User-Agent')
+  const userAgent = c.req.headers.get('User-Agent')
+  ...
+})
+
+// Query params
+app.get('/search', (c) => {
+  const query = c.req.query('q')
+  ...
+})
+
+// Captured params
+app.get('/entry/:id', (c) => {
+  const id = c.req.params('id')
   ...
 })
 ```
 
-### res
+### c.res
 
 ```js
+// Response object
 app.use('/', (c, next) => {
   next()
   c.res.headers.append('X-Debug', 'Debug message')
 })
 ```
 
-## Request
+### c.event
+
+```js
+// FetchEvent objest
+app.use('*', async (c, next) => {
+  c.event.waitUntil(
+    ...
+  )
+  await next()
+})
+```
 
-### query
+### c.env
 
 ```js
-app.get('/search', (c) => {
-  const query = c.req.query('q')
+// Environment object for Cloudflare Workers
+app.get('*', async c => {
+  const counter = c.env.COUNTER
   ...
 })
 ```
 
-### params
+### c.text()
+
+Render text as `Content-Type:text/plain`:
 
 ```js
-app.get('/entry/:id', (c) => {
-  const id = c.req.params('id')
-  ...
+app.get('/say', (c) => {
+  return c.text('Hello!')
 })
 ```
 
+### c.json()
+
+Render JSON as `Content-Type:application/json`:
+
+```js
+app.get('/api', (c) => {
+  return c.json({ message: 'Hello!' })
+})
+```
+
+### c.html()
+
+Render HTML as `Content-Type:text/html`:
+
+```js
+app.get('/', (c) => {
+  return c.html('<h1>Hello! Hono!</h1>')
+})
+```
+
+### c.redirect()
+
+Redirect, default status code is `302`:
+
+```js
+app.get('/redirect', (c) => c.redirect('/'))
+app.get('/redirect-permanently', (c) => c.redirect('/', 301))
+```
+
+## fire
+
+`app.fire()` do:
+
+```js
+addEventListener('fetch', (event) => {
+  event.respondWith(this.handleEvent(event))
+})
+```
+
+## fetch
+
+`app.fetch()` is for Cloudflare Module Worker syntax.
+
+```js
+export default {
+  fetch(request: Request, env: Env, event: FetchEvent) {
+    return app.fetch(request, env, event)
+  },
+}
+```
+
+## Cloudflare Workers with Hono
+
+Using `wrangler` or `miniflare`, you can develop the application locally and publish it with few commands.
+
+Let's write your first code for Cloudflare Workers with Hono.
+
+### 1. Install Wrangler
+
+Install Cloudflare Command Line "[Wrangler](https://github.com/cloudflare/wrangler)"
+
+```sh
+npm i @cloudflare/wrangler -g
+```
+
+### 2. `npm init`
+
+Make npm skeleton directory.
+
+```sh
+mkdir hono-example
+ch hono-example
+npm init -y
+```
+
+### 3. `wrangler init`
+
+Init as a wrangler project.
+
+```sh
+wrangler init
+```
+
+### 4. `npm install hono`
+
+Install `hono` from npm registry.
+
+```sh
+npm i hono
+```
+
+### 5. Write your app
+
+Only 4 lines!!
+
+```js
+import { Hono } from 'hono'
+const app = new Hono()
+
+app.get('/', (c) => c.text('Hello! Hono!'))
+
+app.fire()
+```
+
+### 6. Run
+
+Run the development server locally. Then, access like `http://127.0.0.1:8787/` in your Web browser.
+
+```sh
+wrangler dev
+```
+
+### Publish
+
+Deploy to Cloudflare. That's all!
+
+```sh
+wrangler publish
+```
+
 ## Related projects
 
-- koa <https://github.com/koajs/koa>
+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.
+
 - express <https://github.com/expressjs/express>
-- oak <https://github.com/oakserver/oak>
+- 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>
+
+## Contributing
+
+Contributions Welcome! You can contribute by the following way:
+
+- Write or fix documents
+- Write code of middleware
+- Fix bugs
+- Refactor the code
+- etc.
+
+If you can, let's make Hono together!
 
 ## Author
 
@@ -200,4 +417,4 @@ Yusuke Wada <https://github.com/yusukebe>
 
 ## License
 
-MIT
+Distributed under the MIT License. See [LICENSE](LICENSE) for more information.

package/dist/compose.d.ts

@@ -0,0 +1 @@
+export declare const compose: (middleware: any) => (context: any, next?: Function) => any;

package/dist/compose.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compose = void 0;
+// Based on the code in the MIT licensed `koa-compose` package.
+const compose = (middleware) => {
+    return function (context, next) {
+        let index = -1;
+        return dispatch(0);
+        function dispatch(i) {
+            if (i <= index)
+                return Promise.reject(new Error('next() called multiple times'));
+            index = i;
+            let fn = middleware[i];
+            if (i === middleware.length)
+                fn = next;
+            if (!fn)
+                return Promise.resolve();
+            try {
+                return Promise.resolve(fn(context, dispatch.bind(null, i + 1)));
+            }
+            catch (err) {
+                return Promise.reject(err);
+            }
+        }
+    };
+};
+exports.compose = compose;

package/dist/context.d.ts

@@ -0,0 +1,23 @@
+/// <reference types="@cloudflare/workers-types" />
+declare type Headers = {
+    [key: string]: string;
+};
+export interface Env {
+}
+export declare class Context {
+    req: Request;
+    res: Response;
+    env: Env;
+    event: FetchEvent;
+    constructor(req: Request, opts?: {
+        res: Response;
+        env: Env;
+        event: FetchEvent;
+    });
+    newResponse(body?: BodyInit | null | undefined, init?: ResponseInit | undefined): Response;
+    text(text: string, status?: number, headers?: Headers): Response;
+    json(object: object, status?: number, headers?: Headers): Response;
+    html(html: string, status?: number, headers?: Headers): Response;
+    redirect(location: string, status?: number): Response;
+}
+export {};

package/dist/context.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Context = void 0;
+const util_1 = require("./util");
+class Context {
+    constructor(req, opts) {
+        this.req = req;
+        if (opts) {
+            this.res = opts.res;
+            this.env = opts.env;
+            this.event = opts.event;
+        }
+    }
+    newResponse(body, init) {
+        return new Response(body, init);
+    }
+    text(text, status = 200, headers = {}) {
+        if (typeof text !== 'string') {
+            throw new TypeError('text method arg must be a string!');
+        }
+        headers['Content-Type'] = 'text/plain';
+        return this.newResponse(text, {
+            status: status,
+            headers: headers,
+        });
+    }
+    json(object, status = 200, headers = {}) {
+        if (typeof object !== 'object') {
+            throw new TypeError('json method arg must be a object!');
+        }
+        const body = JSON.stringify(object);
+        headers['Content-Type'] = 'application/json; charset=UTF-8';
+        return this.newResponse(body, {
+            status: status,
+            headers: headers,
+        });
+    }
+    html(html, status = 200, headers = {}) {
+        if (typeof html !== 'string') {
+            throw new TypeError('html method arg must be a string!');
+        }
+        headers['Content-Type'] = 'text/html; charset=UTF-8';
+        return this.newResponse(html, {
+            status: status,
+            headers: headers,
+        });
+    }
+    redirect(location, status = 302) {
+        if (typeof location !== 'string') {
+            throw new TypeError('location must be a string!');
+        }
+        if (!(0, util_1.isAbsoluteURL)(location)) {
+            const url = new URL(this.req.url);
+            url.pathname = location;
+            location = url.toString();
+        }
+        return this.newResponse(null, {
+            status: status,
+            headers: {
+                Location: location,
+            },
+        });
+    }
+}
+exports.Context = Context;

package/dist/hono.d.ts

@@ -0,0 +1,43 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { Result } from './node';
+import { Node } from './node';
+import { Context } from './context';
+import type { Env } from './context';
+declare global {
+    interface Request {
+        params: (key: string) => string;
+        query: (key: string) => string | null;
+        parsedBody: any;
+    }
+}
+export declare type Handler = (c: Context, next?: Function) => Response | Promise<Response>;
+export declare type MiddlewareHandler = (c: Context, next: Function) => Promise<void>;
+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[]>;
+    middlewareRouters: Router<MiddlewareHandler>[];
+    tempPath: string;
+    constructor();
+    get(arg: string | Handler, ...args: Handler[]): Hono;
+    post(arg: string | Handler, ...args: Handler[]): Hono;
+    put(arg: string | Handler, ...args: Handler[]): Hono;
+    head(arg: string | Handler, ...args: Handler[]): Hono;
+    delete(arg: string | Handler, ...args: Handler[]): Hono;
+    options(arg: string | Handler, ...args: Handler[]): Hono;
+    patch(arg: string | Handler, ...args: Handler[]): Hono;
+    all(arg: string | Handler, ...args: Handler[]): 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[]>>;
+    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;
+    notFound(): Response;
+}