routup 1.0.3 → 3.0.0-alpha.1

package/README.md

@@ -12,10 +12,11 @@
 [![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.
-It uses node's vanilla request and response interfaces, which are injected into route handlers aka middlewares as function argument.
+**Routup** is a fast, lightweight, runtime agnostic and asynchronous routing framework.
+Helpers provide additional functionalities to interact with the request and manipulate the response.
 
-Helpers provide additional functionalities to transform and interact with the request and manipulate the response upstream.
+It can be used independently of the selected runtime environment (Node.Js, Bun, ... ) 🎉.
+Moreover, it is even **228%** faster than Express ([more](#benchmarks)).
 
 **Table of Contents**
 
@@ -24,6 +25,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,15 +37,15 @@ npm install routup --save
 
 ## Features
 
-- 🚀 high performance routing
-- 🧰 response & request composables/helpers
-- 💼 extendable & compact
-- 🛫 named route parameters
+- 🚀 runtime agnostic (Node.JS, Bun, Deno, ...)
+- 📝 different handler types (base & error)
+- ✨ promise (async) support for core- & error-handlers
+- 🔌 powerful plugin system
+- 🧰 tree shakeable response & request helpers
+- 🤝️ different handler declaration styles (shorthand & verbose)
 - 📁 nestable routers
-- 🤝️ define one or many (error-) middlewares
-- ✨ promise support for route- & middleware-handlers
-- 👕 TypeScript fully supported
-- 🤏 Minimalistic to fit into any solution with minimum overhead
+- 👕 TypeScript support
+- 🤏 minimalistic to fit into any solution with minimum overhead
 - & much more
 
 ## Documentation
@@ -52,16 +54,131 @@ To read the docs, visit [https://routup.net](https://routup.net)
 
 ## Usage
 
+The following examples are intended to give a small insight into the use of the framework.
+However, it is highly recommended to read the [documentation](https://routup.net), 
+as all concepts and basics are taught there.
+
+### Handlers
+
+Both core and error handlers, can be defined in two different ways.
+
+**`Shorthand`**
+
+With the shorthand variant, 
+only the handler function is passed as argument to the **coreHandler** & **errorHandler** function.
+
 ```typescript
-import { Router, send } from 'routup';
+import { createServer } from 'node:http';
+import {
+    coreHandler,
+    createNodeDispatcher,
+    errorHandler,
+    Router,
+    useRequestParam
+} from 'routup';
 
 const router = new Router();
 
-router.get('/', (req, res) => {
-    send(res, 'Hello World');
+router.get('/', coreHandler(() => 'Hello, World!'));
+router.get('/greet/:name', coreHandler((req) => `Hello, ${useRequestParam(req, 'name')}!`));
+router.use(errorHandler((err) => `An error with statusCode ${err.statusCode} occured.`));
+
+const server = createServer(createNodeDispatcher(router));
+server.listen(3000)
+```
+
+**`Verbose`**
+
+The verbose variant is more complex, but offers the possibility to set additional information
+like **path**, **method**, ... in the handler definition.
+
+```typescript
+import { createServer } from 'node:http';
+import {
+    coreHandler,
+    createNodeDispatcher,
+    errorHandler,
+    Router,
+    useRequestParam
+} from 'routup';
+
+const router = new Router();
+
+router.get(coreHandler({
+    path: '/',
+    fn: () => 'Hello, World!',
+}));
+
+router.get(coreHandler({
+    path: '/greet/:name',
+    fn: (req) => `Hello, ${useRequestParam(req, 'name')}!`
+}))
+
+router.use(errorHandler({
+    fn: (err) => `An error with statusCode ${err.statusCode} occured.`
+}))
+
+const server = createServer(createNodeDispatcher(router));
+server.listen(3000)
+```
+
+### Runtimes
+
+It is possible to use any javascript runtime environment. Below are examples for Bun and Deno.
+These use the web dispatcher to submit requests based on the web api. Besides the node- & web-dispatcher, 
+there is also a plain dispatcher that underlies the web dispatcher, which can be controlled via a simple API.
+
+**`Bun`**
+
+```typescript
+import {
+    coreHandler,
+    createWebDispatcher,
+    Router
+} from 'routup';
+
+const router = new Router();
+
+router.get('/', coreHandler(() => 'Hello, World!'));
+
+const dispatch = createWebDispatcher(router);
+
+Bun.serve({
+    async fetch(request) {
+        return dispatch(request);
+    },
+    port: 3000,
 });
+```
+
+**`Deno`**
 
-router.listen(3000);
+```typescript
+import {
+    coreHandler,
+    createWebDispatcher,
+    Router
+} from 'routup';
+
+const router = new Router();
+
+router.get('/', coreHandler(() => '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
@@ -70,17 +187,37 @@ According to the fact that routup is a minimalistic framework,
 it depends on [plugins](https://github.com/routup/plugins) to cover some 
 typically http framework functions, which are not integrated in the main package.
 
-| Name                                                                       | Description                                                            |
-|----------------------------------------------------------------------------|------------------------------------------------------------------------|
-| [body](https://www.npmjs.com/package/@routup/body)                         | Read and parse the request body.                                       |
-| [cookie](https://www.npmjs.com/package/@routup/cookie)                     | Read and parse request cookies and serialize cookies for the response. |
-| [decorators](https://www.npmjs.com/package/@routup/decorators)             | Create request handlers with class-, method- & parameter-decorators.   |
-| [prometheus](https://www.npmjs.com/package/@routup/prometheus)             | Collect and serve metrics for prometheus.                              |
-| [query](https://www.npmjs.com/package/@routup/query)                       | Read and parse the query string of the request url.                    |
-| [rate-limit](https://www.npmjs.com/package/@routup/rate-limit)             | Rate limit incoming requests.                                          |
-| [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.                 |
+| Name                                                                                          | Description                                                            |
+|-----------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
+| [body](https://github.com/routup/plugins/tree/master/packages/body)                           | Read and parse the request body.                                       |
+| [cookie](https://github.com/routup/plugins/tree/master/packages/cookie)                       | Read and parse request cookies and serialize cookies for the response. |
+| [decorators](https://github.com/routup/plugins/tree/master/packages/decorators)               | Create request handlers with class-, method- & parameter-decorators.   |
+| [prometheus](https://github.com/routup/plugins/tree/master/packages/prometheus)               | Collect and serve metrics for prometheus.                              |
+| [query](https://github.com/routup/plugins/tree/master/packages/query)                         | Read and parse the query string of the request url.                    |
+| [rate-limit](https://github.com/routup/plugins/tree/master/packages/rate-limit)               | Rate limit incoming requests.                                          |
+| [rate-limit-redis](https://github.com/routup/plugins/tree/master/packages/rate-limit-redis)   | Redis adapter for the rate-limit plugin.                               |
+| [static](https://github.com/routup/plugins/tree/master/packages/static)                       | Serve static files from a directory.                                   |
+| [swagger](https://github.com/routup/plugins/tree/master/packages/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,7 @@
+/// <reference types="node" />
+import type { RequestListener } from 'node:http';
+import type { Request } from '../../../request';
+import type { Response } from '../../../response';
+import type { Router } from '../../../router';
+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/{route → dispatcher/adapters/web}/index.d.ts

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

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,32 @@
+import type { ErrorProxy } from '../error';
+import type { Request } from '../request';
+import type { Response } from '../response';
+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?: ErrorProxy;
+    /**
+     * Ids of chained router instances.
+     */
+    routerPath: number[];
+};
+export type DispatcherEvent = {
+    req: Request;
+    res: Response;
+};

package/dist/dispatcher/utils.d.ts

@@ -0,0 +1,5 @@
+import type { DispatcherMeta } from './type';
+export declare function buildDispatcherMeta(input: Partial<DispatcherMeta>): DispatcherMeta;
+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/create.d.ts

@@ -0,0 +1,11 @@
+import type { Input } from '@ebec/http';
+import { ErrorProxy } from './module';
+/**
+ * Create an error proxy by
+ * - an existing error (accessible via cause property)
+ * - options
+ * - message
+ *
+ * @param input
+ */
+export declare function createError(input: Input): ErrorProxy;

package/dist/error/index.d.ts

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

package/dist/error/is.d.ts

@@ -0,0 +1,2 @@
+import { ErrorProxy } from './module';
+export declare function isError(input: unknown): input is ErrorProxy;

package/dist/error/module.d.ts

@@ -0,0 +1,3 @@
+import { HTTPError } from '@ebec/http';
+export declare class ErrorProxy extends HTTPError {
+}

package/dist/handler/constants.d.ts

@@ -0,0 +1,4 @@
+export declare enum HandlerType {
+    CORE = "core",
+    ERROR = "error"
+}

package/dist/handler/core/define.d.ts

@@ -0,0 +1,3 @@
+import type { CoreHandler, CoreHandlerFn } from './types';
+export declare function coreHandler(input: Omit<CoreHandler, 'type'>): CoreHandler;
+export declare function coreHandler(input: CoreHandlerFn): CoreHandler;

package/dist/handler/core/index.d.ts

@@ -0,0 +1,2 @@
+export * from './define';
+export * from './types';

package/dist/handler/core/types.d.ts

@@ -0,0 +1,10 @@
+import type { Request } from '../../request';
+import type { Response } from '../../response';
+import type { HandlerType } from '../constants';
+import type { Next } from '../types';
+import type { HandlerBase } from '../types-base';
+export type CoreHandlerFn = (req: Request, res: Response, next: Next) => unknown | Promise<unknown>;
+export type CoreHandler = HandlerBase & {
+    type: `${HandlerType.CORE}`;
+    fn: CoreHandlerFn;
+};

package/dist/handler/error/define.d.ts

@@ -0,0 +1,3 @@
+import type { ErrorHandler, ErrorHandlerFn } from './types';
+export declare function errorHandler(input: Omit<ErrorHandler, 'type'>): ErrorHandler;
+export declare function errorHandler(input: ErrorHandlerFn): ErrorHandler;

package/dist/handler/error/index.d.ts

@@ -0,0 +1,2 @@
+export * from './define';
+export * from './types';

package/dist/handler/error/types.d.ts

@@ -0,0 +1,11 @@
+import type { ErrorProxy } from '../../error';
+import type { Request } from '../../request';
+import type { Response } from '../../response';
+import type { HandlerType } from '../constants';
+import type { Next } from '../types';
+import type { HandlerBase } from '../types-base';
+export type ErrorHandlerFn = (err: ErrorProxy, req: Request, res: Response, next: Next) => unknown | Promise<unknown>;
+export type ErrorHandler = HandlerBase & {
+    type: `${HandlerType.ERROR}`;
+    fn: ErrorHandlerFn;
+};

package/dist/handler/index.d.ts

@@ -1 +1,6 @@
-export * from './utils';
+export * from './core';
+export * from './error';
+export * from './constants';
+export * from './is';
+export * from './types';
+export * from './types-base';

package/dist/handler/is.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from './types';
+export declare function isHandler(input: unknown): input is Handler;

package/dist/handler/types-base.d.ts

@@ -0,0 +1,6 @@
+import type { MethodName } from '../constants';
+import type { Path } from '../path';
+export type HandlerBase = {
+    method?: `${MethodName}` | `${Uppercase<MethodName>}`;
+    path?: Path;
+};

package/dist/handler/types.d.ts

@@ -0,0 +1,5 @@
+import type { CoreHandler, CoreHandlerFn } from './core';
+import type { ErrorHandler, ErrorHandlerFn } from './error';
+export type Next = (err?: Error) => void;
+export type Handler = CoreHandler | ErrorHandler;
+export type HandlerFn = CoreHandlerFn | ErrorHandlerFn;