@nextrush/core 3.0.0

package/dist/index.d.ts

@@ -0,0 +1,388 @@
+import { Middleware, Context, Plugin, Next } from '@nextrush/types';
+export { ContentType, Context, ContextState, HttpMethod, HttpStatus, HttpStatusCode, Middleware, Next, Plugin, PluginWithHooks, QueryParams, RouteHandler, RouteParams } from '@nextrush/types';
+export { BadRequestError, ForbiddenError, HttpError, InternalServerError, NextRushError, NotFoundError, UnauthorizedError, createError as createHttpError } from '@nextrush/errors';
+
+/**
+ * @nextrush/core - Application Class
+ *
+ * The Application class is the main entry point for NextRush.
+ * It manages middleware registration and plugin installation.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Error handler function type
+ */
+type ErrorHandler = (error: Error, ctx: Context) => void | Promise<void>;
+/**
+ * Logger interface for pluggable logging
+ */
+interface Logger {
+    error(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    debug(...args: unknown[]): void;
+}
+/**
+ * Application options
+ */
+interface ApplicationOptions {
+    /**
+     * Environment mode
+     * @default 'development'
+     */
+    env?: 'development' | 'production' | 'test';
+    /**
+     * Whether to use proxy headers (X-Forwarded-For, etc.)
+     * @default false
+     */
+    proxy?: boolean;
+    /**
+     * Custom logger. Defaults to no-op (silent).
+     *
+     * @remarks
+     * Pass `console` for quick development logging:
+     * ```ts
+     * const app = createApp({ logger: console });
+     * ```
+     *
+     * For production, provide a structured logger (e.g. pino, winston)
+     * that implements the {@link Logger} interface.
+     *
+     * Adapters and internal hooks use `app.logger` — configuring it here
+     * ensures consistent logging across the framework.
+     */
+    logger?: Logger;
+}
+/**
+ * Listener callback type
+ */
+type ListenCallback = () => void;
+/**
+ * Routable interface - any object with routes() method
+ * This allows mounting Router instances without circular dependency
+ */
+interface Routable {
+    routes(): Middleware;
+}
+/**
+ * The Application class
+ *
+ * @example
+ * ```typescript
+ * const app = createApp();
+ *
+ * app.use(async (ctx) => {
+ *   ctx.json({ message: 'Hello World' });
+ * });
+ *
+ * // Mount with an adapter
+ * listen(app, { port: 3000 });
+ * ```
+ */
+declare class Application {
+    /**
+     * Middleware stack
+     */
+    private readonly middlewareStack;
+    /**
+     * Installed plugins
+     */
+    private readonly plugins;
+    /**
+     * Custom error handler
+     */
+    private _errorHandler;
+    /**
+     * Pluggable logger
+     */
+    readonly logger: Logger;
+    /**
+     * Application options
+     */
+    readonly options: ApplicationOptions;
+    /**
+     * Whether the app is running
+     */
+    private _isRunning;
+    constructor(options?: ApplicationOptions);
+    /**
+     * Check if running in production
+     */
+    get isProduction(): boolean;
+    /**
+     * Check if app is running
+     */
+    get isRunning(): boolean;
+    /**
+     * Get middleware count
+     */
+    get middlewareCount(): number;
+    /**
+     * Throws if the app is already running.
+     * Prevents configuration mutations after start().
+     */
+    private assertNotRunning;
+    /**
+     * 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: Middleware[]): this;
+    /**
+     * 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: string, router: Routable): this;
+    /**
+     * 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: ErrorHandler): 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: ErrorHandler): this;
+    /**
+     * 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: Plugin): this | Promise<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: '...' }));
+     * ```
+     */
+    pluginAsync(plugin: Plugin): Promise<this>;
+    /**
+     * Get an installed plugin by name
+     *
+     * @param name - Plugin name
+     * @returns Plugin instance or undefined
+     */
+    getPlugin<T extends Plugin>(name: string): T | undefined;
+    /**
+     * Check if a plugin is installed
+     */
+    hasPlugin(name: string): boolean;
+    /**
+     * 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(): (ctx: Context) => Promise<void>;
+    /**
+     * Handle errors - uses custom handler if set, otherwise default
+     */
+    private handleError;
+    /**
+     * 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.
+     */
+    private defaultErrorHandler;
+    /**
+     * 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(): void;
+    /**
+     * 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)
+     */
+    close(): Promise<Error[]>;
+}
+/**
+ * Create a new Application instance
+ *
+ * @param options - Application options
+ * @returns New Application instance
+ *
+ * @example
+ * ```typescript
+ * const app = createApp();
+ * const app = createApp({ env: 'production' });
+ * ```
+ */
+declare function createApp(options?: ApplicationOptions): Application;
+
+/**
+ * @nextrush/core - Middleware Composition
+ *
+ * Koa-style middleware composition with async/await support.
+ * This is the heart of the middleware pipeline.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Composed middleware handler - can be called with just context
+ */
+type ComposedMiddleware = (ctx: Context, next?: Next) => Promise<void>;
+/**
+ * Options for middleware composition
+ */
+interface ComposeOptions {
+    /**
+     * Warn when a middleware sends a response AND calls next().
+     * Enabled by default in non-production environments.
+     * @default process.env.NODE_ENV !== 'production'
+     */
+    warnDoubleResponse?: boolean;
+}
+/**
+ * Compose multiple middleware functions into a single middleware.
+ *
+ * Executes middleware in order, each middleware can call `await next()`
+ * to pass control to the next middleware and wait for it to complete.
+ *
+ * @param middleware - Array of middleware functions to compose
+ * @param options - Composition options
+ * @returns Single composed middleware function
+ *
+ * @example
+ * ```typescript
+ * const composed = compose([
+ *   async (ctx, next) => {
+ *     console.log('1 - before');
+ *     await next();
+ *     console.log('1 - after');
+ *   },
+ *   async (ctx, next) => {
+ *     console.log('2 - before');
+ *     await next();
+ *     console.log('2 - after');
+ *   },
+ * ]);
+ *
+ * // Output:
+ * // 1 - before
+ * // 2 - before
+ * // 2 - after
+ * // 1 - after
+ * ```
+ */
+declare function compose(middleware: Middleware[], options?: ComposeOptions): ComposedMiddleware;
+/**
+ * Check if a function is a valid middleware
+ */
+declare function isMiddleware(fn: unknown): fn is Middleware;
+/**
+ * Flatten nested middleware arrays with type validation.
+ * Uses bounded depth (10 levels) to prevent V8 deoptimization on deeply nested arrays.
+ */
+declare function flattenMiddleware(arr: (Middleware | Middleware[])[]): Middleware[];
+
+export { Application, type ApplicationOptions, type ComposeOptions, type ComposedMiddleware, type ErrorHandler, type ListenCallback, type Logger, type Routable, compose, createApp, flattenMiddleware, isMiddleware };