hono 0.0.8 → 0.0.12

package/README.md

@@ -6,31 +6,43 @@ Hono [炎] - Tiny web framework for Cloudflare Workers and others.
 const { Hono } = require('hono')
 const app = new Hono()
 
-app.get('/', () => new Response('Hono!!'))
+app.get('/', (c) => c.text('Hono!!'))
 
 app.fire()
 ```
 
-## Feature
+Hono[炎] - _**means flame🔥 in Japanese**_ - is small, fast and simple web flamework for a Service Workers API based serverless such as **Cloudflare Workers** and **Fastly Compute@Edge**. Hono does not depend on any npm packages. However, Hono has a router, context object, and middleware including the builtins. It's easy to make a web application.
 
-- 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.
+## Features
+
+- **Fast** - the router is implemented with Trie-Tree structure.
+- **Tiny** - zero dependencies, using Web standard API.
+- **Flexible** - you can make your own middleware.
+- **Easy** - simple API, builtin middleware, and written in TypeScript.
+- **Optimized** - for Cloudflare Workers or Fastly Compute@Edge.
 
 ## Benchmark
 
+**Hono is fastest** compared to other routers for Cloudflare Workers.
+
 ```
-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 x 758,264 ops/sec ±5.41% (75 runs sampled)
+itty-router x 158,359 ops/sec ±3.21% (89 runs sampled)
+sunder x 297,581 ops/sec ±4.74% (83 runs sampled)
 Fastest is hono
-✨  Done in 37.03s.
+✨  Done in 42.84s.
 ```
 
+## 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
 
+You can install from npm registry:
+
 ```
 $ yarn add hono
 ```
@@ -43,10 +55,13 @@ $ 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**()
 
 ## Routing
 
@@ -100,6 +115,15 @@ 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
@@ -109,82 +133,243 @@ const { Hono, Middleware } = require('hono')
 
 ...
 
-app.use('*', Middleware.poweredBy)
-
+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
+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}`)
+})
+
+// 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.text()
 
-### query
+Render text as `Content-Type:text/plain`:
 
 ```js
-app.get('/search', (c) => {
-  const query = c.req.query('q')
-  ...
+app.get('/say', (c) => {
+  return c.text('Hello!')
 })
 ```
 
-### params
+### c.json()
+
+Render JSON as `Content-Type:application/json`:
 
 ```js
-app.get('/entry/:id', (c) => {
-  const id = c.req.params('id')
-  ...
+app.get('/api', (c) => {
+  return c.json({ message: 'Hello!' })
 })
 ```
 
+### c.html()
+
+Render HTML as `Content-Type:text/html`:
+
+```js
+app.get('/api', (c) => {
+  return c.html('<h1>Hello! Hono!</h1>')
+})
+```
+
+## fire
+
+`app.fire()` do:
+
+```js
+addEventListener('fetch', (event) => {
+  event.respondWith(this.handleEvent(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.
+
+```
+$ npm i hono
+```
+
+### 5. Write your app
+
+Only 4 lines!!
+
+```js
+const { Hono } = require('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) and [Sunder](https://github.com/SunderJS/sunder) 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>
 
+## 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
 
 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,9 @@
+export declare class Context {
+    req: Request;
+    res: Response;
+    constructor(req: Request, res: Response);
+    newResponse(body?: BodyInit | null | undefined, init?: ResponseInit | undefined): Response;
+    text(body: string): Response;
+    json(object: object, replacer?: (string | number)[], space?: string | number): Response;
+    html(body: string): Response;
+}

package/dist/context.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Context = void 0;
+class Context {
+    constructor(req, res) {
+        this.req = req;
+        this.res = res;
+    }
+    newResponse(body, init) {
+        return new Response(body, init);
+    }
+    text(body) {
+        if (typeof body !== 'string') {
+            throw new TypeError('text method arg must be a string!');
+        }
+        return this.newResponse(body, {
+            status: 200,
+            headers: {
+                'Content-Type': 'text/plain',
+            },
+        });
+    }
+    json(object, replacer, space) {
+        if (typeof object !== 'object') {
+            throw new TypeError('json method arg must be a object!');
+        }
+        const body = JSON.stringify(object, replacer, space);
+        return this.newResponse(body, {
+            status: 200,
+            headers: {
+                'Content-Type': 'application/json; charset=UTF-8',
+            },
+        });
+    }
+    html(body) {
+        if (typeof body !== 'string') {
+            throw new TypeError('html method arg must be a string!');
+        }
+        return this.newResponse(body, {
+            status: 200,
+            headers: {
+                'Content-Type': 'text/html; charset=UTF-8',
+            },
+        });
+    }
+}
+exports.Context = Context;

package/dist/hono.d.ts

@@ -0,0 +1,42 @@
+/// <reference types="@cloudflare/workers-types" />
+import type { Result } from './node';
+import { Node } from './node';
+import { Middleware } from './middleware';
+import { Context } from './context';
+export { Middleware };
+declare global {
+    interface Request {
+        params: (key: string) => any;
+        query: (key: string) => string | null;
+    }
+}
+declare type Handler = (c: Context, next?: Function) => Response | Promise<Response>;
+declare type MiddlwareHandler = (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<MiddlwareHandler>[];
+    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: MiddlwareHandler): void;
+    addRoute(method: string, arg: string | Handler, ...args: Handler[]): Hono;
+    matchRoute(method: string, path: string): Promise<Result<Handler[]>>;
+    dispatch(request: Request, response?: Response): Promise<Response>;
+    handleEvent(event: FetchEvent): Promise<Response>;
+    fire(): void;
+    notFound(): Response;
+}

