routup 3.0.0-alpha.3 → 3.1.0

package/README.md

@@ -40,6 +40,7 @@ npm install routup --save
 - 🚀 runtime agnostic (Node.JS, Bun, Deno, ...)
 - 📝 different handler types (base & error)
 - ✨ promise (async) support for core- & error-handlers
+- 📌 robust hook system
 - 🔌 powerful plugin system
 - 🧰 tree shakeable response & request helpers
 - 🤝️ different handler declaration styles (shorthand & verbose)
@@ -61,6 +62,8 @@ as all concepts and basics are taught there.
 ### Handlers
 
 Both core and error handlers, can be defined in two different ways.
+Core handler functions can have up to 3 arguments (req, res, next) whereas error handler functions can have up to 4 arguments (err, req, res, next).
+This should be familiar to anyone who has used express before.
 
 **`Shorthand`**
 
@@ -187,17 +190,18 @@ 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://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.                 |
+| Name                                                                                        | Description                                                            |
+|---------------------------------------------------------------------------------------------|------------------------------------------------------------------------|
+| [assets](https://github.com/routup/plugins/tree/master/packages/assets)                     | Serve static files from a directory.                                   |
+| [basic](https://github.com/routup/plugins/tree/master/packages/basic)                       | Bundle of the body, cookie and query plugin.                           |
+| [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.                               |
+| [swagger](https://github.com/routup/plugins/tree/master/packages/swagger)                   | Serve generated docs from URL or based on a JSON file.                 |
 
 ## Benchmarks
 
@@ -207,14 +211,14 @@ typically http framework functions, which are not integrated in the main package
 * 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 |
+| 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** |    44588    |        21.91 |          9.02 |
+| 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.

package/dist/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, request: Request, response: Response): Promise<void>;
+export declare function createNodeDispatcher(router: Router): RequestListener;

package/dist/{utils → adapters/raw}/header.d.ts

@@ -1,3 +1,3 @@
-import type { RawResponseHeader } from '../dispatcher';
+import type { RawResponseHeader } from './type';
 export declare function transformHeaderToTuples(key: string, value: RawResponseHeader): [string, string][];
 export declare function transformHeadersToTuples(input: Record<string, RawResponseHeader>): [string, string][];

package/dist/{layer → adapters/raw}/index.d.ts

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

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

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

package/dist/{dispatcher/adapters → adapters}/raw/type.d.ts

@@ -1,4 +1,4 @@
-import type { RequestBody, RequestHeaders } from '../../../request';
+import type { RequestBody, RequestHeaders } from '../../request';
 export type RawRequest = {
     method: string;
     path: string;

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

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

package/dist/constants.d.ts

@@ -1,11 +1,11 @@
 export declare enum MethodName {
-    GET = "get",
-    POST = "post",
-    PUT = "put",
-    PATCH = "patch",
-    DELETE = "delete",
-    OPTIONS = "options",
-    HEAD = "head"
+    GET = "GET",
+    POST = "POST",
+    PUT = "PUT",
+    PATCH = "PATCH",
+    DELETE = "DELETE",
+    OPTIONS = "OPTIONS",
+    HEAD = "HEAD"
 }
 export declare enum HeaderName {
     ACCEPT = "accept",

package/dist/dispatcher/event/dispatch.d.ts

@@ -0,0 +1,4 @@
+import type { DispatchEvent } from './module';
+type DispatchTargetFn = (next: (err?: Error) => any) => unknown;
+export declare function dispatch(event: DispatchEvent, target: DispatchTargetFn): Promise<boolean>;
+export {};

package/dist/dispatcher/event/error.d.ts

@@ -0,0 +1,5 @@
+import type { RoutupError } from '../../error';
+import { DispatchEvent } from './module';
+export declare class DispatchErrorEvent extends DispatchEvent {
+    error: RoutupError;
+}

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

@@ -0,0 +1,5 @@
+export * from './dispatch';
+export * from './is';
+export * from './error';
+export * from './module';
+export * from './types';

package/dist/dispatcher/event/is.d.ts

@@ -0,0 +1,3 @@
+import type { DispatchErrorEvent } from './error';
+import type { DispatchEvent } from './module';
+export declare function isDispatcherErrorEvent(event: DispatchEvent | DispatchErrorEvent): event is DispatchErrorEvent;

package/dist/dispatcher/event/module.d.ts

@@ -0,0 +1,56 @@
+import { MethodName } from '../../constants';
+import type { RoutupError } from '../../error';
+import type { Request } from '../../request';
+import type { Response } from '../../response';
+import type { Next } from '../../types';
+import type { DispatchEventCreateContext } from './types';
+export declare class DispatchEvent {
+    /**
+     * Request Object.
+     */
+    request: Request;
+    /**
+     * Response Object.
+     */
+    response: Response;
+    /**
+     * Params collected during execution.
+     */
+    params: Record<string, any>;
+    /**
+     * Request path.
+     */
+    path: string;
+    /**
+     * HTTP Method used for the request.
+     */
+    method: `${MethodName}`;
+    /**
+     * The relative path on which the router is hung.
+     */
+    mountPath: string;
+    /**
+     * The error which occurred during the dispatch process.
+     */
+    error?: RoutupError;
+    /**
+     * Signal that the request hasn't been handled.
+     * Therefore, the request must be passed to the next handler or router in the chain.
+     */
+    next: Next;
+    /**
+     * Indicate if the request has already been dispatched/send.
+     */
+    protected _dispatched: boolean;
+    /**
+     * Ids of chained router instances.
+     */
+    routerPath: number[];
+    /**
+     * Collected methods during dispatch process.
+     */
+    methodsAllowed: string[];
+    constructor(context: DispatchEventCreateContext);
+    get dispatched(): boolean;
+    set dispatched(value: boolean);
+}

package/dist/dispatcher/event/types.d.ts

@@ -0,0 +1,9 @@
+import type { MethodName } from '../../constants';
+import type { Request } from '../../request';
+import type { Response } from '../../response';
+export type DispatchEventCreateContext = {
+    request: Request;
+    response: Response;
+    method?: `${MethodName}`;
+    path?: string;
+};

package/dist/dispatcher/index.d.ts

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

package/dist/dispatcher/type.d.ts

@@ -1,32 +1,4 @@
-import type { ErrorProxy } from '../error';
-import type { Request } from '../request';
-import type { Response } from '../response';
+import type { DispatchEvent } from './event';
 export interface Dispatcher {
-    dispatch(event: DispatcherEvent, meta: DispatcherMeta): Promise<boolean>;
+    dispatch(event: DispatchEvent): Promise<void>;
 }
-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/error/create.d.ts

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

package/dist/error/is.d.ts

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

package/dist/error/module.d.ts

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

package/dist/handler/constants.d.ts

@@ -2,3 +2,4 @@ export declare enum HandlerType {
     CORE = "core",
     ERROR = "error"
 }
+export declare const HandlerSymbol: unique symbol;

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

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

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

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

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

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

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

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

package/dist/handler/index.d.ts

@@ -2,5 +2,6 @@ export * from './core';
 export * from './error';
 export * from './constants';
 export * from './is';
+export * from './module';
 export * from './types';
 export * from './types-base';

package/dist/handler/is.d.ts

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

package/dist/handler/module.d.ts

@@ -0,0 +1,23 @@
+import { MethodName } from '../constants';
+import type { DispatchEvent, Dispatcher } from '../dispatcher';
+import { HookManager } from '../hook';
+import type { Path } from '../path';
+import { PathMatcher } from '../path';
+import type { HandlerConfig } from './types';
+export declare class Handler implements Dispatcher {
+    readonly '@instanceof': symbol;
+    protected config: HandlerConfig;
+    protected hookManager: HookManager;
+    protected pathMatcher: PathMatcher | undefined;
+    protected _method: MethodName | undefined;
+    constructor(handler: HandlerConfig);
+    get type(): "error" | "core";
+    get path(): Path | undefined;
+    get method(): MethodName | undefined;
+    dispatch(event: DispatchEvent): Promise<void>;
+    matchPath(path: string): boolean;
+    setPath(path?: Path): void;
+    matchMethod(method: `${MethodName}`): boolean;
+    setMethod(input?: `${MethodName}`): void;
+    protected mountHooks(): void;
+}

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

@@ -1,6 +1,10 @@
 import type { MethodName } from '../constants';
+import type { HookDefaultListener, HookErrorListener } from '../hook';
 import type { Path } from '../path';
-export type HandlerBase = {
-    method?: `${MethodName}` | `${Uppercase<MethodName>}`;
+export type HandlerBaseConfig = {
+    method?: Uppercase<MethodName> | Lowercase<MethodName>;
     path?: Path;
+    onError?: HookErrorListener;
+    onBefore?: HookDefaultListener;
+    onAfter?: HookDefaultListener;
 };

package/dist/handler/types.d.ts

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

package/dist/hook/constants.d.ts

@@ -0,0 +1,8 @@
+export declare enum HookName {
+    ERROR = "error",
+    DISPATCH_START = "dispatchStart",
+    DISPATCH_END = "dispatchEnd",
+    CHILD_MATCH = "childMatch",
+    CHILD_DISPATCH_BEFORE = "childDispatchBefore",
+    CHILD_DISPATCH_AFTER = "childDispatchAfter"
+}

package/dist/hook/index.d.ts

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

package/dist/hook/module.d.ts

@@ -0,0 +1,19 @@
+import type { DispatchEvent } from '../dispatcher';
+import { HookName } from './constants';
+import type { HookListener, HookUnsubscribeFn } from './types';
+export declare class HookManager {
+    protected items: Record<string, HookListener[]>;
+    constructor();
+    addListener(name: `${HookName}`, fn: HookListener): HookUnsubscribeFn;
+    removeListener(name: `${HookName}`): void;
+    removeListener(name: `${HookName}`, fn: HookListener): void;
+    /**
+     * @throws RoutupError
+     *
+     * @param name
+     * @param event
+     */
+    trigger(name: `${HookName}`, event: DispatchEvent): Promise<void>;
+    private triggerListener;
+    private isErrorListenerHook;
+}

package/dist/hook/types.d.ts

@@ -0,0 +1,5 @@
+import type { DispatchErrorEvent, DispatchEvent } from '../dispatcher';
+export type HookErrorListener = (event: DispatchErrorEvent) => Promise<unknown> | unknown;
+export type HookDefaultListener = (event: DispatchEvent) => Promise<unknown> | unknown;
+export type HookListener = HookErrorListener | HookDefaultListener;
+export type HookUnsubscribeFn = () => void;