routup 1.0.2 → 2.0.0

package/README.md

@@ -12,11 +12,15 @@
 [![Known Vulnerabilities](https://snyk.io/test/github/Tada5hi/routup/badge.svg)](https://snyk.io/test/github/Tada5hi/routup)
 [![Conventional Commits](https://img.shields.io/badge/Conventional%20Commits-1.0.0-%23FE5196?logo=conventionalcommits&logoColor=white)](https://conventionalcommits.org)
 
-**Routup** is a lightweight, minimalistic and extendable http interface based routing framework.
+**Routup** is a lightweight, runtime agnostic and extendable routing library.
 It uses node's vanilla request and response interfaces, which are injected into route handlers aka middlewares as function argument.
-
 Helpers provide additional functionalities to transform and interact with the request and manipulate the response upstream.
 
+Use the same routing framework for each project, regardless of the used runtime environment (Node.Js, Bun, ... ) 🎉.
+Besides, it is even **228%** faster than Express ([more](#benchmarks)).
+
+
+
 **Table of Contents**
 
 - [Installation](#installation)
@@ -24,6 +28,7 @@ Helpers provide additional functionalities to transform and interact with the re
 - [Documentation](#documentation)
 - [Usage](#usage)
 - [Plugins](#plugins)
+- [Benchmarks](#benchmarks)
 - [Contributing](#contributing)
 - [License](#license)
 
@@ -35,12 +40,12 @@ npm install routup --save
 
 ## Features
 
-- 🚀 high performance routing
+- 🚀 runtime agnostic (Node.JS, Bun, Deno, ...)
 - 🧰 response & request composables/helpers
 - 💼 extendable & compact
 - 🛫 named route parameters
 - 📁 nestable routers
-- 🤝️ define one or many (error-) middlewares
+- 🤝️ define one or many (error-) middlewares (inc. express middlewares)
 - ✨ promise support for route- & middleware-handlers
 - 👕 TypeScript fully supported
 - 🤏 Minimalistic to fit into any solution with minimum overhead
@@ -52,16 +57,75 @@ To read the docs, visit [https://routup.net](https://routup.net)
 
 ## Usage
 
+**`NodeJs`**
+
+```typescript
+import {createServer} from 'node:http';
+import {
+    createNodeDispatcher,
+    Router,
+    send
+} from 'routup';
+
+const router = new Router();
+
+router.get('/', () => 'Hello World');
+
+const server = createServer(createNodeDispatcher(router));
+server.listen(3000)
+```
+
+**`Bun`**
+
 ```typescript
-import { Router, send } from 'routup';
+import {
+    createWebDispatcher,
+    Router,
+    send
+} from 'routup';
 
 const router = new Router();
 
-router.get('/', (req, res) => {
-    send(res, 'Hello World');
+router.get('/', () => 'Hello World');
+
+const dispatch = createWebDispatcher(router);
+
+Bun.serve({
+    async fetch(request) {
+        return dispatch(request);
+    },
+    port: 3000,
 });
+```
+
+**`Deno`**
+
+```typescript
+import {
+    createWebDispatcher,
+    Router,
+    send
+} from 'routup';
 
-router.listen(3000);
+const router = new Router();
+
+router.get('/', () => 'Hello World');
+
+const dispatch = createWebDispatcher(router);
+
+const server = Deno.listen({
+    port: 3000
+});
+for await (const conn of server) {
+    const httpConn = Deno.serveHttp(conn);
+
+    for await (const requestEvent of httpConn) {
+        const response = await dispatch(
+            requestEvent.request
+        );
+        requestEvent.respondWith(response);
+    }
+}
 ```
 
 ## Plugins
@@ -81,6 +145,26 @@ typically http framework functions, which are not integrated in the main package
 | [rate-limit-redis](https://www.npmjs.com/package/@routup/rate-limit-redis) | Redis adapter for the rate-limit plugin.                               |
 | [static](https://www.npmjs.com/package/@routup/static)                     | Serve static files from a directory.                                   |
 | [swagger](https://www.npmjs.com/package/@routup/swagger)                   | Serve generated docs from URL or based on a JSON file.                 |
+
+## Benchmarks
+
+* CPUs:  `24`
+* RAM:  `63.9GB`
+* Node: `v18.16.0`
+* Date:  `Wed Sep 13 2023 15:11:58 GMT+0200 (Mitteleuropäische Sommerzeit) `
+* Method: `autocannon -c 100 -d 40 -p 10 localhost:3000` (two rounds; one to warm-up, one to measure)
+
+| Package    | Requests/s  |  Latency (ms) |   Throughput/MB |
+|:-----------|:-----------:|--------------:|----------------:|
+| http       |    61062    |         15.87 |           10.89 |
+| fastify    |    59679    |         16.26 |           10.70 |
+| koa        |    45763    |         21.35 |            8.16 |
+| **routup** |    43881    |         22.29 |            8.87 |
+| hapi       |    41374    |         23.67 |            7.38 |
+| express    |    13376    |         74.18 |            2.39 |
+
+Benchmarks were generated using autocannon. 
+To recreate the results, this can be done using the [benchmarks'](https://github.com/routup/benchmarks) repository.
 ## Contributing
 
 Before starting to work on a pull request, it is important to review the guidelines for

package/dist/dispatcher/adapters/index.d.ts

@@ -0,0 +1,3 @@
+export * from './node';
+export * from './raw';
+export * from './web';

package/dist/dispatcher/adapters/node/index.d.ts

@@ -0,0 +1 @@
+export * from './module';

package/dist/dispatcher/adapters/node/module.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="node" />
+import type { RequestListener } from 'node:http';
+import type { Router } from '../../../router';
+import type { Request, Response } from '../../../types';
+export declare function dispatchNodeRequest(router: Router, req: Request, res: Response): Promise<void>;
+export declare function createNodeDispatcher(router: Router): RequestListener;

package/dist/dispatcher/adapters/raw/module.d.ts

@@ -0,0 +1,4 @@
+import type { Router } from '../../../router';
+import type { DispatchRawRequestOptions, RawRequest, RawResponse } from './type';
+export declare function dispatchRawRequest(router: Router, request: RawRequest, options?: DispatchRawRequestOptions): Promise<RawResponse>;
+export declare function createRawDispatcher(router: Router): (request: RawRequest) => Promise<RawResponse>;

package/dist/dispatcher/adapters/raw/type.d.ts

@@ -0,0 +1,18 @@
+import type { RequestBody, RequestHeaders } from '../../../request';
+export type RawRequest = {
+    method: string;
+    path: string;
+    headers?: RequestHeaders;
+    body?: RequestBody;
+};
+export type RawResponseHeader = string | string[];
+export type RawResponseHeaders = Record<string, RawResponseHeader>;
+export type RawResponse = {
+    status: number;
+    statusMessage?: string;
+    headers: RawResponseHeaders;
+    body?: ArrayBuffer;
+};
+export type DispatchRawRequestOptions = {
+    throwOnError?: boolean;
+};

package/dist/dispatcher/adapters/web/index.d.ts

@@ -0,0 +1,2 @@
+export * from './module';
+export * from './type';

package/dist/dispatcher/adapters/web/module.d.ts

@@ -0,0 +1,5 @@
+import type { Router } from '../../../router';
+import type { WebRequest } from '../../../types';
+import type { DispatchWebRequestOptions } from './type';
+export declare function dispatchWebRequest(router: Router, request: WebRequest, options?: DispatchWebRequestOptions): Promise<Response>;
+export declare function createWebDispatcher(router: Router): (request: WebRequest) => Promise<Response>;

package/dist/dispatcher/adapters/web/type.d.ts

@@ -0,0 +1,3 @@
+export type DispatchWebRequestOptions = {
+    throwOnError?: boolean;
+};

package/dist/dispatcher/index.d.ts

@@ -0,0 +1,3 @@
+export * from './adapters';
+export * from './type';
+export * from './utils';

package/dist/dispatcher/type.d.ts

@@ -0,0 +1,30 @@
+import type { Request, Response } from '../types';
+export interface Dispatcher {
+    dispatch(event: DispatcherEvent, meta: DispatcherMeta): Promise<boolean>;
+}
+export type DispatcherMeta = {
+    /**
+     * Params collected on path.
+     */
+    params?: Record<string, any>;
+    /**
+     * Path to check for the current instance.
+     */
+    path?: string;
+    /**
+     * The relative path on which the router is hung.
+     */
+    mountPath?: string;
+    /**
+     * The error which occurred during a previous handler.
+     */
+    error?: Error;
+    /**
+     * Ids of chained router instances.
+     */
+    routerIds?: number[];
+};
+export type DispatcherEvent = {
+    req: Request;
+    res: Response;
+};

package/dist/dispatcher/utils.d.ts

@@ -0,0 +1,4 @@
+import type { DispatcherMeta } from './type';
+export declare function cloneDispatcherMeta(input?: DispatcherMeta): DispatcherMeta;
+export declare function cloneDispatcherMetaParams(input?: Record<string, any>): Record<string, any>;
+export declare function mergeDispatcherMetaParams(t1?: Record<string, any>, t2?: Record<string, any>): Record<string, any>;

package/dist/error.d.ts

@@ -0,0 +1 @@
+export declare function createError(input: Error | Record<string, any>): Error;