package/dist/hono.js

@@ -0,0 +1,137 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Hono = exports.Router = exports.Middleware = void 0;
+const node_1 = require("./node");
+const compose_1 = require("./compose");
+const util_1 = require("./util");
+const middleware_1 = require("./middleware");
+Object.defineProperty(exports, "Middleware", { enumerable: true, get: function () { return middleware_1.Middleware; } });
+const context_1 = require("./context");
+const METHOD_NAME_OF_ALL = 'ALL';
+class Router {
+    constructor() {
+        this.node = new node_1.Node();
+    }
+    add(method, path, handler) {
+        this.node.insert(method, path, handler);
+    }
+    match(method, path) {
+        return this.node.search(method, path);
+    }
+}
+exports.Router = Router;
+class Hono {
+    constructor() {
+        this.router = new Router();
+        this.middlewareRouters = [];
+        this.tempPath = '/';
+    }
+    /* HTTP METHODS */
+    get(arg, ...args) {
+        return this.addRoute('get', arg, ...args);
+    }
+    post(arg, ...args) {
+        return this.addRoute('post', arg, ...args);
+    }
+    put(arg, ...args) {
+        return this.addRoute('put', arg, ...args);
+    }
+    head(arg, ...args) {
+        return this.addRoute('head', arg, ...args);
+    }
+    delete(arg, ...args) {
+        return this.addRoute('delete', arg, ...args);
+    }
+    options(arg, ...args) {
+        return this.addRoute('options', arg, ...args);
+    }
+    patch(arg, ...args) {
+        return this.addRoute('patch', arg, ...args);
+    }
+    /*
+    trace
+    copy
+    lock
+    purge
+    unlock
+    report
+    checkout
+    merge
+    notify
+    subscribe
+    unsubscribe
+    search
+    connect
+    */
+    all(arg, ...args) {
+        return this.addRoute('all', arg, ...args);
+    }
+    route(path) {
+        this.tempPath = path;
+        return this;
+    }
+    use(path, middleware) {
+        if (middleware.constructor.name !== 'AsyncFunction') {
+            throw new TypeError('middleware must be a async function!');
+        }
+        const router = new Router();
+        router.add(METHOD_NAME_OF_ALL, path, middleware);
+        this.middlewareRouters.push(router);
+    }
+    // addRoute('get', '/', handler)
+    addRoute(method, arg, ...args) {
+        method = method.toUpperCase();
+        if (typeof arg === 'string') {
+            this.tempPath = arg;
+            this.router.add(method, arg, args);
+        }
+        else {
+            args.unshift(arg);
+            this.router.add(method, this.tempPath, args);
+        }
+        return this;
+    }
+    async matchRoute(method, path) {
+        return this.router.match(method, path);
+    }
+    async dispatch(request, response) {
+        const [method, path] = [request.method, (0, util_1.getPathFromURL)(request.url)];
+        const result = await this.matchRoute(method, path);
+        request.params = (key) => {
+            if (result) {
+                return result.params[key];
+            }
+            return '';
+        };
+        const handler = result ? result.handler[0] : this.notFound; // XXX
+        const middleware = [];
+        for (const mr of this.middlewareRouters) {
+            const mwResult = mr.match(METHOD_NAME_OF_ALL, path);
+            if (mwResult) {
+                middleware.push(mwResult.handler);
+            }
+        }
+        const wrappedHandler = async (context, next) => {
+            context.res = await handler(context);
+            await next();
+        };
+        middleware.push(middleware_1.Middleware.defaultFilter);
+        middleware.push(wrappedHandler);
+        const composed = (0, compose_1.compose)(middleware);
+        const c = new context_1.Context(request, response);
+        await composed(c);
+        return c.res;
+    }
+    async handleEvent(event) {
+        return this.dispatch(event.request);
+    }
+    fire() {
+        addEventListener('fetch', (event) => {
+            event.respondWith(this.handleEvent(event));
+        });
+    }
+    notFound() {
+        return new Response('Not Found', { status: 404 });
+    }
+}
+exports.Hono = Hono;

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Hono, Middleware } from './hono';
+export { Context } from './context';

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Context = exports.Middleware = exports.Hono = void 0;
+var hono_1 = require("./hono");
+Object.defineProperty(exports, "Hono", { enumerable: true, get: function () { return hono_1.Hono; } });
+Object.defineProperty(exports, "Middleware", { enumerable: true, get: function () { return hono_1.Middleware; } });
+var context_1 = require("./context");
+Object.defineProperty(exports, "Context", { enumerable: true, get: function () { return context_1.Context; } });

