@nhtio/middleware 0.1.0-master-d3ec5be7

package/LICENSE.md

@@ -0,0 +1,9 @@
+# MIT License
+
+Copyright (c) 2025 New Horizon Technology LTD (nht.io)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @nhtio/middleware
+
+A cross-environment (browser/node) implementation of the chain of responsibility design pattern based on [@poppinss/middleware](https://github.com/poppinss/middleware)
+
+For more information, see the [official documentation](https://middleware.nht.io)

package/index.cjs

@@ -0,0 +1,2 @@
+"use strict";var H=t=>{throw TypeError(t)};var M=(t,r,e)=>r.has(t)||H("Cannot "+e);var n=(t,r,e)=>(M(t,r,"read from private field"),e?e.call(t):r.get(t)),a=(t,r,e)=>r.has(t)?H("Cannot add the same private member more than once"):r instanceof WeakSet?r.add(t):r.set(t,e),s=(t,r,e,i)=>(M(t,r,"write to private field"),i?i.call(t,e):r.set(t,e),e),f=(t,r,e)=>(M(t,r,"access private method"),e);var z=(t,r,e,i)=>({set _(l){s(t,r,l,e)},get _(){return n(t,r,i)}});Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});function y(t,r){function e(){if(!e.called)return e.called=!0,r(t)}return e.called=!1,e}const C=()=>Promise.resolve();var u,v,w,m,c,h,k,g;class A{constructor(r){a(this,h);a(this,u);a(this,v,0);a(this,w);a(this,m,C);a(this,c);s(this,u,r)}finalHandler(r){return s(this,m,r),this}errorHandler(r){return s(this,c,r),this}async run(r){return s(this,w,r),n(this,c)?f(this,h,g).call(this,this):f(this,h,k).call(this,this)}}u=new WeakMap,v=new WeakMap,w=new WeakMap,m=new WeakMap,c=new WeakMap,h=new WeakSet,k=function(r){var i,l;const e=n(r,u)[z(r,v)._++];return e?n(l=r,w).call(l,e,y(r,f(r,h,k))):n(i=r,m).call(i)},g=function(r){var i,l;const e=n(r,u)[z(r,v)._++];return e?n(l=r,w).call(l,e,y(r,f(r,h,g))).catch(n(r,c)):n(i=r,m).call(i).catch(n(r,c))};var o,E,d;class b{constructor(){a(this,o,new Set);a(this,E);a(this,d,!1)}all(){return n(this,o)}has(r){return n(this,o).has(r)}add(r){if(n(this,d))throw new Error("Middleware stack is frozen. Cannot add new middleware");return n(this,o).add(r),this}remove(r){if(n(this,d))throw new Error("Middleware stack is frozen. Cannot remove middleware");return n(this,o).delete(r)}clear(){if(n(this,d))throw new Error("Middleware stack is frozen. Cannot clear middleware");n(this,o).clear()}merge(r){if(n(this,d))throw new Error("Middleware stack is frozen. Cannot merge middleware");r.all().forEach(e=>{this.add(e)})}freeze(){n(this,d)||(s(this,d,!0),s(this,E,[...this.all()]))}runner(){return this.freeze(),new A(n(this,E))}}o=new WeakMap,E=new WeakMap,d=new WeakMap;const x="0.1.0-master-d3ec5be7";exports.Middleware=b;exports.Runner=A;exports.version=x;
+//# sourceMappingURL=index.cjs.map

