@flight-framework/core 0.2.6 → 0.3.1

package/dist/middleware/index.d.ts

@@ -2,9 +2,41 @@
  * Flight Middleware - Composable request/response handlers
  *
  * Framework-agnostic middleware system inspired by Koa/Hono.
+ * Provides primitives for building your own middleware solutions.
+ *
+ * @example
+ * ```typescript
+ * // Type-safe middleware with custom variables (Hono pattern)
+ * interface MyLocals {
+ *     user: { id: string; role: string };
+ *     requestId: string;
+ * }
+ *
+ * const authMiddleware: Middleware<MyLocals> = async (ctx, next) => {
+ *     ctx.locals.user = { id: '123', role: 'admin' };
+ *     await next();
+ * };
+ * ```
  */
-/** Request context passed through middleware chain */
-interface MiddlewareContext {
+/**
+ * Request context passed through middleware chain.
+ *
+ * Supports generic type parameter for type-safe locals (like Hono Variables).
+ *
+ * @typeParam TLocals - Type of the locals object for type-safe middleware data sharing
+ *
+ * @example
+ * ```typescript
+ * interface AppLocals {
+ *     user: User;
+ *     db: DatabaseClient;
+ * }
+ *
+ * const ctx: MiddlewareContext<AppLocals> = createContextFromRequest(request);
+ * ctx.locals.user = currentUser; // Type-safe!
+ * ```
+ */
+interface MiddlewareContext<TLocals extends Record<string, unknown> = Record<string, unknown>> {
     /** Request URL */
     url: URL;
     /** Request method */
@@ -17,8 +49,8 @@ interface MiddlewareContext {
     query: URLSearchParams;
     /** Parsed request body (if any) */
     body?: unknown;
-    /** Local data shared between middleware */
-    locals: Record<string, unknown>;
+    /** Local data shared between middleware - type-safe with generics */
+    locals: TLocals;
     /** Original request (platform-specific) */
     request?: Request;
     /** Response status code */
@@ -30,8 +62,12 @@ interface MiddlewareContext {
 }
 /** Next function to call the next middleware */
 type MiddlewareNext = () => Promise<void>;
-/** Middleware function signature */
-type Middleware = (ctx: MiddlewareContext, next: MiddlewareNext) => Promise<void> | void;
+/**
+ * Middleware function signature with optional typed locals.
+ *
+ * @typeParam TLocals - Type of the locals object for type-safe data sharing
+ */
+type Middleware<TLocals extends Record<string, unknown> = Record<string, unknown>> = (ctx: MiddlewareContext<TLocals>, next: MiddlewareNext) => Promise<void> | void;
 /** Middleware with optional path matching */
 interface MiddlewareDefinition {
     /** Path pattern to match (undefined = match all) */
@@ -58,13 +94,52 @@ declare function createMiddlewareChain(): MiddlewareChain;
 /**
  * CORS middleware factory
  */
-declare function cors(options?: {
-    origin?: string | string[] | ((origin: string) => boolean);
+/**
+ * CORS options for configuring cross-origin requests.
+ */
+interface CorsOptions {
+    /**
+     * Allowed origins. Can be:
+     * - '*' for any origin
+     * - A specific origin string
+     * - An array of allowed origins
+     * - A function that returns true if origin is allowed
+     * - An async function for dynamic origin validation
+     */
+    origin?: string | string[] | ((origin: string) => boolean | Promise<boolean>);
+    /** Allowed HTTP methods */
     methods?: string[];
+    /** Allowed headers */
     headers?: string[];
+    /** Whether to include credentials */
     credentials?: boolean;
+    /** Preflight cache duration in seconds */
     maxAge?: number;
-}): Middleware;
+    /** Exposed headers that can be accessed from the response */
+    exposeHeaders?: string[];
+}
+/**
+ * CORS middleware factory.
+ *
+ * Handles cross-origin resource sharing with best practices:
+ * - Adds Vary: Origin for dynamic origins (CDN compatibility)
+ * - Supports async origin validation
+ * - Proper preflight handling
+ *
+ * @example
+ * ```typescript
+ * // Allow specific origins
+ * chain.use(cors({ origin: ['https://app.example.com'] }));
+ *
+ * // Dynamic validation
+ * chain.use(cors({
+ *     origin: async (origin) => {
+ *         return await db.allowedOrigins.exists(origin);
+ *     }
+ * }));
+ * ```
+ */
+declare function cors(options?: CorsOptions): Middleware;
 /** Log levels in order of verbosity */
 type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
 /** Log format types */
@@ -136,6 +211,84 @@ declare function securityHeaders(options?: {
  * Compression middleware (requires implementation in adapter)
  */
 declare function compress(): Middleware;
+/**
+ * Error information passed to error handlers.
+ */
+interface ErrorInfo {
+    /** The original error */
+    error: Error;
+    /** HTTP status code (derived from error or default 500) */
+    status: number;
+    /** Error code for categorization */
+    code?: string;
+    /** Request context */
+    ctx: MiddlewareContext;
+    /** Request timestamp */
+    timestamp: string;
+}
+/**
+ * Error handler options.
+ */
+interface ErrorHandlerOptions {
+    /**
+     * Custom error handler function.
+     * Called when an error is caught. Can modify ctx to set response.
+     * If not provided, a default JSON response is sent.
+     */
+    onError?: (info: ErrorInfo) => void | Promise<void>;
+    /**
+     * Whether to expose error details in response.
+     * Set to false in production to hide internal error messages.
+     * @default false
+     */
+    expose?: boolean;
+    /**
+     * Default status code for errors without a status property.
+     * @default 500
+     */
+    defaultStatus?: number;
+    /**
+     * Emit error events for centralized logging (Koa pattern).
+     * Provide a function to receive error events.
+     */
+    emit?: (error: Error, ctx: MiddlewareContext) => void;
+}
+/**
+ * Error handler middleware factory.
+ *
+ * Provides centralized error handling following Koa best practices:
+ * - Catches all downstream errors
+ * - Sets appropriate status codes
+ * - Supports custom error handlers
+ * - Supports error event emission for logging
+ *
+ * Place this as one of the FIRST middleware in your chain.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - default JSON error response
+ * chain.use(errorHandler());
+ *
+ * // With custom handler
+ * chain.use(errorHandler({
+ *     onError: ({ error, status, ctx }) => {
+ *         ctx.status = status;
+ *         ctx.responseBody = JSON.stringify({
+ *             error: error.message,
+ *             code: 'SERVER_ERROR'
+ *         });
+ *     },
+ *     emit: (error, ctx) => {
+ *         logger.error('Request error:', error);
+ *         errorTracker.capture(error);
+ *     }
+ * }));
+ *
+ * // Production-safe (hide error details)
+ * chain.use(errorHandler({ expose: false }));
+ * ```
+ */
+declare function errorHandler(options?: ErrorHandlerOptions): Middleware;
 /**
  * Create a middleware context from a Web Request
  */
@@ -149,4 +302,4 @@ declare function createResponseFromContext(ctx: MiddlewareContext): Response;
  */
 declare function compose(...middlewares: Middleware[]): Middleware;
 
-export { type LogEntry, type LogFormat, type LogLevel, type LogWriter, type LoggerOptions, type Middleware, type MiddlewareChain, type MiddlewareContext, type MiddlewareDefinition, type MiddlewareNext, compose, compress, cors, createContextFromRequest, createMiddlewareChain, createResponseFromContext, logger, securityHeaders };
+export { type CorsOptions, type ErrorHandlerOptions, type ErrorInfo, type LogEntry, type LogFormat, type LogLevel, type LogWriter, type LoggerOptions, type Middleware, type MiddlewareChain, type MiddlewareContext, type MiddlewareDefinition, type MiddlewareNext, compose, compress, cors, createContextFromRequest, createMiddlewareChain, createResponseFromContext, errorHandler, logger, securityHeaders };

package/dist/middleware/index.js

@@ -1,3 +1,3 @@
-export { compose, compress, cors, createContextFromRequest, createMiddlewareChain, createResponseFromContext, logger, securityHeaders } from '../chunk-KWFX6WHG.js';
+export { compose, compress, cors, createContextFromRequest, createMiddlewareChain, createResponseFromContext, errorHandler, logger, securityHeaders } from '../chunk-OYF2OAKS.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/server/index.js

@@ -1,6 +1,6 @@
-export { createServer, getRuntime, isFlightServer } from '../chunk-LBYDTULN.js';
+export { createServer, getRuntime, isFlightServer } from '../chunk-ROJFQCGV.js';
 import '../chunk-IXMD5QH2.js';
 import '../chunk-GCQZ4FHI.js';
-import '../chunk-KWFX6WHG.js';
+import '../chunk-OYF2OAKS.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map