package/dist/middleware/basic-auth/basic-auth.d.ts

@@ -0,0 +1,6 @@
+import type { Context } from '../../context';
+export declare const basicAuth: (options: {
+    username: string;
+    password: string;
+    realm?: string;
+}) => (ctx: Context, next: Function) => Promise<any>;

package/dist/middleware/basic-auth/basic-auth.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.basicAuth = void 0;
+const util_1 = require("../../util");
+const CREDENTIALS_REGEXP = /^ *(?:[Bb][Aa][Ss][Ii][Cc]) +([A-Za-z0-9._~+/-]+=*) *$/;
+const USER_PASS_REGEXP = /^([^:]*):(.*)$/;
+const auth = (req) => {
+    if (!req) {
+        throw new TypeError('argument req is required');
+    }
+    if (typeof req !== 'object') {
+        throw new TypeError('argument req is required to be an object');
+    }
+    if (!req.headers || typeof req.headers !== 'object') {
+        throw new TypeError('argument req is required to have headers property');
+    }
+    const match = CREDENTIALS_REGEXP.exec(req.headers.get('Authorization'));
+    if (!match) {
+        return undefined;
+    }
+    const userPass = USER_PASS_REGEXP.exec(decodeBase64(match[1]));
+    if (!userPass) {
+        return undefined;
+    }
+    return { username: userPass[1], password: userPass[2] };
+};
+function decodeBase64(str) {
+    return Buffer.from(str, 'base64').toString();
+}
+const basicAuth = (options) => {
+    if (!options.realm) {
+        options.realm = 'Secure Area';
+    }
+    return async (ctx, next) => {
+        const user = auth(ctx.req);
+        const usernameEqual = user && await (0, util_1.timingSafeEqual)(options.username, user.username);
+        const passwordEqual = user && await (0, util_1.timingSafeEqual)(options.password, user.password);
+        if (!user || !usernameEqual || !passwordEqual) {
+            ctx.res = new Response('Unauthorized', {
+                status: 401,
+                headers: {
+                    'WWW-Authenticate': 'Basic realm="' + options.realm.replace(/"/g, '\\"') + '"',
+                },
+            });
+            return;
+        }
+        return next();
+    };
+};
+exports.basicAuth = basicAuth;