package/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/private/runner.ts","../src/private/middleware.ts","../src/index.ts"],"sourcesContent":["import type { ErrorHandler, Executor, FinalHandler } from './types'\n\n/**\n * Ensures a function is executed only once by maintaining a called state.\n *\n * This utility function is tightly coupled with the Runner class and is used\n * to ensure the `next` callback is not invoked multiple times in the middleware chain.\n *\n * @param scope - The Runner instance scope\n * @param callback - The function to execute only once\n * @returns A wrapped function that tracks its execution state\n * @internal\n */\nfunction once(scope: Runner<any>, callback: (scope: Runner<any>) => Promise<void> | void) {\n  function next(): Promise<void> | void {\n    if (next.called) {\n      return\n    }\n\n    next.called = true\n    return callback(scope)\n  }\n  next.called = false\n\n  return next\n}\n\n/**\n * Default final handler that resolves immediately when the middleware chain completes.\n *\n * This handler is used when no custom final handler is specified via `finalHandler()`.\n *\n * @internal\n */\nconst DEFAULT_FINAL_HANDLER = () => Promise.resolve()\n\n/**\n * Runner executes an array of middleware functions in sequence.\n *\n * The middleware pipeline advances only when the current function calls `next`,\n * implementing the chain of responsibility pattern. You control how to execute\n * the underlying middleware functions by providing an executor function.\n *\n * @template MiddlewareFn - The type of the middleware function/handler\n *\n * @example\n * ```ts\n * const context = { stack: [] }\n * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>\n *\n * const middleware = new Middleware<MiddlewareFn>()\n * middleware.add((ctx, next) => {\n *   ctx.stack.push('fn1')\n *   await next()\n * })\n *\n * await middleware\n *   .runner()\n *   .finalHandler(() => {\n *     context.stack.push('final handler')\n *   })\n *   .run((fn, next) => fn(context, next))\n * ```\n */\nexport class Runner<MiddlewareFn extends any> {\n  /**\n   * The array of middleware handlers to execute in sequence.\n   */\n  #middleware: MiddlewareFn[]\n\n  /**\n   * The current index position in the middleware pipeline.\n   */\n  #currentIndex = 0\n\n  /**\n   * The executor function responsible for invoking each middleware handler.\n   */\n  #executor!: Executor<MiddlewareFn>\n\n  /**\n   * The final handler to execute when the middleware chain completes successfully.\n   */\n  #finalHandler: FinalHandler = DEFAULT_FINAL_HANDLER\n\n  /**\n   * Optional error handler to catch and handle exceptions in the middleware pipeline.\n   */\n  #errorHandler?: ErrorHandler\n\n  constructor(middleware: MiddlewareFn[]) {\n    this.#middleware = middleware\n  }\n\n  /**\n   * Invokes middleware handlers one at a time.\n   *\n   * Middleware functions are executed recursively until `next` is called.\n   * If a middleware doesn't call `next`, the chain will finish automatically\n   * without executing remaining handlers.\n   *\n   * @param self - The Runner instance scope\n   * @returns A Promise that resolves when the middleware chain completes\n   * @internal\n   */\n  #invoke(self: Runner<MiddlewareFn>): Promise<void> | void {\n    const middleware = self.#middleware[self.#currentIndex++]\n\n    /**\n     * Empty stack\n     */\n    if (!middleware) {\n      return self.#finalHandler()\n    }\n\n    return self.#executor(middleware, once(self, self.#invoke))\n  }\n\n  /**\n   * Invokes middleware handlers with error handling.\n   *\n   * Similar to `#invoke`, but catches exceptions and passes them to the error handler.\n   * When an exception is raised, the middleware downstream logic will not run unless\n   * the error handler allows the chain to continue.\n   *\n   * @param self - The Runner instance scope\n   * @returns A Promise that resolves when the middleware chain completes\n   * @internal\n   */\n  #invokeWithErrorManagement(self: Runner<MiddlewareFn>): Promise<void> | void {\n    const middleware = self.#middleware[self.#currentIndex++]\n\n    /**\n     * Empty stack\n     */\n    if (!middleware) {\n      return self.#finalHandler().catch(self.#errorHandler)\n    }\n\n    return self\n      .#executor(middleware, once(self, self.#invokeWithErrorManagement))\n      .catch(self.#errorHandler)\n  }\n\n  /**\n   * Sets a custom final handler to execute when the middleware chain completes successfully.\n   *\n   * The final handler is called when the entire middleware pipeline reaches the end\n   * by calling `next` through all handlers. This makes it easier to execute custom\n   * logic that is not part of the chain but must run when the chain ends.\n   *\n   * @param finalHandler - The function to execute when the chain completes\n   * @returns The Runner instance for method chaining\n   *\n   * @example\n   * ```ts\n   * await middleware\n   *   .runner()\n   *   .finalHandler(() => {\n   *     console.log('All middleware completed')\n   *   })\n   *   .run((fn, next) => fn(context, next))\n   * ```\n   */\n  finalHandler(finalHandler: FinalHandler): this {\n    this.#finalHandler = finalHandler\n    return this\n  }\n\n  /**\n   * Sets a custom error handler to catch exceptions in the middleware pipeline.\n   *\n   * By default, exceptions raised in the middleware pipeline bubble up to the `run`\n   * method and can be captured using a try/catch block. When an exception is raised,\n   * the middleware downstream logic will not run.\n   *\n   * Defining an error handler changes this behavior:\n   * - The `run` method will not throw exceptions\n   * - Errors are caught and passed to the error handler\n   * - Middleware upstream logic (after `next`) can still execute\n   *\n   * @param errorHandler - The function to handle errors\n   * @returns The Runner instance for method chaining\n   *\n   * @example\n   * ```ts\n   * await middleware\n   *   .runner()\n   *   .errorHandler((error) => {\n   *     console.error('Middleware error:', error)\n   *   })\n   *   .run((fn, next) => fn(context, next))\n   * ```\n   */\n  errorHandler(errorHandler: ErrorHandler): this {\n    this.#errorHandler = errorHandler\n    return this\n  }\n\n  /**\n   * Executes the middleware pipeline using the provided executor function.\n   *\n   * The executor function is responsible for invoking each middleware handler with\n   * the appropriate context and the `next` callback. Since you control the executor,\n   * you can pass any data you want to the middleware.\n   *\n   * @param cb - The executor function that invokes each middleware handler\n   * @returns A Promise that resolves when the middleware pipeline completes\n   *\n   * @example\n   * ```ts\n   * const context = { user: null }\n   * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>\n   *\n   * const middleware = new Middleware<MiddlewareFn>()\n   * middleware.add(async (ctx, next) => {\n   *   ctx.user = await authenticate()\n   *   await next()\n   * })\n   *\n   * await middleware\n   *   .runner()\n   *   .run((fn, next) => fn(context, next))\n   * ```\n   */\n  async run(cb: Executor<MiddlewareFn>): Promise<void> {\n    this.#executor = cb\n\n    if (this.#errorHandler) {\n      return this.#invokeWithErrorManagement(this)\n    }\n\n    return this.#invoke(this)\n  }\n}\n","import { Runner } from './runner'\n\n/**\n * The Middleware class implements the chain of responsibility design pattern\n * and allows executing handlers in series.\n *\n * The middleware handlers can be represented as any value you wish, such as:\n * - A function: `middleware.add(function () { console.log('called') })`\n * - An object with a `handle` method: `middleware.add({ name: 'auth', handle: authenticate })`\n *\n * @template MiddlewareFn - The type of the middleware function/handler\n *\n * @example\n * ```ts\n * const context = {}\n * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>\n *\n * const middleware = new Middleware<MiddlewareFn>()\n *\n * middleware.add((ctx, next) => {\n *   console.log('executing middleware')\n *   await next()\n * })\n *\n * await middleware\n *   .runner()\n *   .run((fn, next) => fn(context, next))\n * ```\n */\nexport class Middleware<MiddlewareFn extends any> {\n  #middleware: Set<MiddlewareFn> = new Set()\n  #middlewareArray?: MiddlewareFn[]\n  #isFrozen: boolean = false\n\n  /**\n   * Returns all registered middleware handlers.\n   *\n   * @returns A Set containing all registered middleware handlers\n   */\n  all() {\n    return this.#middleware\n  }\n\n  /**\n   * Checks if a specific handler has already been registered as middleware.\n   *\n   * @param handler - The middleware handler to check for\n   * @returns `true` if the handler is registered, `false` otherwise\n   */\n  has(handler: MiddlewareFn): boolean {\n    return this.#middleware.has(handler)\n  }\n\n  /**\n   * Registers a new middleware handler to the pipeline.\n   *\n   * Adding the same middleware handler multiple times will result in a no-op,\n   * as handlers are stored in a Set to prevent duplicates.\n   *\n   * @param handler - The middleware handler to register\n   * @returns The Middleware instance for method chaining\n   * @throws {Error} If the middleware stack is frozen\n   */\n  add(handler: MiddlewareFn): this {\n    if (this.#isFrozen) {\n      throw new Error('Middleware stack is frozen. Cannot add new middleware')\n    }\n\n    this.#middleware.add(handler)\n    return this\n  }\n\n  /**\n   * Removes a specific middleware handler from the pipeline.\n   *\n   * @param handler - The middleware handler to remove\n   * @returns `true` if the handler was removed, `false` if it was not found\n   * @throws {Error} If the middleware stack is frozen\n   */\n  remove(handler: MiddlewareFn): boolean {\n    if (this.#isFrozen) {\n      throw new Error('Middleware stack is frozen. Cannot remove middleware')\n    }\n\n    return this.#middleware.delete(handler)\n  }\n\n  /**\n   * Removes all registered middleware handlers from the pipeline.\n   *\n   * @throws {Error} If the middleware stack is frozen\n   */\n  clear(): void {\n    if (this.#isFrozen) {\n      throw new Error('Middleware stack is frozen. Cannot clear middleware')\n    }\n\n    this.#middleware.clear()\n  }\n\n  /**\n   * Merges middleware handlers from another Middleware instance.\n   *\n   * The middleware from the source instance are appended to the current instance.\n   *\n   * @param hooks - The source Middleware instance to merge from\n   * @throws {Error} If the middleware stack is frozen\n   */\n  merge(hooks: Middleware<MiddlewareFn>) {\n    if (this.#isFrozen) {\n      throw new Error('Middleware stack is frozen. Cannot merge middleware')\n    }\n\n    hooks.all().forEach((handler) => {\n      this.add(handler)\n    })\n  }\n\n  /**\n   * Freezes the middleware stack to prevent further modifications.\n   *\n   * Once frozen, the middleware array is cached and no new handlers can be added,\n   * removed, or modified. This method is automatically called when creating a runner.\n   */\n  freeze() {\n    if (this.#isFrozen) {\n      return\n    }\n\n    this.#isFrozen = true\n    this.#middlewareArray = [...this.all()]\n  }\n\n  /**\n   * Creates and returns a Runner instance to execute the middleware pipeline.\n   *\n   * This method automatically freezes the middleware stack to prevent modifications\n   * during execution.\n   *\n   * @returns A new Runner instance configured with the current middleware handlers\n   */\n  runner(): Runner<MiddlewareFn> {\n    this.freeze()\n    return new Runner(this.#middlewareArray!)\n  }\n}\n","/**\n * @module @nhtio/middleware\n *\n * A cross-environment (browser/node) implementation of the chain of responsibility design pattern,\n * also known as the middleware pipeline. This package is based on\n * [@poppinss/middleware](https://github.com/poppinss/middleware) and provides a zero-dependency\n * implementation for executing handlers in series.\n *\n * @example\n * ```ts\n * import { Middleware } from '@nhtio/middleware'\n * import type { NextFn } from '@nhtio/middleware'\n *\n * const context = {}\n * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>\n *\n * const middleware = new Middleware<MiddlewareFn>()\n *\n * middleware.add((ctx, next) => {\n *   console.log('executing fn1')\n *   await next()\n * })\n *\n * await middleware\n *   .runner()\n *   .run((fn, next) => fn(context, next))\n * ```\n */\n\n/**\n * The current version of the package.\n *\n * This constant is replaced during the build process with the actual version from package.json.\n */\nexport const version = __VERSION__\n\nexport { Middleware } from './private/middleware'\nexport { Runner } from './private/runner'\nexport * from './private/types'\n"],"names":["once","scope","callback","next","DEFAULT_FINAL_HANDLER","Runner","middleware","__privateAdd","_Runner_instances","_middleware","_currentIndex","_executor","_finalHandler","_errorHandler","__privateSet","finalHandler","errorHandler","cb","__privateGet","__privateMethod","invokeWithErrorManagement_fn","invoke_fn","self","__privateWrapper","_b","_a","Middleware","_middlewareArray","_isFrozen","handler","hooks","version"],"mappings":"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"}

package/index.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @module @nhtio/middleware
+ *
+ * A cross-environment (browser/node) implementation of the chain of responsibility design pattern,
+ * also known as the middleware pipeline. This package is based on
+ * [@poppinss/middleware](https://github.com/poppinss/middleware) and provides a zero-dependency
+ * implementation for executing handlers in series.
+ *
+ * @example
+ * ```ts
+ * import { Middleware } from '@nhtio/middleware'
+ * import type { NextFn } from '@nhtio/middleware'
+ *
+ * const context = {}
+ * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>
+ *
+ * const middleware = new Middleware<MiddlewareFn>()
+ *
+ * middleware.add((ctx, next) => {
+ *   console.log('executing fn1')
+ *   await next()
+ * })
+ *
+ * await middleware
+ *   .runner()
+ *   .run((fn, next) => fn(context, next))
+ * ```
+ */
+/**
+ * The current version of the package.
+ *
+ * This constant is replaced during the build process with the actual version from package.json.
+ */
+export declare const version: string;
+export { Middleware } from './private/middleware';
+export { Runner } from './private/runner';
+export * from './private/types';

package/index.mjs

@@ -0,0 +1,264 @@
+var x = (t) => {
+  throw TypeError(t);
+};
+var k = (t, r, e) => r.has(t) || x("Cannot " + e);
+var n = (t, r, e) => (k(t, r, "read from private field"), e ? e.call(t) : r.get(t)), a = (t, r, e) => r.has(t) ? x("Cannot add the same private member more than once") : r instanceof WeakSet ? r.add(t) : r.set(t, e), s = (t, r, e, i) => (k(t, r, "write to private field"), i ? i.call(t, e) : r.set(t, e), e), f = (t, r, e) => (k(t, r, "access private method"), e);
+var v = (t, r, e, i) => ({
+  set _(c) {
+    s(t, r, c, e);
+  },
+  get _() {
+    return n(t, r, i);
+  }
+});
+function A(t, r) {
+  function e() {
+    if (!e.called)
+      return e.called = !0, r(t);
+  }
+  return e.called = !1, e;
+}
+const C = () => Promise.resolve();
+var u, E, w, m, l, h, M, H;
+class g {
+  constructor(r) {
+    a(this, h);
+    /**
+     * The array of middleware handlers to execute in sequence.
+     */
+    a(this, u);
+    /**
+     * The current index position in the middleware pipeline.
+     */
+    a(this, E, 0);
+    /**
+     * The executor function responsible for invoking each middleware handler.
+     */
+    a(this, w);
+    /**
+     * The final handler to execute when the middleware chain completes successfully.
+     */
+    a(this, m, C);
+    /**
+     * Optional error handler to catch and handle exceptions in the middleware pipeline.
+     */
+    a(this, l);
+    s(this, u, r);
+  }
+  /**
+   * Sets a custom final handler to execute when the middleware chain completes successfully.
+   *
+   * The final handler is called when the entire middleware pipeline reaches the end
+   * by calling `next` through all handlers. This makes it easier to execute custom
+   * logic that is not part of the chain but must run when the chain ends.
+   *
+   * @param finalHandler - The function to execute when the chain completes
+   * @returns The Runner instance for method chaining
+   *
+   * @example
+   * ```ts
+   * await middleware
+   *   .runner()
+   *   .finalHandler(() => {
+   *     console.log('All middleware completed')
+   *   })
+   *   .run((fn, next) => fn(context, next))
+   * ```
+   */
+  finalHandler(r) {
+    return s(this, m, r), this;
+  }
+  /**
+   * Sets a custom error handler to catch exceptions in the middleware pipeline.
+   *
+   * By default, exceptions raised in the middleware pipeline bubble up to the `run`
+   * method and can be captured using a try/catch block. When an exception is raised,
+   * the middleware downstream logic will not run.
+   *
+   * Defining an error handler changes this behavior:
+   * - The `run` method will not throw exceptions
+   * - Errors are caught and passed to the error handler
+   * - Middleware upstream logic (after `next`) can still execute
+   *
+   * @param errorHandler - The function to handle errors
+   * @returns The Runner instance for method chaining
+   *
+   * @example
+   * ```ts
+   * await middleware
+   *   .runner()
+   *   .errorHandler((error) => {
+   *     console.error('Middleware error:', error)
+   *   })
+   *   .run((fn, next) => fn(context, next))
+   * ```
+   */
+  errorHandler(r) {
+    return s(this, l, r), this;
+  }
+  /**
+   * Executes the middleware pipeline using the provided executor function.
+   *
+   * The executor function is responsible for invoking each middleware handler with
+   * the appropriate context and the `next` callback. Since you control the executor,
+   * you can pass any data you want to the middleware.
+   *
+   * @param cb - The executor function that invokes each middleware handler
+   * @returns A Promise that resolves when the middleware pipeline completes
+   *
+   * @example
+   * ```ts
+   * const context = { user: null }
+   * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>
+   *
+   * const middleware = new Middleware<MiddlewareFn>()
+   * middleware.add(async (ctx, next) => {
+   *   ctx.user = await authenticate()
+   *   await next()
+   * })
+   *
+   * await middleware
+   *   .runner()
+   *   .run((fn, next) => fn(context, next))
+   * ```
+   */
+  async run(r) {
+    return s(this, w, r), n(this, l) ? f(this, h, H).call(this, this) : f(this, h, M).call(this, this);
+  }
+}
+u = new WeakMap(), E = new WeakMap(), w = new WeakMap(), m = new WeakMap(), l = new WeakMap(), h = new WeakSet(), /**
+ * Invokes middleware handlers one at a time.
+ *
+ * Middleware functions are executed recursively until `next` is called.
+ * If a middleware doesn't call `next`, the chain will finish automatically
+ * without executing remaining handlers.
+ *
+ * @param self - The Runner instance scope
+ * @returns A Promise that resolves when the middleware chain completes
+ * @internal
+ */
+M = function(r) {
+  var i, c;
+  const e = n(r, u)[v(r, E)._++];
+  return e ? n(c = r, w).call(c, e, A(r, f(r, h, M))) : n(i = r, m).call(i);
+}, /**
+ * Invokes middleware handlers with error handling.
+ *
+ * Similar to `#invoke`, but catches exceptions and passes them to the error handler.
+ * When an exception is raised, the middleware downstream logic will not run unless
+ * the error handler allows the chain to continue.
+ *
+ * @param self - The Runner instance scope
+ * @returns A Promise that resolves when the middleware chain completes
+ * @internal
+ */
+H = function(r) {
+  var i, c;
+  const e = n(r, u)[v(r, E)._++];
+  return e ? n(c = r, w).call(c, e, A(r, f(r, h, H))).catch(n(r, l)) : n(i = r, m).call(i).catch(n(r, l));
+};
+var o, z, d;
+class L {
+  constructor() {
+    a(this, o, /* @__PURE__ */ new Set());
+    a(this, z);
+    a(this, d, !1);
+  }
+  /**
+   * Returns all registered middleware handlers.
+   *
+   * @returns A Set containing all registered middleware handlers
+   */
+  all() {
+    return n(this, o);
+  }
+  /**
+   * Checks if a specific handler has already been registered as middleware.
+   *
+   * @param handler - The middleware handler to check for
+   * @returns `true` if the handler is registered, `false` otherwise
+   */
+  has(r) {
+    return n(this, o).has(r);
+  }
+  /**
+   * Registers a new middleware handler to the pipeline.
+   *
+   * Adding the same middleware handler multiple times will result in a no-op,
+   * as handlers are stored in a Set to prevent duplicates.
+   *
+   * @param handler - The middleware handler to register
+   * @returns The Middleware instance for method chaining
+   * @throws {Error} If the middleware stack is frozen
+   */
+  add(r) {
+    if (n(this, d))
+      throw new Error("Middleware stack is frozen. Cannot add new middleware");
+    return n(this, o).add(r), this;
+  }
+  /**
+   * Removes a specific middleware handler from the pipeline.
+   *
+   * @param handler - The middleware handler to remove
+   * @returns `true` if the handler was removed, `false` if it was not found
+   * @throws {Error} If the middleware stack is frozen
+   */
+  remove(r) {
+    if (n(this, d))
+      throw new Error("Middleware stack is frozen. Cannot remove middleware");
+    return n(this, o).delete(r);
+  }
+  /**
+   * Removes all registered middleware handlers from the pipeline.
+   *
+   * @throws {Error} If the middleware stack is frozen
+   */
+  clear() {
+    if (n(this, d))
+      throw new Error("Middleware stack is frozen. Cannot clear middleware");
+    n(this, o).clear();
+  }
+  /**
+   * Merges middleware handlers from another Middleware instance.
+   *
+   * The middleware from the source instance are appended to the current instance.
+   *
+   * @param hooks - The source Middleware instance to merge from
+   * @throws {Error} If the middleware stack is frozen
+   */
+  merge(r) {
+    if (n(this, d))
+      throw new Error("Middleware stack is frozen. Cannot merge middleware");
+    r.all().forEach((e) => {
+      this.add(e);
+    });
+  }
+  /**
+   * Freezes the middleware stack to prevent further modifications.
+   *
+   * Once frozen, the middleware array is cached and no new handlers can be added,
+   * removed, or modified. This method is automatically called when creating a runner.
+   */
+  freeze() {
+    n(this, d) || (s(this, d, !0), s(this, z, [...this.all()]));
+  }
+  /**
+   * Creates and returns a Runner instance to execute the middleware pipeline.
+   *
+   * This method automatically freezes the middleware stack to prevent modifications
+   * during execution.
+   *
+   * @returns A new Runner instance configured with the current middleware handlers
+   */
+  runner() {
+    return this.freeze(), new g(n(this, z));
+  }
+}
+o = new WeakMap(), z = new WeakMap(), d = new WeakMap();
+const y = "0.1.0-master-d3ec5be7";
+export {
+  L as Middleware,
+  g as Runner,
+  y as version
+};
+//# sourceMappingURL=index.mjs.map

package/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","sources":["../src/private/runner.ts","../src/private/middleware.ts","../src/index.ts"],"sourcesContent":["import type { ErrorHandler, Executor, FinalHandler } from './types'\n\n/**\n * Ensures a function is executed only once by maintaining a called state.\n *\n * This utility function is tightly coupled with the Runner class and is used\n * to ensure the `next` callback is not invoked multiple times in the middleware chain.\n *\n * @param scope - The Runner instance scope\n * @param callback - The function to execute only once\n * @returns A wrapped function that tracks its execution state\n * @internal\n */\nfunction once(scope: Runner<any>, callback: (scope: Runner<any>) => Promise<void> | void) {\n  function next(): Promise<void> | void {\n    if (next.called) {\n      return\n    }\n\n    next.called = true\n    return callback(scope)\n  }\n  next.called = false\n\n  return next\n}\n\n/**\n * Default final handler that resolves immediately when the middleware chain completes.\n *\n * This handler is used when no custom final handler is specified via `finalHandler()`.\n *\n * @internal\n */\nconst DEFAULT_FINAL_HANDLER = () => Promise.resolve()\n\n/**\n * Runner executes an array of middleware functions in sequence.\n *\n * The middleware pipeline advances only when the current function calls `next`,\n * implementing the chain of responsibility pattern. You control how to execute\n * the underlying middleware functions by providing an executor function.\n *\n * @template MiddlewareFn - The type of the middleware function/handler\n *\n * @example\n * ```ts\n * const context = { stack: [] }\n * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>\n *\n * const middleware = new Middleware<MiddlewareFn>()\n * middleware.add((ctx, next) => {\n *   ctx.stack.push('fn1')\n *   await next()\n * })\n *\n * await middleware\n *   .runner()\n *   .finalHandler(() => {\n *     context.stack.push('final handler')\n *   })\n *   .run((fn, next) => fn(context, next))\n * ```\n */\nexport class Runner<MiddlewareFn extends any> {\n  /**\n   * The array of middleware handlers to execute in sequence.\n   */\n  #middleware: MiddlewareFn[]\n\n  /**\n   * The current index position in the middleware pipeline.\n   */\n  #currentIndex = 0\n\n  /**\n   * The executor function responsible for invoking each middleware handler.\n   */\n  #executor!: Executor<MiddlewareFn>\n\n  /**\n   * The final handler to execute when the middleware chain completes successfully.\n   */\n  #finalHandler: FinalHandler = DEFAULT_FINAL_HANDLER\n\n  /**\n   * Optional error handler to catch and handle exceptions in the middleware pipeline.\n   */\n  #errorHandler?: ErrorHandler\n\n  constructor(middleware: MiddlewareFn[]) {\n    this.#middleware = middleware\n  }\n\n  /**\n   * Invokes middleware handlers one at a time.\n   *\n   * Middleware functions are executed recursively until `next` is called.\n   * If a middleware doesn't call `next`, the chain will finish automatically\n   * without executing remaining handlers.\n   *\n   * @param self - The Runner instance scope\n   * @returns A Promise that resolves when the middleware chain completes\n   * @internal\n   */\n  #invoke(self: Runner<MiddlewareFn>): Promise<void> | void {\n    const middleware = self.#middleware[self.#currentIndex++]\n\n    /**\n     * Empty stack\n     */\n    if (!middleware) {\n      return self.#finalHandler()\n    }\n\n    return self.#executor(middleware, once(self, self.#invoke))\n  }\n\n  /**\n   * Invokes middleware handlers with error handling.\n   *\n   * Similar to `#invoke`, but catches exceptions and passes them to the error handler.\n   * When an exception is raised, the middleware downstream logic will not run unless\n   * the error handler allows the chain to continue.\n   *\n   * @param self - The Runner instance scope\n   * @returns A Promise that resolves when the middleware chain completes\n   * @internal\n   */\n  #invokeWithErrorManagement(self: Runner<MiddlewareFn>): Promise<void> | void {\n    const middleware = self.#middleware[self.#currentIndex++]\n\n    /**\n     * Empty stack\n     */\n    if (!middleware) {\n      return self.#finalHandler().catch(self.#errorHandler)\n    }\n\n    return self\n      .#executor(middleware, once(self, self.#invokeWithErrorManagement))\n      .catch(self.#errorHandler)\n  }\n\n  /**\n   * Sets a custom final handler to execute when the middleware chain completes successfully.\n   *\n   * The final handler is called when the entire middleware pipeline reaches the end\n   * by calling `next` through all handlers. This makes it easier to execute custom\n   * logic that is not part of the chain but must run when the chain ends.\n   *\n   * @param finalHandler - The function to execute when the chain completes\n   * @returns The Runner instance for method chaining\n   *\n   * @example\n   * ```ts\n   * await middleware\n   *   .runner()\n   *   .finalHandler(() => {\n   *     console.log('All middleware completed')\n   *   })\n   *   .run((fn, next) => fn(context, next))\n   * ```\n   */\n  finalHandler(finalHandler: FinalHandler): this {\n    this.#finalHandler = finalHandler\n    return this\n  }\n\n  /**\n   * Sets a custom error handler to catch exceptions in the middleware pipeline.\n   *\n   * By default, exceptions raised in the middleware pipeline bubble up to the `run`\n   * method and can be captured using a try/catch block. When an exception is raised,\n   * the middleware downstream logic will not run.\n   *\n   * Defining an error handler changes this behavior:\n   * - The `run` method will not throw exceptions\n   * - Errors are caught and passed to the error handler\n   * - Middleware upstream logic (after `next`) can still execute\n   *\n   * @param errorHandler - The function to handle errors\n   * @returns The Runner instance for method chaining\n   *\n   * @example\n   * ```ts\n   * await middleware\n   *   .runner()\n   *   .errorHandler((error) => {\n   *     console.error('Middleware error:', error)\n   *   })\n   *   .run((fn, next) => fn(context, next))\n   * ```\n   */\n  errorHandler(errorHandler: ErrorHandler): this {\n    this.#errorHandler = errorHandler\n    return this\n  }\n\n  /**\n   * Executes the middleware pipeline using the provided executor function.\n   *\n   * The executor function is responsible for invoking each middleware handler with\n   * the appropriate context and the `next` callback. Since you control the executor,\n   * you can pass any data you want to the middleware.\n   *\n   * @param cb - The executor function that invokes each middleware handler\n   * @returns A Promise that resolves when the middleware pipeline completes\n   *\n   * @example\n   * ```ts\n   * const context = { user: null }\n   * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>\n   *\n   * const middleware = new Middleware<MiddlewareFn>()\n   * middleware.add(async (ctx, next) => {\n   *   ctx.user = await authenticate()\n   *   await next()\n   * })\n   *\n   * await middleware\n   *   .runner()\n   *   .run((fn, next) => fn(context, next))\n   * ```\n   */\n  async run(cb: Executor<MiddlewareFn>): Promise<void> {\n    this.#executor = cb\n\n    if (this.#errorHandler) {\n      return this.#invokeWithErrorManagement(this)\n    }\n\n    return this.#invoke(this)\n  }\n}\n","import { Runner } from './runner'\n\n/**\n * The Middleware class implements the chain of responsibility design pattern\n * and allows executing handlers in series.\n *\n * The middleware handlers can be represented as any value you wish, such as:\n * - A function: `middleware.add(function () { console.log('called') })`\n * - An object with a `handle` method: `middleware.add({ name: 'auth', handle: authenticate })`\n *\n * @template MiddlewareFn - The type of the middleware function/handler\n *\n * @example\n * ```ts\n * const context = {}\n * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>\n *\n * const middleware = new Middleware<MiddlewareFn>()\n *\n * middleware.add((ctx, next) => {\n *   console.log('executing middleware')\n *   await next()\n * })\n *\n * await middleware\n *   .runner()\n *   .run((fn, next) => fn(context, next))\n * ```\n */\nexport class Middleware<MiddlewareFn extends any> {\n  #middleware: Set<MiddlewareFn> = new Set()\n  #middlewareArray?: MiddlewareFn[]\n  #isFrozen: boolean = false\n\n  /**\n   * Returns all registered middleware handlers.\n   *\n   * @returns A Set containing all registered middleware handlers\n   */\n  all() {\n    return this.#middleware\n  }\n\n  /**\n   * Checks if a specific handler has already been registered as middleware.\n   *\n   * @param handler - The middleware handler to check for\n   * @returns `true` if the handler is registered, `false` otherwise\n   */\n  has(handler: MiddlewareFn): boolean {\n    return this.#middleware.has(handler)\n  }\n\n  /**\n   * Registers a new middleware handler to the pipeline.\n   *\n   * Adding the same middleware handler multiple times will result in a no-op,\n   * as handlers are stored in a Set to prevent duplicates.\n   *\n   * @param handler - The middleware handler to register\n   * @returns The Middleware instance for method chaining\n   * @throws {Error} If the middleware stack is frozen\n   */\n  add(handler: MiddlewareFn): this {\n    if (this.#isFrozen) {\n      throw new Error('Middleware stack is frozen. Cannot add new middleware')\n    }\n\n    this.#middleware.add(handler)\n    return this\n  }\n\n  /**\n   * Removes a specific middleware handler from the pipeline.\n   *\n   * @param handler - The middleware handler to remove\n   * @returns `true` if the handler was removed, `false` if it was not found\n   * @throws {Error} If the middleware stack is frozen\n   */\n  remove(handler: MiddlewareFn): boolean {\n    if (this.#isFrozen) {\n      throw new Error('Middleware stack is frozen. Cannot remove middleware')\n    }\n\n    return this.#middleware.delete(handler)\n  }\n\n  /**\n   * Removes all registered middleware handlers from the pipeline.\n   *\n   * @throws {Error} If the middleware stack is frozen\n   */\n  clear(): void {\n    if (this.#isFrozen) {\n      throw new Error('Middleware stack is frozen. Cannot clear middleware')\n    }\n\n    this.#middleware.clear()\n  }\n\n  /**\n   * Merges middleware handlers from another Middleware instance.\n   *\n   * The middleware from the source instance are appended to the current instance.\n   *\n   * @param hooks - The source Middleware instance to merge from\n   * @throws {Error} If the middleware stack is frozen\n   */\n  merge(hooks: Middleware<MiddlewareFn>) {\n    if (this.#isFrozen) {\n      throw new Error('Middleware stack is frozen. Cannot merge middleware')\n    }\n\n    hooks.all().forEach((handler) => {\n      this.add(handler)\n    })\n  }\n\n  /**\n   * Freezes the middleware stack to prevent further modifications.\n   *\n   * Once frozen, the middleware array is cached and no new handlers can be added,\n   * removed, or modified. This method is automatically called when creating a runner.\n   */\n  freeze() {\n    if (this.#isFrozen) {\n      return\n    }\n\n    this.#isFrozen = true\n    this.#middlewareArray = [...this.all()]\n  }\n\n  /**\n   * Creates and returns a Runner instance to execute the middleware pipeline.\n   *\n   * This method automatically freezes the middleware stack to prevent modifications\n   * during execution.\n   *\n   * @returns A new Runner instance configured with the current middleware handlers\n   */\n  runner(): Runner<MiddlewareFn> {\n    this.freeze()\n    return new Runner(this.#middlewareArray!)\n  }\n}\n","/**\n * @module @nhtio/middleware\n *\n * A cross-environment (browser/node) implementation of the chain of responsibility design pattern,\n * also known as the middleware pipeline. This package is based on\n * [@poppinss/middleware](https://github.com/poppinss/middleware) and provides a zero-dependency\n * implementation for executing handlers in series.\n *\n * @example\n * ```ts\n * import { Middleware } from '@nhtio/middleware'\n * import type { NextFn } from '@nhtio/middleware'\n *\n * const context = {}\n * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>\n *\n * const middleware = new Middleware<MiddlewareFn>()\n *\n * middleware.add((ctx, next) => {\n *   console.log('executing fn1')\n *   await next()\n * })\n *\n * await middleware\n *   .runner()\n *   .run((fn, next) => fn(context, next))\n * ```\n */\n\n/**\n * The current version of the package.\n *\n * This constant is replaced during the build process with the actual version from package.json.\n */\nexport const version = __VERSION__\n\nexport { Middleware } from './private/middleware'\nexport { Runner } from './private/runner'\nexport * from './private/types'\n"],"names":["once","scope","callback","next","DEFAULT_FINAL_HANDLER","_middleware","_currentIndex","_executor","_finalHandler","_errorHandler","_Runner_instances","invoke_fn","invokeWithErrorManagement_fn","Runner","middleware","__privateAdd","__privateSet","finalHandler","errorHandler","cb","__privateGet","__privateMethod","self","_a","_b","__privateWrapper","_middlewareArray","_isFrozen","Middleware","handler","hooks","version"],"mappings":"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"}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@nhtio/middleware",
+  "version": "0.1.0-master-d3ec5be7",
+  "description": "A cross-environment (browser/node) implementation of the chain of responsibility design pattern based on @poppinss/middleware",
+  "keywords": [],
+  "author": "Jak Giveon <jak@nht.io>",
+  "copyright": "© 2025-present New Horizon Technology LTD",
+  "license": "MIT",
+  "module": "./index.mjs",
+  "main": "./index.cjs",
+  "exports": {
+    ".": {
+      "import": "./index.mjs",
+      "require": "./index.cjs",
+      "types": "./index.d.ts"
+    }
+  },
+  "packageManager": "pnpm@10.8.0+sha512.0e82714d1b5b43c74610193cb20734897c1d00de89d0e18420aebc5977fa13d780a9cb05734624e81ebd81cc876cd464794850641c48b9544326b5622ca29971",
+  "type": "module",
+  "dependencies": {}
+}

package/private/middleware.d.ts

@@ -0,0 +1,94 @@
+import { Runner } from './runner';
+/**
+ * The Middleware class implements the chain of responsibility design pattern
+ * and allows executing handlers in series.
+ *
+ * The middleware handlers can be represented as any value you wish, such as:
+ * - A function: `middleware.add(function () { console.log('called') })`
+ * - An object with a `handle` method: `middleware.add({ name: 'auth', handle: authenticate })`
+ *
+ * @template MiddlewareFn - The type of the middleware function/handler
+ *
+ * @example
+ * ```ts
+ * const context = {}
+ * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>
+ *
+ * const middleware = new Middleware<MiddlewareFn>()
+ *
+ * middleware.add((ctx, next) => {
+ *   console.log('executing middleware')
+ *   await next()
+ * })
+ *
+ * await middleware
+ *   .runner()
+ *   .run((fn, next) => fn(context, next))
+ * ```
+ */
+export declare class Middleware<MiddlewareFn extends any> {
+    #private;
+    /**
+     * Returns all registered middleware handlers.
+     *
+     * @returns A Set containing all registered middleware handlers
+     */
+    all(): Set<MiddlewareFn>;
+    /**
+     * Checks if a specific handler has already been registered as middleware.
+     *
+     * @param handler - The middleware handler to check for
+     * @returns `true` if the handler is registered, `false` otherwise
+     */
+    has(handler: MiddlewareFn): boolean;
+    /**
+     * Registers a new middleware handler to the pipeline.
+     *
+     * Adding the same middleware handler multiple times will result in a no-op,
+     * as handlers are stored in a Set to prevent duplicates.
+     *
+     * @param handler - The middleware handler to register
+     * @returns The Middleware instance for method chaining
+     * @throws {Error} If the middleware stack is frozen
+     */
+    add(handler: MiddlewareFn): this;
+    /**
+     * Removes a specific middleware handler from the pipeline.
+     *
+     * @param handler - The middleware handler to remove
+     * @returns `true` if the handler was removed, `false` if it was not found
+     * @throws {Error} If the middleware stack is frozen
+     */
+    remove(handler: MiddlewareFn): boolean;
+    /**
+     * Removes all registered middleware handlers from the pipeline.
+     *
+     * @throws {Error} If the middleware stack is frozen
+     */
+    clear(): void;
+    /**
+     * Merges middleware handlers from another Middleware instance.
+     *
+     * The middleware from the source instance are appended to the current instance.
+     *
+     * @param hooks - The source Middleware instance to merge from
+     * @throws {Error} If the middleware stack is frozen
+     */
+    merge(hooks: Middleware<MiddlewareFn>): void;
+    /**
+     * Freezes the middleware stack to prevent further modifications.
+     *
+     * Once frozen, the middleware array is cached and no new handlers can be added,
+     * removed, or modified. This method is automatically called when creating a runner.
+     */
+    freeze(): void;
+    /**
+     * Creates and returns a Runner instance to execute the middleware pipeline.
+     *
+     * This method automatically freezes the middleware stack to prevent modifications
+     * during execution.
+     *
+     * @returns A new Runner instance configured with the current middleware handlers
+     */
+    runner(): Runner<MiddlewareFn>;
+}

package/private/runner.d.ts

@@ -0,0 +1,107 @@
+import type { ErrorHandler, Executor, FinalHandler } from './types';
+/**
+ * Runner executes an array of middleware functions in sequence.
+ *
+ * The middleware pipeline advances only when the current function calls `next`,
+ * implementing the chain of responsibility pattern. You control how to execute
+ * the underlying middleware functions by providing an executor function.
+ *
+ * @template MiddlewareFn - The type of the middleware function/handler
+ *
+ * @example
+ * ```ts
+ * const context = { stack: [] }
+ * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>
+ *
+ * const middleware = new Middleware<MiddlewareFn>()
+ * middleware.add((ctx, next) => {
+ *   ctx.stack.push('fn1')
+ *   await next()
+ * })
+ *
+ * await middleware
+ *   .runner()
+ *   .finalHandler(() => {
+ *     context.stack.push('final handler')
+ *   })
+ *   .run((fn, next) => fn(context, next))
+ * ```
+ */
+export declare class Runner<MiddlewareFn extends any> {
+    #private;
+    constructor(middleware: MiddlewareFn[]);
+    /**
+     * Sets a custom final handler to execute when the middleware chain completes successfully.
+     *
+     * The final handler is called when the entire middleware pipeline reaches the end
+     * by calling `next` through all handlers. This makes it easier to execute custom
+     * logic that is not part of the chain but must run when the chain ends.
+     *
+     * @param finalHandler - The function to execute when the chain completes
+     * @returns The Runner instance for method chaining
+     *
+     * @example
+     * ```ts
+     * await middleware
+     *   .runner()
+     *   .finalHandler(() => {
+     *     console.log('All middleware completed')
+     *   })
+     *   .run((fn, next) => fn(context, next))
+     * ```
+     */
+    finalHandler(finalHandler: FinalHandler): this;
+    /**
+     * Sets a custom error handler to catch exceptions in the middleware pipeline.
+     *
+     * By default, exceptions raised in the middleware pipeline bubble up to the `run`
+     * method and can be captured using a try/catch block. When an exception is raised,
+     * the middleware downstream logic will not run.
+     *
+     * Defining an error handler changes this behavior:
+     * - The `run` method will not throw exceptions
+     * - Errors are caught and passed to the error handler
+     * - Middleware upstream logic (after `next`) can still execute
+     *
+     * @param errorHandler - The function to handle errors
+     * @returns The Runner instance for method chaining
+     *
+     * @example
+     * ```ts
+     * await middleware
+     *   .runner()
+     *   .errorHandler((error) => {
+     *     console.error('Middleware error:', error)
+     *   })
+     *   .run((fn, next) => fn(context, next))
+     * ```
+     */
+    errorHandler(errorHandler: ErrorHandler): this;
+    /**
+     * Executes the middleware pipeline using the provided executor function.
+     *
+     * The executor function is responsible for invoking each middleware handler with
+     * the appropriate context and the `next` callback. Since you control the executor,
+     * you can pass any data you want to the middleware.
+     *
+     * @param cb - The executor function that invokes each middleware handler
+     * @returns A Promise that resolves when the middleware pipeline completes
+     *
+     * @example
+     * ```ts
+     * const context = { user: null }
+     * type MiddlewareFn = (ctx: typeof context, next: NextFn) => void | Promise<void>
+     *
+     * const middleware = new Middleware<MiddlewareFn>()
+     * middleware.add(async (ctx, next) => {
+     *   ctx.user = await authenticate()
+     *   await next()
+     * })
+     *
+     * await middleware
+     *   .runner()
+     *   .run((fn, next) => fn(context, next))
+     * ```
+     */
+    run(cb: Executor<MiddlewareFn>): Promise<void>;
+}

package/private/types.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The next function used to advance the middleware pipeline.
+ *
+ * When called, it triggers the execution of the next middleware in the chain.
+ * If not called, the middleware chain stops at the current handler.
+ */
+export type NextFn = () => Promise<any> | any;
+/**
+ * Final handler called when the entire middleware chain completes successfully.
+ *
+ * The final handler is executed after all middleware have called `next` and the
+ * pipeline reaches its end. It provides a way to execute custom logic outside
+ * the middleware chain when the chain completes.
+ */
+export type FinalHandler = () => Promise<any>;
+/**
+ * Error handler called when any middleware in the pipeline raises an exception.
+ *
+ * When defined, errors are caught and passed to this handler instead of bubbling
+ * up to the `run` method. This allows you to implement custom error handling logic
+ * and optionally resume the downstream flow of middleware.
+ *
+ * @param error - The error thrown by the middleware
+ */
+export type ErrorHandler = (error: any) => Promise<any>;
+/**
+ * The executor function responsible for invoking each middleware handler.
+ *
+ * The executor gives you control over how middleware functions are called,
+ * allowing you to pass custom context and parameters to each handler.
+ *
+ * @template MiddlewareFn - The type of the middleware function/handler
+ * @param middleware - The current middleware handler to execute
+ * @param next - The next function to advance the pipeline
+ */
+export type Executor<MiddlewareFn extends any> = (middleware: MiddlewareFn, next: NextFn) => Promise<any>;