routup 2.0.0 → 3.0.0-alpha.2

package/README.md

@@ -12,14 +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, 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)).
-
+**Routup** is a fast, lightweight, runtime agnostic and asynchronous routing framework.
+Helpers provide additional functionalities to interact with the request and manipulate the response.
 
+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**
 
@@ -41,14 +38,14 @@ npm install routup --save
 ## Features
 
 - 🚀 runtime agnostic (Node.JS, Bun, Deno, ...)
-- 🧰 response & request composables/helpers
-- 💼 extendable & compact
-- 🛫 named route parameters
+- 📝 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 (inc. express 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
@@ -57,36 +54,92 @@ To read the docs, visit [https://routup.net](https://routup.net)
 
 ## Usage
 
-**`NodeJs`**
+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 {createServer} from 'node:http';
+import { createServer } from 'node:http';
 import {
+    coreHandler,
     createNodeDispatcher,
+    errorHandler,
     Router,
-    send
+    useRequestParam
 } from 'routup';
 
 const router = new Router();
 
-router.get('/', () => '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,
-    send
+    Router
 } from 'routup';
 
 const router = new Router();
 
-router.get('/', () => 'Hello World');
+router.get('/', coreHandler(() => 'Hello, World!'));
 
 const dispatch = createWebDispatcher(router);
 
@@ -102,14 +155,14 @@ Bun.serve({
 
 ```typescript
 import {
+    coreHandler,
     createWebDispatcher,
-    Router,
-    send
+    Router
 } from 'routup';
 
 const router = new Router();
 
-router.get('/', () => 'Hello World');
+router.get('/', coreHandler(() => 'Hello, World!'));
 
 const dispatch = createWebDispatcher(router);
 
@@ -134,17 +187,17 @@ 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
 

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

@@ -1,6 +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';
-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/type.d.ts

@@ -1,4 +1,6 @@
-import type { Request, Response } from '../types';
+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>;
 }
@@ -6,23 +8,23 @@ export type DispatcherMeta = {
     /**
      * Params collected on path.
      */
-    params?: Record<string, any>;
+    params: Record<string, any>;
     /**
      * Path to check for the current instance.
      */
-    path?: string;
+    path: string;
     /**
      * The relative path on which the router is hung.
      */
-    mountPath?: string;
+    mountPath: string;
     /**
      * The error which occurred during a previous handler.
      */
-    error?: Error;
+    error?: ErrorProxy;
     /**
      * Ids of chained router instances.
      */
-    routerIds?: number[];
+    routerPath: number[];
 };
 export type DispatcherEvent = {
     req: Request;

package/dist/dispatcher/utils.d.ts

@@ -1,4 +1,5 @@
 import type { DispatcherMeta } from './type';
-export declare function cloneDispatcherMeta(input?: DispatcherMeta): DispatcherMeta;
+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

@@ -0,0 +1,6 @@
+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;