@nhtio/middleware 1.20251013.0 → 1.20251213.0

package/index.cjs

@@ -1,2 +1,270 @@
-"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 x{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 F="1.20251013.0";exports.Middleware=x;exports.Runner=A;exports.version=F;
+"use strict";
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+function once(scope, callback) {
+  function next() {
+    if (next.called) {
+      return;
+    }
+    next.called = true;
+    return callback(scope);
+  }
+  next.called = false;
+  return next;
+}
+const DEFAULT_FINAL_HANDLER = () => Promise.resolve();
+class Runner {
+  /**
+   * The array of middleware handlers to execute in sequence.
+   */
+  #middleware;
+  /**
+   * The current index position in the middleware pipeline.
+   */
+  #currentIndex = 0;
+  /**
+   * The executor function responsible for invoking each middleware handler.
+   */
+  #executor;
+  /**
+   * The final handler to execute when the middleware chain completes successfully.
+   */
+  #finalHandler = DEFAULT_FINAL_HANDLER;
+  /**
+   * Optional error handler to catch and handle exceptions in the middleware pipeline.
+   */
+  #errorHandler;
+  constructor(middleware) {
+    this.#middleware = middleware;
+  }
+  /**
+   * 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
+   */
+  #invoke(self) {
+    const middleware = self.#middleware[self.#currentIndex++];
+    if (!middleware) {
+      return self.#finalHandler();
+    }
+    return self.#executor(middleware, once(self, self.#invoke));
+  }
+  /**
+   * 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
+   */
+  #invokeWithErrorManagement(self) {
+    const middleware = self.#middleware[self.#currentIndex++];
+    if (!middleware) {
+      return self.#finalHandler().catch(self.#errorHandler);
+    }
+    return self.#executor(middleware, once(self, self.#invokeWithErrorManagement)).catch(self.#errorHandler);
+  }
+  /**
+   * 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) {
+    this.#finalHandler = finalHandler;
+    return 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) {
+    this.#errorHandler = errorHandler;
+    return 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(cb) {
+    this.#executor = cb;
+    if (this.#errorHandler) {
+      return this.#invokeWithErrorManagement(this);
+    }
+    return this.#invoke(this);
+  }
+}
+class Middleware {
+  #middleware = /* @__PURE__ */ new Set();
+  #middlewareArray;
+  #isFrozen = false;
+  /**
+   * Returns all registered middleware handlers.
+   *
+   * @returns A Set containing all registered middleware handlers
+   */
+  all() {
+    return this.#middleware;
+  }
+  /**
+   * 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) {
+    return this.#middleware.has(handler);
+  }
+  /**
+   * 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) {
+    if (this.#isFrozen) {
+      throw new Error("Middleware stack is frozen. Cannot add new middleware");
+    }
+    this.#middleware.add(handler);
+    return 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) {
+    if (this.#isFrozen) {
+      throw new Error("Middleware stack is frozen. Cannot remove middleware");
+    }
+    return this.#middleware.delete(handler);
+  }
+  /**
+   * Removes all registered middleware handlers from the pipeline.
+   *
+   * @throws {Error} If the middleware stack is frozen
+   */
+  clear() {
+    if (this.#isFrozen) {
+      throw new Error("Middleware stack is frozen. Cannot clear middleware");
+    }
+    this.#middleware.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(hooks) {
+    if (this.#isFrozen) {
+      throw new Error("Middleware stack is frozen. Cannot merge middleware");
+    }
+    hooks.all().forEach((handler) => {
+      this.add(handler);
+    });
+  }
+  /**
+   * 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() {
+    if (this.#isFrozen) {
+      return;
+    }
+    this.#isFrozen = true;
+    this.#middlewareArray = [...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() {
+    this.freeze();
+    return new Runner(this.#middlewareArray);
+  }
+}
+const version = "1.20251213.0";
+exports.Middleware = Middleware;
+exports.Runner = Runner;
+exports.version = version;
 //# sourceMappingURL=index.cjs.map

package/index.cjs.map

@@ -1 +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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"}
+{"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":[],"mappings":"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"}

package/index.d.mts

@@ -0,0 +1,249 @@
+/**
+ * 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 declare 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 declare type Executor<MiddlewareFn extends any> = (middleware: MiddlewareFn, next: NextFn) => Promise<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 declare type FinalHandler = () => Promise<any>;
+
+/**
+ * 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>;
+}
+
+/**
+ * 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 declare type NextFn = () => Promise<any> | any;
+
+/**
+ * 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>;
+}
+
+/**
+ * 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 { }

package/index.mjs

@@ -1,49 +1,74 @@
-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);
+function once(scope, callback) {
+  function next() {
+    if (next.called) {
+      return;
+    }
+    next.called = true;
+    return callback(scope);
   }
-  return e.called = !1, e;
+  next.called = false;
+  return next;
 }
-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);
+const DEFAULT_FINAL_HANDLER = () => Promise.resolve();
+class Runner {
+  /**
+   * The array of middleware handlers to execute in sequence.
+   */
+  #middleware;
+  /**
+   * The current index position in the middleware pipeline.
+   */
+  #currentIndex = 0;
+  /**
+   * The executor function responsible for invoking each middleware handler.
+   */
+  #executor;
+  /**
+   * The final handler to execute when the middleware chain completes successfully.
+   */
+  #finalHandler = DEFAULT_FINAL_HANDLER;
+  /**
+   * Optional error handler to catch and handle exceptions in the middleware pipeline.
+   */
+  #errorHandler;
+  constructor(middleware) {
+    this.#middleware = middleware;
+  }
+  /**
+   * 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
+   */
+  #invoke(self) {
+    const middleware = self.#middleware[self.#currentIndex++];
+    if (!middleware) {
+      return self.#finalHandler();
+    }
+    return self.#executor(middleware, once(self, self.#invoke));
+  }
+  /**
+   * 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
+   */
+  #invokeWithErrorManagement(self) {
+    const middleware = self.#middleware[self.#currentIndex++];
+    if (!middleware) {
+      return self.#finalHandler().catch(self.#errorHandler);
+    }
+    return self.#executor(middleware, once(self, self.#invokeWithErrorManagement)).catch(self.#errorHandler);
   }
   /**
    * Sets a custom final handler to execute when the middleware chain completes successfully.
@@ -65,8 +90,9 @@ class g {
    *   .run((fn, next) => fn(context, next))
    * ```
    */
