Merge pull request #2 from typescript-package/develop

v0.0.2

Author: sciborrudnicki

README.md

@@ -16,13 +16,17 @@
 
 A **lightweight** TypeScript library for middleware.
 
-## Features
-
 ## Table of contents
 
+- [Features](#features)
 - [Installation](#installation)
 - [Api](#api)
+  - Abstract
+    - [`ContextMiddlewareBase`](#contextmiddlewarebase)
+    - [`MiddlewareBase`](#middlewarebase)
+    - [`MiddlewareCore`](#middlewarecore)
   - Class
+    - [`ContextMiddleware`](#contextmiddleware)
     - [`Middleware`](#middleware)
 - [Contributing](#contributing)
 - [Support](#support)
@@ -33,6 +37,13 @@ A **lightweight** TypeScript library for middleware.
 - [License](#license)
 - [Related packages](#related-packages)
 
+### Features
+
+- **Core abstraction**: Class for both arguments-based (array) and object-based (context) middleware.
+- **Base abstraction**: Extends core abstraction with functionality to build new arguments-based middlewares.
+- **Concrete class**: Extension of base for initialization.
+- **Context middleware**: Context object-based `ContextMiddleware` base and concrete middleware built on `MiddlewareBase`.
+
 ## Installation
 
 ### 1. Install the package
@@ -43,6 +54,24 @@ npm install @typescript-package/middleware --save-peer
 
 ## Api
 
+### `ContextMiddlewareBase`
+
+```typescript
+import { ContextMiddlewareBase } from '@typescript-package/middleware';
+```
+
+### `MiddlewareCore`
+
+```typescript
+import { MiddlewareCore } from '@typescript-package/middleware';
+```
+
+### `MiddlewareBase`
+
+```typescript
+import { MiddlewareBase } from '@typescript-package/middleware';
+```
+
 ### `Middleware`
 
 ```typescript
@@ -96,6 +125,38 @@ middleware.onComplete((args) => {
 middleware.executeAsync({ key: 'value' });
 ```
 
+### `ContextMiddleware`
+
+```typescript
+import { ContextMiddleware } from '@typescript-package/middleware';
+
+const contextMiddleware = new ContextMiddleware<{ req: string; res?: string }>(
+  (context, next: () => void) => {
+    console.log('Middleware 0 executed with args:', context);
+    next();
+  },
+  (context, next: () => void) => {
+    console.log('Middleware 00 executed with args:', context);
+    next();
+  }
+);
+
+contextMiddleware.use((context, next) => {
+  console.log('Middleware 1 executed with args:', context);
+  context.req = 'newValue';
+  next();
+});
+
+
+contextMiddleware.use((context, next) => {
+  console.log('Middleware 2 executed with args:', context);
+  next();
+});
+
+contextMiddleware.execute({ req: 'value' });
+
+```
+
 ## Contributing
 
 Your contributions are valued! If you'd like to contribute, please feel free to submit a pull request. Help is always appreciated.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@typescript-package/middleware",
-  "version": "0.0.1",
+  "version": "0.0.2",
   "author": "wwwdev.io <dev@wwwdev.io>",
   "description": "A lightweight TypeScript library for middleware.",
   "license": "MIT",
@@ -27,6 +27,10 @@
     "@typescript-package/middleware"
   ],
   "funding": [
+    {
+      "type": "stripe",
+      "url": "https://donate.stripe.com/dR614hfDZcJE3wAcMM"
+    },
     {
       "type": "individual",
       "url": "https://checkout.revolut.com/pay/048b10a3-0e10-42c8-a917-e3e9cb4c8e29"

src/interface/index.ts

@@ -0,0 +1 @@
+export type { MiddlewareShape } from './middleware.shape';

src/interface/middleware.shape.ts

@@ -0,0 +1,16 @@
+/**
+ * @description The shape of a middleware system.
+ * @export
+ * @interface MiddlewareShape
+ * @typedef {MiddlewareShape}
+ * @template [Input=any] The type of the arguments passed to middleware functions.
+ * @template [Output=any] The type of the output returned by middleware functions.
+ * @template [Middleware=any] The type of the middleware.
+ */
+export interface MiddlewareShape<Input = any, Output = any, Middleware = any> {
+  execute(context: Input): void;
+  execute(...args: Input[]): void;
+  use(middleware: Middleware): this;
+  executeAsync(context: Input): Promise<Output>;
+  executeAsync(...args: Input[]): Promise<Output>;
+}

src/lib/context-middleware-base.abstract.ts

@@ -0,0 +1,56 @@
+// Abstract.
+import { MiddlewareBase } from './middleware-base.abstract';
+// Type.
+import { ContextMiddlewareFunction } from '../type';
+/**
+ * @description
+ * @export
+ * @abstract
+ * @class ContextMiddlewareBase
+ * @template [T=any] 
+ * @template {Function} [U=ContextMiddlewareFunction<T>] 
+ * @extends {MiddlewareBase<T, T, U>}
+ */
+export abstract class ContextMiddlewareBase<
+  T = any,
+  U extends Function = ContextMiddlewareFunction<T>
+> extends MiddlewareBase<T, T, U> {
+  /**
+   * @description
+   * @public
+   * @param {T} context 
+   */
+  public override execute(context: T) {
+    return super.execute(context), this;
+  }
+
+  /**
+   * @description
+   * @public
+   * @async
+   * @param {T} context 
+   * @returns {unknown} 
+   */
+  public override async executeAsync(context: T): Promise<T> {
+    return super.executeAsync(context);
+  }
+
+  /**
+   * @description
+   * @public
+   * @param {(context: T) => void} onComplete 
+   */
+  public override onComplete(onComplete: (context: T) => void): void {
+    super.onComplete(onComplete);
+  }
+
+  /**
+   * @description
+   * @public
+   * @param {U} middleware 
+   * @returns {this} 
+   */
+  public override use(middleware: U): this {
+    return super.use(middleware);
+  }
+}

src/lib/context-middleware.class.ts

@@ -0,0 +1,16 @@
+// Abstract.
+import { ContextMiddlewareBase } from './context-middleware-base.abstract';
+// Type.
+import { ContextMiddlewareFunction } from '../type';
+/**
+ * @description
+ * @export
+ * @class ContextMiddleware
+ * @template [T=any] 
+ * @template {Function} [U=ContextMiddlewareFunction<T>] 
+ * @extends {ContextMiddlewareBase<T, U>}
+ */
+export class ContextMiddleware<
+  T = any,
+  U extends Function = ContextMiddlewareFunction<T>
+> extends ContextMiddlewareBase<T, U> {}

src/lib/index.ts

@@ -1 +1,7 @@
-export { Middleware } from './middleware.class';
+// Class.
+export { Middleware } from './middleware.class';
+export { ContextMiddleware } from './context-middleware.class';
+// Abstract.
+export { ContextMiddlewareBase } from './context-middleware-base.abstract';
+export { MiddlewareBase } from './middleware-base.abstract';
+export { MiddlewareCore } from './middleware-core.abstract';

src/lib/middleware-base.abstract.ts

@@ -0,0 +1,115 @@
+// Abstract.
+import { MiddlewareCore } from './middleware-core.abstract';
+// Type.
+import { MiddlewareFunction } from '../type';
+/**
+ * @description The base abstraction for arguments middleware.
+ * @export
+ * @abstract
+ * @class MiddlewareBase
+ * @typedef {MiddlewareBase}
+ * @template [T=any] 
+ * @template [O=T[]] 
+ * @template {Function} [U=MiddlewareFunction<T>] 
+ * @extends {MiddlewareCore<T, O, U>}
+ */
+export abstract class MiddlewareBase<
+  T = any,
+  O = T[],
+  U extends Function = MiddlewareFunction<T>
+> extends MiddlewareCore<T, O, U> {
+  /**
+   * @description
+   * @type {number}
+   */
+  #index = 0;
+
+  /**
+   * @description
+   * @type {U[]}
+   */
+  #middleware: U[];
+
+  /**
+   * @description
+   * @type {() => void}
+   */
+  #onComplete: (args: O) => void = () => {};
+
+  /**
+   * Creates an instance of `MiddlewareBase`.
+   * @constructor
+   * @param {...U[]} middleware 
+   */
+  constructor(...middleware: U[]) {
+    super();
+    this.#middleware = middleware;
+  }
+
+  /**
+   * @description
+   * @public
+   * @param {...T[]} args 
+   * @returns {this} 
+   */
+  public execute(...args: T[]) {
+    return this.#index = 0,
+      this.#next(...args),
+      this;
+  }
+
+  /**
+   * @description
+   * @public
+   * @async
+   * @param {...T[]} args 
+   * @returns {unknown} 
+   */
+  public override async executeAsync(...args: T[]): Promise<O> {
+    return this.#index = 0,
+      await this.#nextAsync(...args),
+      this.onComplete(() => args as O),
+      args as O;
+  }
+
+  /**
+   * @description
+   * @public
+   * @param {(args: T[]) => void} onComplete 
+   */
+  public onComplete(onComplete: (args: O) => void): void {
+    this.#onComplete = onComplete;
+  }
+
+  /**
+   * @description
+   * @public
+   * @param {U} middleware 
+   * @returns {this} 
+   */
+  public use(middleware: U): this {
+    return this.#middleware.push(middleware), this;
+  }
+
+  /**
+   * @description
+   * @param {...T[]} args 
+   */
+  #next(...args: T[]): void {
+    this.#index < this.#middleware.length
+      ? this.#middleware[this.#index++](args, () => this.#next(...args))
+      : this.#onComplete(args as O);
+  }
+
+  /**
+   * @description
+   * @async
+   * @param {...T[]} args  
+   * @returns {*} 
+   */
+  async #nextAsync(...args: T[]): Promise<void> {
+    this.#index < this.#middleware.length
+      ? await this.#middleware[this.#index++](args, () => this.#nextAsync(...args))
+      : this.#onComplete(args as O);
+  }
+}

src/lib/middleware-core.abstract.ts

@@ -0,0 +1,39 @@
+// Interface.
+import { MiddlewareShape } from "../interface/middleware.shape";
+/**
+ * @description
+ * @export
+ * @abstract
+ * @class MiddlewareCore
+ * @typedef {MiddlewareCore}
+ * @template [Input=any] 
+ * @template [Output=void] 
+ * @template [Middleware=any] 
+ * @implements {MiddlewareShape<Input, Output, Middleware>}
+ */
+export abstract class MiddlewareCore<
+  Input = any,
+  Output = void,
+  Middleware = any
+> implements MiddlewareShape<Input, Output, Middleware> {
+  /**
+   * @description
+   * @public
+   * @abstract
+   * @param {...Input[]} args 
+   */
+  public abstract execute(context: Input): this;
+  public abstract execute(...args: Input[]): this;
+
+  /**
+   * @description
+   * @public
+   * @abstract
+   * @param {Middleware} middleware 
+   * @returns {this} 
+   */
+  public abstract use(middleware: Middleware): this;
+
+  public abstract executeAsync(context: Input): Promise<Output>;
+  public abstract executeAsync(...args: Input[]): Promise<Output>;
+}