@nextrush/core 3.0.0

package/dist/index.js

@@ -0,0 +1,534 @@
+export { BadRequestError, ForbiddenError, HttpError, InternalServerError, NextRushError, NotFoundError, UnauthorizedError, createError as createHttpError } from '@nextrush/errors';
+export { ContentType, HttpStatus } from '@nextrush/types';
+
+// src/middleware.ts
+function compose(middleware, options) {
+  if (!Array.isArray(middleware)) {
+    throw new TypeError("Middleware stack must be an array");
+  }
+  for (const fn of middleware) {
+    if (typeof fn !== "function") {
+      throw new TypeError("Middleware must be a function");
+    }
+  }
+  const warnDoubleResponse = options?.warnDoubleResponse ?? process.env.NODE_ENV !== "production";
+  const stack = [...middleware];
+  const len = stack.length;
+  if (len === 0) {
+    return function composedMiddleware(_ctx, next) {
+      return next ? next() : Promise.resolve();
+    };
+  }
+  return function composedMiddleware(ctx, next) {
+    let index = -1;
+    function dispatch(i) {
+      if (i <= index) {
+        return Promise.reject(new Error("next() called multiple times"));
+      }
+      index = i;
+      let fn;
+      if (i < len) {
+        fn = stack[i];
+      } else if (i === len) {
+        fn = next;
+      }
+      if (!fn) {
+        return Promise.resolve();
+      }
+      const respondedBefore = warnDoubleResponse ? ctx.responded : false;
+      let nextCalled = false;
+      const nextFn = () => {
+        nextCalled = true;
+        return dispatch(i + 1);
+      };
+      if (ctx.setNext) {
+        ctx.setNext(nextFn);
+      }
+      try {
+        const result = Promise.resolve(fn(ctx, nextFn));
+        if (warnDoubleResponse) {
+          return result.then(() => {
+            if (!respondedBefore && ctx.responded && nextCalled) {
+              console.warn(
+                `[nextrush] Middleware at index ${String(i)} sent a response and called next(). Downstream middleware may attempt to write to an already-finished response. Either send a response OR call next(), not both.`
+              );
+            }
+          });
+        }
+        return result;
+      } catch (err) {
+        return Promise.reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    }
+    return dispatch(0);
+  };
+}
+function isMiddleware(fn) {
+  return typeof fn === "function";
+}
+function flattenMiddleware(arr) {
+  const flattened = arr.flat(10);
+  for (const fn of flattened) {
+    if (typeof fn !== "function") {
+      throw new TypeError(`Invalid middleware: expected function, got ${typeof fn}`);
+    }
+  }
+  return flattened;
+}
+
+// src/application.ts
+var ORIGINAL_PATH = /* @__PURE__ */ Symbol.for("nextrush.originalPath");
+var ROUTE_PREFIX = /* @__PURE__ */ Symbol.for("nextrush.routePrefix");
+var NOOP_LOGGER = {
+  error(..._args) {
+  },
+  warn(..._args) {
+  },
+  info(..._args) {
+  },
+  debug(..._args) {
+  }
+};
+var Application = class {
+  /**
+   * Middleware stack
+   */
+  middlewareStack = [];
+  /**
+   * Installed plugins
+   */
+  plugins = /* @__PURE__ */ new Map();
+  /**
+   * Custom error handler
+   */
+  _errorHandler = null;
+  /**
+   * Pluggable logger
+   */
+  logger;
+  /**
+   * Application options
+   */
+  options;
+  /**
+   * Whether the app is running
+   */
+  _isRunning = false;
+  constructor(options = {}) {
+    this.options = {
+      env: options.env ?? "development",
+      proxy: options.proxy ?? false
+    };
+    this.logger = options.logger ?? NOOP_LOGGER;
+  }
+  /**
+   * Check if running in production
+   */
+  get isProduction() {
+    return this.options.env === "production";
+  }
+  /**
+   * Check if app is running
+   */
+  get isRunning() {
+    return this._isRunning;
+  }
+  /**
+   * Get middleware count
+   */
+  get middlewareCount() {
+    return this.middlewareStack.length;
+  }
+  /**
+   * Throws if the app is already running.
+   * Prevents configuration mutations after start().
+   */
+  assertNotRunning(method) {
+    if (this._isRunning) {
+      throw new Error(`Cannot call ${method}() after the application has started`);
+    }
+  }
+  // ===========================================================================
+  // Middleware Registration
+  // ===========================================================================
+  /**
+   * Register middleware function(s)
+   *
+   * @param middleware - Middleware function or array of middleware
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * // Single middleware
+   * app.use(async (ctx) => {
+   *   console.log(ctx.method, ctx.path);
+   *   await ctx.next();
+   * });
+   *
+   * // Multiple middleware
+   * app.use(cors(), helmet(), json());
+   * ```
+   */
+  use(...middleware) {
+    this.assertNotRunning("use");
+    for (const mw of middleware) {
+      if (typeof mw !== "function") {
+        throw new TypeError("Middleware must be a function");
+      }
+      this.middlewareStack.push(mw);
+    }
+    return this;
+  }
+  // ===========================================================================
+  // Router Mounting (Hono-style)
+  // ===========================================================================
+  /**
+   * Mount a router at a path prefix
+   *
+   * This is the Hono-style API for mounting routers directly on the app.
+   * The router's routes will only match requests that start with the given prefix.
+   *
+   * @param path - Path prefix for the router (e.g., '/api/users')
+   * @param router - Router instance to mount
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * // Create modular routers
+   * const users = createRouter();
+   * users.get('/', listUsers);
+   * users.get('/:id', getUser);
+   * users.post('/', createUser);
+   *
+   * const posts = createRouter();
+   * posts.get('/', listPosts);
+   * posts.get('/:id', getPost);
+   *
+   * // Mount directly on app - clean like Hono!
+   * const app = createApp();
+   * app.route('/api/users', users);
+   * app.route('/api/posts', posts);
+   *
+   * listen(app, 3000);
+   * ```
+   */
+  route(path, router) {
+    this.assertNotRunning("route");
+    if (path === "/" || path === "") {
+      this.middlewareStack.push(router.routes());
+      return this;
+    }
+    const routerMiddleware = router.routes();
+    let normalizedPrefix = path.endsWith("/") ? path.slice(0, -1) : path;
+    if (!normalizedPrefix.startsWith("/")) {
+      normalizedPrefix = "/" + normalizedPrefix;
+    }
+    const prefixLen = normalizedPrefix.length;
+    const mountedMiddleware = async (ctx, next) => {
+      const currentPath = ctx.path;
+      if (!currentPath.startsWith(normalizedPrefix)) {
+        return next();
+      }
+      const hasCharAfterPrefix = prefixLen < currentPath.length;
+      if (hasCharAfterPrefix && currentPath.charCodeAt(prefixLen) !== 47) {
+        return next();
+      }
+      const adjustedPath = currentPath.slice(prefixLen) || "/";
+      ctx.path = adjustedPath;
+      ctx.state[ORIGINAL_PATH] = currentPath;
+      ctx.state[ROUTE_PREFIX] = normalizedPrefix;
+      try {
+        await routerMiddleware(ctx, async () => {
+          ctx.path = currentPath;
+          await next();
+          ctx.path = adjustedPath;
+        });
+      } finally {
+        ctx.path = currentPath;
+        ctx.state[ORIGINAL_PATH] = void 0;
+        ctx.state[ROUTE_PREFIX] = void 0;
+      }
+    };
+    this.middlewareStack.push(mountedMiddleware);
+    return this;
+  }
+  // ===========================================================================
+  // Error Handling
+  // ===========================================================================
+  /**
+   * Set the application error handler.
+   *
+   * Replaces any previously set handler. Only one error handler is active
+   * at a time. For additive error handling, compose logic within a single
+   * handler or use the `errorHandler()` middleware from `@nextrush/errors`.
+   *
+   * @param handler - Error handler function
+   * @returns this for chaining
+   *
+   * @example
+   * ```typescript
+   * app.setErrorHandler((error, ctx) => {
+   *   console.error('Request failed:', error);
+   *
+   *   if (error instanceof ValidationError) {
+   *     ctx.status = 400;
+   *     ctx.json({ error: error.message, details: error.details });
+   *     return;
+   *   }
+   *
+   *   ctx.status = 500;
+   *   ctx.json({ error: 'Internal Server Error' });
+   * });
+   * ```
+   */
+  setErrorHandler(handler) {
+    this._errorHandler = handler;
+    return this;
+  }
+  /**
+   * Set custom error handler.
+   *
+   * @param handler - Error handler function
+   * @returns this for chaining
+   *
+   * @deprecated Use `setErrorHandler()` instead — `onError()` implies
+   * event subscription (additive), but this is a setter (replaces).
+   */
+  onError(handler) {
+    return this.setErrorHandler(handler);
+  }
+  // ===========================================================================
+  // Plugin System
+  // ===========================================================================
+  /**
+   * Install a plugin.
+   *
+   * Handles both sync and async `install()` methods automatically.
+   * Returns `this` for sync plugins and `Promise<this>` for async ones.
+   *
+   * @param plugin - Plugin to install
+   * @returns this (sync) or Promise<this> (async)
+   *
+   * @example
+   * ```typescript
+   * // Sync plugin
+   * app.plugin(loggerPlugin({ level: 'info' }));
+   *
+   * // Async plugin — just await it
+   * await app.plugin(databasePlugin({ uri: '...' }));
+   * ```
+   */
+  plugin(plugin) {
+    this.assertNotRunning("plugin");
+    if (this.plugins.has(plugin.name)) {
+      throw new Error(`Plugin "${plugin.name}" is already installed`);
+    }
+    const result = plugin.install(this);
+    if (result instanceof Promise) {
+      return result.then(() => {
+        this.plugins.set(plugin.name, plugin);
+        return this;
+      });
+    }
+    this.plugins.set(plugin.name, plugin);
+    return this;
+  }
+  /**
+   * Install a plugin asynchronously.
+   *
+   * @param plugin - Plugin to install
+   * @returns Promise that resolves when plugin is installed
+   *
+   * @deprecated Use `plugin()` instead — it handles both sync and async
+   * plugins automatically.
+   *
+   * @example
+   * ```typescript
+   * await app.plugin(new DatabasePlugin({ connectionString: '...' }));
+   * ```
+   */
+  async pluginAsync(plugin) {
+    const result = this.plugin(plugin);
+    return result instanceof Promise ? result : Promise.resolve(result);
+  }
+  /**
+   * Get an installed plugin by name
+   *
+   * @param name - Plugin name
+   * @returns Plugin instance or undefined
+   */
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters
+  getPlugin(name) {
+    return this.plugins.get(name);
+  }
+  /**
+   * Check if a plugin is installed
+   */
+  hasPlugin(name) {
+    return this.plugins.has(name);
+  }
+  // ===========================================================================
+  // Request Handler
+  // ===========================================================================
+  /**
+   * Create the request handler callback
+   *
+   * This is the function that adapters call to handle each request.
+   * It composes all middleware and returns a function that processes context.
+   *
+   * **Important:** The middleware stack is snapshot at call time.
+   * Middleware or plugins added after `callback()` will NOT take effect
+   * on the returned handler. Call `callback()` again to get a
+   * handler that includes subsequent registrations.
+   *
+   * @returns Request handler function
+   */
+  callback() {
+    const fn = compose(this.middlewareStack);
+    const hookPlugins = Array.from(this.plugins.values()).filter((p) => {
+      const hasHook = "onRequest" in p || "onResponse" in p || "onError" in p || "extendContext" in p;
+      if (!hasHook) return false;
+      if ("onRequest" in p && typeof p.onRequest !== "function") {
+        throw new TypeError(
+          `Plugin "${p.name}": onRequest must be a function, got ${typeof p.onRequest}`
+        );
+      }
+      if ("onResponse" in p && typeof p.onResponse !== "function") {
+        throw new TypeError(
+          `Plugin "${p.name}": onResponse must be a function, got ${typeof p.onResponse}`
+        );
+      }
+      if ("onError" in p && typeof p.onError !== "function") {
+        throw new TypeError(
+          `Plugin "${p.name}": onError must be a function, got ${typeof p.onError}`
+        );
+      }
+      if ("extendContext" in p && typeof p.extendContext !== "function") {
+        throw new TypeError(
+          `Plugin "${p.name}": extendContext must be a function, got ${typeof p.extendContext}`
+        );
+      }
+      return true;
+    });
+    return async (ctx) => {
+      try {
+        for (const p of hookPlugins) {
+          if (p.extendContext) p.extendContext(ctx);
+          if (p.onRequest) await p.onRequest(ctx);
+        }
+        await fn(ctx);
+        for (const p of hookPlugins) {
+          if (p.onResponse) {
+            try {
+              await p.onResponse(ctx);
+            } catch (hookError) {
+              this.logger.warn("Plugin onResponse hook threw:", {
+                plugin: p.name,
+                error: hookError
+              });
+            }
+          }
+        }
+      } catch (error) {
+        const err = error instanceof Error ? error : new Error(String(error));
+        for (const p of hookPlugins) {
+          if (p.onError) {
+            try {
+              await p.onError(err, ctx);
+            } catch (hookError) {
+              this.logger.warn("Plugin onError hook threw:", {
+                plugin: p.name,
+                error: hookError
+              });
+            }
+          }
+        }
+        await this.handleError(error, ctx);
+      }
+    };
+  }
+  /**
+   * Handle errors - uses custom handler if set, otherwise default
+   */
+  async handleError(error, ctx) {
+    const err = error instanceof Error ? error : new Error(String(error));
+    if (this._errorHandler) {
+      try {
+        await this._errorHandler(err, ctx);
+        return;
+      } catch (handlerError) {
+        this.logger.error("Error handler threw:", handlerError);
+      }
+    }
+    this.defaultErrorHandler(err, ctx);
+  }
+  /**
+   * Default error handler
+   *
+   * Uses the `expose` flag on errors (set by HttpError/NextRushError)
+   * to decide whether to include the error message in the response.
+   * 4xx errors expose messages by default; 5xx errors never do.
+   * This prevents leaking internal details (paths, SQL, stack info)
+   * regardless of environment.
+   */
+  defaultErrorHandler(error, ctx) {
+    if (!this.isProduction) {
+      this.logger.error("Request error:", error);
+    }
+    const errorMeta = error;
+    let status = 500;
+    if (typeof errorMeta.status === "number") {
+      const raw = errorMeta.status;
+      status = raw >= 400 && raw < 600 ? raw : 500;
+    }
+    ctx.status = status;
+    const expose = errorMeta.expose === true;
+    const message = expose ? error.message : "Internal Server Error";
+    ctx.json({ error: message });
+  }
+  // ===========================================================================
+  // Lifecycle
+  // ===========================================================================
+  /**
+   * Mark app as running and freeze configuration.
+   *
+   * Called by adapters when the server starts listening. After this call,
+   * `use()`, `route()`, `plugin()`, and `pluginAsync()` will throw.
+   * This prevents unsafe middleware mutations while requests are in flight.
+   *
+   * To re-enable registration (e.g. for testing), call `close()` first.
+   */
+  start() {
+    this._isRunning = true;
+  }
+  /**
+   * Graceful shutdown
+   * Destroys all plugins that have a destroy method.
+   * Uses Promise.allSettled to ensure all plugins are destroyed
+   * even if some throw errors.
+   *
+   * @returns Array of errors from plugins that failed to destroy (empty on success)
+   */
+  async close() {
+    this._isRunning = false;
+    const pluginArray = Array.from(this.plugins.values()).reverse();
+    const destroyablePlugins = pluginArray.filter(
+      (p) => typeof p.destroy === "function"
+    );
+    const destroyPromises = destroyablePlugins.map(
+      (p) => Promise.resolve().then(() => p.destroy()).catch((err) => {
+        throw err instanceof Error ? err : new Error(String(err));
+      })
+    );
+    const results = await Promise.allSettled(destroyPromises);
+    this.plugins.clear();
+    return results.filter((r) => r.status === "rejected").map((r) => r.reason instanceof Error ? r.reason : new Error(String(r.reason)));
+  }
+};
+function createApp(options) {
+  return new Application(options);
+}
+
+export { Application, compose, createApp, flattenMiddleware, isMiddleware };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/middleware.ts","../src/application.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @nextrush/core - Middleware Composition\n *\n * Koa-style middleware composition with async/await support.\n * This is the heart of the middleware pipeline.\n *\n * @packageDocumentation\n */\n\nimport type { Context, Middleware, Next } from '@nextrush/types';\n\n/**\n * Composed middleware handler - can be called with just context\n */\nexport type ComposedMiddleware = (ctx: Context, next?: Next) => Promise<void>;\n\n/**\n * Options for middleware composition\n */\nexport interface ComposeOptions {\n  /**\n   * Warn when a middleware sends a response AND calls next().\n   * Enabled by default in non-production environments.\n   * @default process.env.NODE_ENV !== 'production'\n   */\n  warnDoubleResponse?: boolean;\n}\n\n/**\n * Compose multiple middleware functions into a single middleware.\n *\n * Executes middleware in order, each middleware can call `await next()`\n * to pass control to the next middleware and wait for it to complete.\n *\n * @param middleware - Array of middleware functions to compose\n * @param options - Composition options\n * @returns Single composed middleware function\n *\n * @example\n * ```typescript\n * const composed = compose([\n *   async (ctx, next) => {\n *     console.log('1 - before');\n *     await next();\n *     console.log('1 - after');\n *   },\n *   async (ctx, next) => {\n *     console.log('2 - before');\n *     await next();\n *     console.log('2 - after');\n *   },\n * ]);\n *\n * // Output:\n * // 1 - before\n * // 2 - before\n * // 2 - after\n * // 1 - after\n * ```\n */\nexport function compose(middleware: Middleware[], options?: ComposeOptions): ComposedMiddleware {\n  // Validate middleware array\n  if (!Array.isArray(middleware)) {\n    throw new TypeError('Middleware stack must be an array');\n  }\n\n  for (const fn of middleware) {\n    if (typeof fn !== 'function') {\n      throw new TypeError('Middleware must be a function');\n    }\n  }\n\n  const warnDoubleResponse = options?.warnDoubleResponse ?? process.env.NODE_ENV !== 'production';\n\n  // Snapshot middleware array at compose time\n  const stack = [...middleware];\n  const len = stack.length;\n\n  // FAST PATH: No middleware — just call next()\n  if (len === 0) {\n    return function composedMiddleware(_ctx: Context, next?: Next): Promise<void> {\n      return next ? next() : Promise.resolve();\n    };\n  }\n\n  /**\n   * Composed middleware function\n   * Uses index-based dispatch to avoid per-request closure chains\n   * while preserving double-next detection per call.\n   */\n  return function composedMiddleware(ctx: Context, next?: Next): Promise<void> {\n    // Per-request index tracker — only state needed\n    let index = -1;\n\n    function dispatch(i: number): Promise<void> {\n      if (i <= index) {\n        return Promise.reject(new Error('next() called multiple times'));\n      }\n\n      index = i;\n\n      let fn: Middleware | Next | undefined;\n      if (i < len) {\n        fn = stack[i];\n      } else if (i === len) {\n        fn = next;\n      }\n\n      if (!fn) {\n        return Promise.resolve();\n      }\n\n      // Capture responded state before middleware runs (dev-mode warning)\n      const respondedBefore = warnDoubleResponse ? ctx.responded : false;\n      let nextCalled = false;\n\n      const nextFn = () => {\n        nextCalled = true;\n        return dispatch(i + 1);\n      };\n\n      // Wire up ctx.next() if the context supports it\n      if (ctx.setNext) {\n        ctx.setNext(nextFn);\n      }\n\n      try {\n        const result = Promise.resolve(fn(ctx, nextFn));\n\n        if (warnDoubleResponse) {\n          return result.then(() => {\n            if (!respondedBefore && ctx.responded && nextCalled) {\n              console.warn(\n                `[nextrush] Middleware at index ${String(i)} sent a response and called next(). ` +\n                  'Downstream middleware may attempt to write to an already-finished response. ' +\n                  'Either send a response OR call next(), not both.'\n              );\n            }\n          });\n        }\n\n        return result;\n      } catch (err: unknown) {\n        return Promise.reject(err instanceof Error ? err : new Error(String(err)));\n      }\n    }\n\n    return dispatch(0);\n  };\n}\n\n/**\n * Check if a function is a valid middleware\n */\nexport function isMiddleware(fn: unknown): fn is Middleware {\n  return typeof fn === 'function';\n}\n\n/**\n * Flatten nested middleware arrays with type validation.\n * Uses bounded depth (10 levels) to prevent V8 deoptimization on deeply nested arrays.\n */\nexport function flattenMiddleware(arr: (Middleware | Middleware[])[]): Middleware[] {\n  const flattened = arr.flat(10);\n  for (const fn of flattened) {\n    if (typeof fn !== 'function') {\n      throw new TypeError(`Invalid middleware: expected function, got ${typeof fn}`);\n    }\n  }\n  return flattened;\n}\n","/**\n * @nextrush/core - Application Class\n *\n * The Application class is the main entry point for NextRush.\n * It manages middleware registration and plugin installation.\n *\n * @packageDocumentation\n */\n\nimport type { Context, Middleware, Plugin, PluginWithHooks } from '@nextrush/types';\nimport { compose } from './middleware';\n\n/** @internal Symbol keys for route() state — avoids polluting user's ctx.state namespace */\nconst ORIGINAL_PATH = Symbol.for('nextrush.originalPath');\nconst ROUTE_PREFIX = Symbol.for('nextrush.routePrefix');\n\n/**\n * Error handler function type\n */\nexport type ErrorHandler = (error: Error, ctx: Context) => void | Promise<void>;\n\n/**\n * Logger interface for pluggable logging\n */\nexport interface Logger {\n  error(...args: unknown[]): void;\n  warn(...args: unknown[]): void;\n  info(...args: unknown[]): void;\n  debug(...args: unknown[]): void;\n}\n\n/** No-op logger — default when no logger is configured */\nconst NOOP_LOGGER: Logger = {\n  error(..._args) {\n    void _args;\n  },\n  warn(..._args) {\n    void _args;\n  },\n  info(..._args) {\n    void _args;\n  },\n  debug(..._args) {\n    void _args;\n  },\n};\n\n/**\n * Application options\n */\nexport interface ApplicationOptions {\n  /**\n   * Environment mode\n   * @default 'development'\n   */\n  env?: 'development' | 'production' | 'test';\n\n  /**\n   * Whether to use proxy headers (X-Forwarded-For, etc.)\n   * @default false\n   */\n  proxy?: boolean;\n\n  /**\n   * Custom logger. Defaults to no-op (silent).\n   *\n   * @remarks\n   * Pass `console` for quick development logging:\n   * ```ts\n   * const app = createApp({ logger: console });\n   * ```\n   *\n   * For production, provide a structured logger (e.g. pino, winston)\n   * that implements the {@link Logger} interface.\n   *\n   * Adapters and internal hooks use `app.logger` — configuring it here\n   * ensures consistent logging across the framework.\n   */\n  logger?: Logger;\n}\n\n/**\n * Listener callback type\n */\nexport type ListenCallback = () => void;\n\n/**\n * Routable interface - any object with routes() method\n * This allows mounting Router instances without circular dependency\n */\nexport interface Routable {\n  routes(): Middleware;\n}\n\n/**\n * The Application class\n *\n * @example\n * ```typescript\n * const app = createApp();\n *\n * app.use(async (ctx) => {\n *   ctx.json({ message: 'Hello World' });\n * });\n *\n * // Mount with an adapter\n * listen(app, { port: 3000 });\n * ```\n */\nexport class Application {\n  /**\n   * Middleware stack\n   */\n  private readonly middlewareStack: Middleware[] = [];\n\n  /**\n   * Installed plugins\n   */\n  private readonly plugins = new Map<string, Plugin>();\n\n  /**\n   * Custom error handler\n   */\n  private _errorHandler: ErrorHandler | null = null;\n\n  /**\n   * Pluggable logger\n   */\n  readonly logger: Logger;\n\n  /**\n   * Application options\n   */\n  readonly options: ApplicationOptions;\n\n  /**\n   * Whether the app is running\n   */\n  private _isRunning = false;\n\n  constructor(options: ApplicationOptions = {}) {\n    this.options = {\n      env: options.env ?? 'development',\n      proxy: options.proxy ?? false,\n    };\n    this.logger = options.logger ?? NOOP_LOGGER;\n  }\n\n  /**\n   * Check if running in production\n   */\n  get isProduction(): boolean {\n    return this.options.env === 'production';\n  }\n\n  /**\n   * Check if app is running\n   */\n  get isRunning(): boolean {\n    return this._isRunning;\n  }\n\n  /**\n   * Get middleware count\n   */\n  get middlewareCount(): number {\n    return this.middlewareStack.length;\n  }\n\n  /**\n   * Throws if the app is already running.\n   * Prevents configuration mutations after start().\n   */\n  private assertNotRunning(method: string): void {\n    if (this._isRunning) {\n      throw new Error(`Cannot call ${method}() after the application has started`);\n    }\n  }\n\n  // ===========================================================================\n  // Middleware Registration\n  // ===========================================================================\n\n  /**\n   * Register middleware function(s)\n   *\n   * @param middleware - Middleware function or array of middleware\n   * @returns this for chaining\n   *\n   * @example\n   * ```typescript\n   * // Single middleware\n   * app.use(async (ctx) => {\n   *   console.log(ctx.method, ctx.path);\n   *   await ctx.next();\n   * });\n   *\n   * // Multiple middleware\n   * app.use(cors(), helmet(), json());\n   * ```\n   */\n  use(...middleware: Middleware[]): this {\n    this.assertNotRunning('use');\n    for (const mw of middleware) {\n      if (typeof mw !== 'function') {\n        throw new TypeError('Middleware must be a function');\n      }\n      this.middlewareStack.push(mw);\n    }\n    return this;\n  }\n\n  // ===========================================================================\n  // Router Mounting (Hono-style)\n  // ===========================================================================\n\n  /**\n   * Mount a router at a path prefix\n   *\n   * This is the Hono-style API for mounting routers directly on the app.\n   * The router's routes will only match requests that start with the given prefix.\n   *\n   * @param path - Path prefix for the router (e.g., '/api/users')\n   * @param router - Router instance to mount\n   * @returns this for chaining\n   *\n   * @example\n   * ```typescript\n   * // Create modular routers\n   * const users = createRouter();\n   * users.get('/', listUsers);\n   * users.get('/:id', getUser);\n   * users.post('/', createUser);\n   *\n   * const posts = createRouter();\n   * posts.get('/', listPosts);\n   * posts.get('/:id', getPost);\n   *\n   * // Mount directly on app - clean like Hono!\n   * const app = createApp();\n   * app.route('/api/users', users);\n   * app.route('/api/posts', posts);\n   *\n   * listen(app, 3000);\n   * ```\n   */\n  route(path: string, router: Routable): this {\n    this.assertNotRunning('route');\n    // Root mount optimization: skip all prefix processing\n    if (path === '/' || path === '') {\n      this.middlewareStack.push(router.routes());\n      return this;\n    }\n\n    const routerMiddleware = router.routes();\n    // Normalize prefix: ensure leading '/', strip trailing '/'\n    let normalizedPrefix = path.endsWith('/') ? path.slice(0, -1) : path;\n    if (!normalizedPrefix.startsWith('/')) {\n      normalizedPrefix = '/' + normalizedPrefix;\n    }\n    const prefixLen = normalizedPrefix.length;\n\n    // NOTE (DX-3): We cast `ctx` to `{ path: string }` inside this middleware\n    // to temporarily strip the `readonly` modifier on `path`. This is intentional:\n    // route mounting must adjust ctx.path for the sub-router and restore it\n    // afterwards. The Context interface keeps `path` readonly to prevent\n    // accidental mutation by user code, but internal mounting is the exception.\n    const mountedMiddleware: Middleware = async (ctx, next) => {\n      const currentPath = ctx.path;\n\n      // Fast prefix check\n      if (!currentPath.startsWith(normalizedPrefix)) {\n        return next();\n      }\n\n      // Check prefix boundary (avoid /api/usersxxx matching /api/users)\n      const hasCharAfterPrefix = prefixLen < currentPath.length;\n      if (hasCharAfterPrefix && currentPath.charCodeAt(prefixLen) !== 47) {\n        // 47 = '/'\n        return next();\n      }\n\n      // Direct path manipulation (no Proxy - fast!)\n      const adjustedPath = currentPath.slice(prefixLen) || '/';\n      (ctx as { path: string }).path = adjustedPath;\n\n      // Store original for recovery (Symbol keys avoid ctx.state pollution)\n      (ctx.state as Record<symbol, unknown>)[ORIGINAL_PATH] = currentPath;\n      (ctx.state as Record<symbol, unknown>)[ROUTE_PREFIX] = normalizedPrefix;\n\n      try {\n        await routerMiddleware(ctx, async () => {\n          // Restore original path before calling downstream middleware\n          // so downstream sees the full unmounted path\n          (ctx as { path: string }).path = currentPath;\n          await next();\n          // Re-apply stripped path for router's return path\n          (ctx as { path: string }).path = adjustedPath;\n        });\n      } finally {\n        // Restore original path and clean up Symbol state\n        (ctx as { path: string }).path = currentPath;\n        (ctx.state as Record<symbol, unknown>)[ORIGINAL_PATH] = undefined;\n        (ctx.state as Record<symbol, unknown>)[ROUTE_PREFIX] = undefined;\n      }\n    };\n\n    this.middlewareStack.push(mountedMiddleware);\n    return this;\n  }\n\n  // ===========================================================================\n  // Error Handling\n  // ===========================================================================\n\n  /**\n   * Set the application error handler.\n   *\n   * Replaces any previously set handler. Only one error handler is active\n   * at a time. For additive error handling, compose logic within a single\n   * handler or use the `errorHandler()` middleware from `@nextrush/errors`.\n   *\n   * @param handler - Error handler function\n   * @returns this for chaining\n   *\n   * @example\n   * ```typescript\n   * app.setErrorHandler((error, ctx) => {\n   *   console.error('Request failed:', error);\n   *\n   *   if (error instanceof ValidationError) {\n   *     ctx.status = 400;\n   *     ctx.json({ error: error.message, details: error.details });\n   *     return;\n   *   }\n   *\n   *   ctx.status = 500;\n   *   ctx.json({ error: 'Internal Server Error' });\n   * });\n   * ```\n   */\n  setErrorHandler(handler: ErrorHandler): this {\n    this._errorHandler = handler;\n    return this;\n  }\n\n  /**\n   * Set custom error handler.\n   *\n   * @param handler - Error handler function\n   * @returns this for chaining\n   *\n   * @deprecated Use `setErrorHandler()` instead — `onError()` implies\n   * event subscription (additive), but this is a setter (replaces).\n   */\n  onError(handler: ErrorHandler): this {\n    return this.setErrorHandler(handler);\n  }\n\n  // ===========================================================================\n  // Plugin System\n  // ===========================================================================\n\n  /**\n   * Install a plugin.\n   *\n   * Handles both sync and async `install()` methods automatically.\n   * Returns `this` for sync plugins and `Promise<this>` for async ones.\n   *\n   * @param plugin - Plugin to install\n   * @returns this (sync) or Promise<this> (async)\n   *\n   * @example\n   * ```typescript\n   * // Sync plugin\n   * app.plugin(loggerPlugin({ level: 'info' }));\n   *\n   * // Async plugin — just await it\n   * await app.plugin(databasePlugin({ uri: '...' }));\n   * ```\n   */\n  plugin(plugin: Plugin): this | Promise<this> {\n    this.assertNotRunning('plugin');\n    if (this.plugins.has(plugin.name)) {\n      throw new Error(`Plugin \"${plugin.name}\" is already installed`);\n    }\n\n    const result = plugin.install(this);\n\n    // If install() returned a promise, handle it asynchronously\n    if (result instanceof Promise) {\n      return result.then(() => {\n        this.plugins.set(plugin.name, plugin);\n        return this;\n      });\n    }\n\n    this.plugins.set(plugin.name, plugin);\n    return this;\n  }\n\n  /**\n   * Install a plugin asynchronously.\n   *\n   * @param plugin - Plugin to install\n   * @returns Promise that resolves when plugin is installed\n   *\n   * @deprecated Use `plugin()` instead — it handles both sync and async\n   * plugins automatically.\n   *\n   * @example\n   * ```typescript\n   * await app.plugin(new DatabasePlugin({ connectionString: '...' }));\n   * ```\n   */\n  async pluginAsync(plugin: Plugin): Promise<this> {\n    const result = this.plugin(plugin);\n    return result instanceof Promise ? result : Promise.resolve(result);\n  }\n\n  /**\n   * Get an installed plugin by name\n   *\n   * @param name - Plugin name\n   * @returns Plugin instance or undefined\n   */\n  // eslint-disable-next-line @typescript-eslint/no-unnecessary-type-parameters\n  getPlugin<T extends Plugin>(name: string): T | undefined {\n    return this.plugins.get(name) as T | undefined;\n  }\n\n  /**\n   * Check if a plugin is installed\n   */\n  hasPlugin(name: string): boolean {\n    return this.plugins.has(name);\n  }\n\n  // ===========================================================================\n  // Request Handler\n  // ===========================================================================\n\n  /**\n   * Create the request handler callback\n   *\n   * This is the function that adapters call to handle each request.\n   * It composes all middleware and returns a function that processes context.\n   *\n   * **Important:** The middleware stack is snapshot at call time.\n   * Middleware or plugins added after `callback()` will NOT take effect\n   * on the returned handler. Call `callback()` again to get a\n   * handler that includes subsequent registrations.\n   *\n   * @returns Request handler function\n   */\n  callback(): (ctx: Context) => Promise<void> {\n    const fn = compose(this.middlewareStack);\n\n    // Collect plugins that implement lifecycle hooks (once at build time)\n    // Validate that hook properties are actually callable functions\n    const hookPlugins = Array.from(this.plugins.values()).filter((p): p is PluginWithHooks => {\n      const hasHook =\n        'onRequest' in p || 'onResponse' in p || 'onError' in p || 'extendContext' in p;\n      if (!hasHook) return false;\n\n      // Runtime validation: ensure hook properties are functions\n      if ('onRequest' in p && typeof p.onRequest !== 'function') {\n        throw new TypeError(\n          `Plugin \"${p.name}\": onRequest must be a function, got ${typeof p.onRequest}`\n        );\n      }\n      if ('onResponse' in p && typeof p.onResponse !== 'function') {\n        throw new TypeError(\n          `Plugin \"${p.name}\": onResponse must be a function, got ${typeof p.onResponse}`\n        );\n      }\n      if ('onError' in p && typeof p.onError !== 'function') {\n        throw new TypeError(\n          `Plugin \"${p.name}\": onError must be a function, got ${typeof p.onError}`\n        );\n      }\n      if ('extendContext' in p && typeof p.extendContext !== 'function') {\n        throw new TypeError(\n          `Plugin \"${p.name}\": extendContext must be a function, got ${typeof p.extendContext}`\n        );\n      }\n      return true;\n    });\n\n    return async (ctx: Context): Promise<void> => {\n      try {\n        // Extend context and run onRequest hooks\n        for (const p of hookPlugins) {\n          if (p.extendContext) p.extendContext(ctx);\n          if (p.onRequest) await p.onRequest(ctx);\n        }\n\n        await fn(ctx);\n\n        // Run onResponse hooks — isolate errors so all hooks run\n        for (const p of hookPlugins) {\n          if (p.onResponse) {\n            try {\n              await p.onResponse(ctx);\n            } catch (hookError) {\n              this.logger.warn('Plugin onResponse hook threw:', {\n                plugin: p.name,\n                error: hookError,\n              });\n            }\n          }\n        }\n      } catch (error) {\n        // Run onError hooks\n        const err = error instanceof Error ? error : new Error(String(error));\n        for (const p of hookPlugins) {\n          if (p.onError) {\n            try {\n              await p.onError(err, ctx);\n            } catch (hookError) {\n              this.logger.warn('Plugin onError hook threw:', {\n                plugin: p.name,\n                error: hookError,\n              });\n            }\n          }\n        }\n        await this.handleError(error, ctx);\n      }\n    };\n  }\n\n  /**\n   * Handle errors - uses custom handler if set, otherwise default\n   */\n  private async handleError(error: unknown, ctx: Context): Promise<void> {\n    const err = error instanceof Error ? error : new Error(String(error));\n\n    // Use custom error handler if set\n    if (this._errorHandler) {\n      try {\n        await this._errorHandler(err, ctx);\n        return;\n      } catch (handlerError) {\n        // If custom handler throws, fall through to default handling\n        this.logger.error('Error handler threw:', handlerError);\n      }\n    }\n\n    // Default error handling\n    this.defaultErrorHandler(err, ctx);\n  }\n\n  /**\n   * Default error handler\n   *\n   * Uses the `expose` flag on errors (set by HttpError/NextRushError)\n   * to decide whether to include the error message in the response.\n   * 4xx errors expose messages by default; 5xx errors never do.\n   * This prevents leaking internal details (paths, SQL, stack info)\n   * regardless of environment.\n   */\n  private defaultErrorHandler(error: Error, ctx: Context): void {\n    // Always log non-production errors for DX\n    if (!this.isProduction) {\n      this.logger.error('Request error:', error);\n    }\n\n    // Determine status — clamp to valid error range (400-599)\n    const errorMeta = error as Error & { status?: number; expose?: boolean };\n    let status = 500;\n    if (typeof errorMeta.status === 'number') {\n      const raw = errorMeta.status;\n      status = raw >= 400 && raw < 600 ? raw : 500;\n    }\n    ctx.status = status;\n\n    // Use the `expose` flag to decide what message the client sees.\n    // HttpError/NextRushError set expose=true for 4xx, false for 5xx.\n    // Plain Error never exposes — prevents leaking internal details.\n    const expose = errorMeta.expose === true;\n    const message = expose ? error.message : 'Internal Server Error';\n\n    ctx.json({ error: message });\n  }\n\n  // ===========================================================================\n  // Lifecycle\n  // ===========================================================================\n\n  /**\n   * Mark app as running and freeze configuration.\n   *\n   * Called by adapters when the server starts listening. After this call,\n   * `use()`, `route()`, `plugin()`, and `pluginAsync()` will throw.\n   * This prevents unsafe middleware mutations while requests are in flight.\n   *\n   * To re-enable registration (e.g. for testing), call `close()` first.\n   */\n  start(): void {\n    this._isRunning = true;\n  }\n\n  /**\n   * Graceful shutdown\n   * Destroys all plugins that have a destroy method.\n   * Uses Promise.allSettled to ensure all plugins are destroyed\n   * even if some throw errors.\n   *\n   * @returns Array of errors from plugins that failed to destroy (empty on success)\n   */\n  async close(): Promise<Error[]> {\n    this._isRunning = false;\n\n    // Destroy plugins in reverse order using allSettled for resilience\n    const pluginArray = Array.from(this.plugins.values()).reverse();\n    const destroyablePlugins = pluginArray.filter(\n      (p): p is Plugin & { destroy: () => void | Promise<void> } => typeof p.destroy === 'function'\n    );\n\n    const destroyPromises = destroyablePlugins.map((p) =>\n      Promise.resolve()\n        .then(() => p.destroy())\n        .catch((err: unknown) => {\n          throw err instanceof Error ? err : new Error(String(err));\n        })\n    );\n\n    const results = await Promise.allSettled(destroyPromises);\n    this.plugins.clear();\n\n    return results\n      .filter((r): r is PromiseRejectedResult => r.status === 'rejected')\n      .map((r) => (r.reason instanceof Error ? r.reason : new Error(String(r.reason))));\n  }\n}\n\n/**\n * Create a new Application instance\n *\n * @param options - Application options\n * @returns New Application instance\n *\n * @example\n * ```typescript\n * const app = createApp();\n * const app = createApp({ env: 'production' });\n * ```\n */\nexport function createApp(options?: ApplicationOptions): Application {\n  return new Application(options);\n}\n"]}

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@nextrush/core",
+  "version": "3.0.0",
+  "description": "Core functionality for NextRush framework - Application, Context, Middleware",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "nextrush",
+    "framework",
+    "http",
+    "server",
+    "middleware",
+    "context"
+  ],
+  "author": {
+    "name": "Tanzim Hossain",
+    "email": "tanzimhossain2@gmail.com",
+    "url": "https://github.com/0xTanzim"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/0xTanzim/nextrush.git",
+    "directory": "packages/core"
+  },
+  "bugs": {
+    "url": "https://github.com/0xTanzim/nextrush/issues"
+  },
+  "homepage": "https://github.com/0xTanzim/nextrush#readme",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@nextrush/errors": "3.0.0",
+    "@nextrush/types": "3.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.2",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest --watch",
+    "test:coverage": "vitest --coverage",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ignore-pattern '**/__tests__/**'",
+    "lint:fix": "eslint src --fix --ignore-pattern '**/__tests__/**'",
+    "clean": "rm -rf dist .turbo"
+  }
+}