-  finalHandler(r) {
-    return s(this, m, r), this;
+  finalHandler(finalHandler) {
+    this.#finalHandler = finalHandler;
+    return this;
   }
   /**
    * Sets a custom error handler to catch exceptions in the middleware pipeline.
@@ -93,8 +119,9 @@ class g {
    *   .run((fn, next) => fn(context, next))
    * ```
    */
-  errorHandler(r) {
-    return s(this, l, r), this;
+  errorHandler(errorHandler) {
+    this.#errorHandler = errorHandler;
+    return this;
   }
   /**
    * Executes the middleware pipeline using the provided executor function.
@@ -122,55 +149,25 @@ class g {
    *   .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);
+  async run(cb) {
+    this.#executor = cb;
+    if (this.#errorHandler) {
+      return this.#invokeWithErrorManagement(this);
+    }
+    return this.#invoke(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);
-  }
+class Middleware {
+  #middleware = /* @__PURE__ */ new Set();
+  #middlewareArray;
+  #isFrozen = false;
   /**
    * Returns all registered middleware handlers.
    *
    * @returns A Set containing all registered middleware handlers
    */
   all() {
-    return n(this, o);
+    return this.#middleware;
   }
   /**
    * Checks if a specific handler has already been registered as middleware.
@@ -178,8 +175,8 @@ class L {
    * @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);
+  has(handler) {
+    return this.#middleware.has(handler);
   }
   /**
    * Registers a new middleware handler to the pipeline.
@@ -191,10 +188,12 @@ class L {
    * @returns The Middleware instance for method chaining
    * @throws {Error} If the middleware stack is frozen
    */
-  add(r) {
-    if (n(this, d))
+  add(handler) {
+    if (this.#isFrozen) {
       throw new Error("Middleware stack is frozen. Cannot add new middleware");
-    return n(this, o).add(r), this;
+    }
+    this.#middleware.add(handler);
+    return this;
   }
   /**
    * Removes a specific middleware handler from the pipeline.
@@ -203,10 +202,11 @@ class L {
    * @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))
+  remove(handler) {
+    if (this.#isFrozen) {
       throw new Error("Middleware stack is frozen. Cannot remove middleware");
-    return n(this, o).delete(r);
+    }
+    return this.#middleware.delete(handler);
   }
   /**
    * Removes all registered middleware handlers from the pipeline.
@@ -214,9 +214,10 @@ class L {
    * @throws {Error} If the middleware stack is frozen
    */
   clear() {
-    if (n(this, d))
+    if (this.#isFrozen) {
       throw new Error("Middleware stack is frozen. Cannot clear middleware");
-    n(this, o).clear();
+    }
+    this.#middleware.clear();
   }
   /**
    * Merges middleware handlers from another Middleware instance.
@@ -226,11 +227,12 @@ class L {
    * @param hooks - The source Middleware instance to merge from
    * @throws {Error} If the middleware stack is frozen
    */
-  merge(r) {
-    if (n(this, d))
+  merge(hooks) {
+    if (this.#isFrozen) {
       throw new Error("Middleware stack is frozen. Cannot merge middleware");
-    r.all().forEach((e) => {
-      this.add(e);
+    }
+    hooks.all().forEach((handler) => {
+      this.add(handler);
     });
   }
   /**
@@ -240,7 +242,11 @@ class L {
    * 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()]));
+    if (this.#isFrozen) {
+      return;
+    }
+    this.#isFrozen = true;
+    this.#middlewareArray = [...this.all()];
   }
   /**
    * Creates and returns a Runner instance to execute the middleware pipeline.
@@ -251,14 +257,14 @@ class L {
    * @returns A new Runner instance configured with the current middleware handlers
    */
   runner() {
-    return this.freeze(), new g(n(this, z));
+    this.freeze();
+    return new Runner(this.#middlewareArray);
   }
 }
-o = new WeakMap(), z = new WeakMap(), d = new WeakMap();
-const y = "1.20251013.0";
+const version = "1.20251213.0";
 export {
-  L as Middleware,
-  g as Runner,
-  y as version
+  Middleware,
+  Runner,
+  version
 };
 //# sourceMappingURL=index.mjs.map

package/index.mjs.map

@@ -1 +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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"}
+{"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":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nhtio/middleware",
-  "version": "1.20251013.0",
+  "version": "1.20251213.0",
   "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>",

package/index.d.ts

@@ -1,37 +0,0 @@
-/**
- * @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/private/middleware.d.ts

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

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

@@ -1,36 +0,0 @@
-/**
- * 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>;