@flight-framework/core 0.2.4 → 0.2.6

package/README.md

@@ -0,0 +1,347 @@
+# @flight-framework/core
+
+Core primitives for Flight Framework - the agnostic full-stack framework with maximum flexibility and zero lock-in.
+
+## Features
+
+- **Multi-Render Mode** - SSR, SSG, ISR, and streaming in one unified API
+- **Framework Agnostic** - Works with React, Vue, Svelte, Solid, HTMX, and more
+- **File-Based Routing** - Automatic route discovery from filesystem
+- **Server Actions** - Type-safe server functions with form support
+- **Streaming SSR** - Out-of-order streaming with priority control
+- **Islands Architecture** - Partial hydration with any UI framework
+- **Caching System** - Pluggable cache adapters with deduplication
+- **Error Handling** - Structured errors with type guards and React integration
+- **Zero Lock-in** - Every component is replaceable
+
+## Installation
+
+```bash
+npm install @flight-framework/core
+```
+
+## Quick Start
+
+### Configuration
+
+```typescript
+// flight.config.ts
+import { defineConfig } from '@flight-framework/core';
+
+export default defineConfig({
+  server: {
+    port: 3000,
+  },
+  render: {
+    defaultMode: 'ssr',
+    streaming: true,
+  },
+});
+```
+
+### Create a Server
+
+```typescript
+import { createServer } from '@flight-framework/core';
+
+const server = createServer({
+  port: 3000,
+  routes: [
+    { path: '/', handler: homeHandler },
+    { path: '/api/*', handler: apiHandler },
+  ],
+});
+
+await server.start();
+```
+
+### File-Based Routing
+
+```typescript
+import { createFileRouter, scanRoutes } from '@flight-framework/core';
+
+const routes = await scanRoutes('./src/routes');
+const router = createFileRouter({ routes });
+
+// Routes are discovered automatically:
+// src/routes/index.page.tsx -> /
+// src/routes/about.page.tsx -> /about
+// src/routes/blog/[slug].page.tsx -> /blog/:slug
+```
+
+## Modules
+
+### Router
+
+```typescript
+import { createRouter } from '@flight-framework/core/router';
+
+const router = createRouter();
+router.add('GET', '/users/:id', userHandler);
+
+const match = router.match('GET', '/users/123');
+// { params: { id: '123' }, handler: userHandler }
+```
+
+### Cache
+
+```typescript
+import { createCache, memory, cached, dedupe } from '@flight-framework/core/cache';
+
+// Create a cache with memory adapter
+const cache = createCache({
+  adapter: memory(),
+  ttl: 60000,
+});
+
+// Cache function results
+const getUser = cached(
+  async (id: string) => fetchUser(id),
+  { ttl: 5000, key: (id) => `user:${id}` }
+);
+
+// Deduplicate concurrent requests
+const getData = dedupe(fetchData);
+```
+
+### Server Actions
+
+```typescript
+import { registerAction, executeAction, cookies } from '@flight-framework/core/actions';
+
+// Register a server action
+registerAction('createUser', async (formData: FormData) => {
+  const name = formData.get('name');
+  const user = await db.users.create({ name });
+  
+  cookies().set('user_id', user.id);
+  
+  return { success: true, user };
+});
+
+// Execute from client
+const result = await executeAction('createUser', formData);
+```
+
+### Streaming SSR
+
+```typescript
+import { 
+  createStreamingSSR, 
+  streamWithPriority 
+} from '@flight-framework/core/streaming';
+
+// Basic streaming
+const stream = await createStreamingSSR({
+  component: App,
+  props: { data },
+});
+
+// Priority-based streaming (out-of-order)
+const result = await streamWithPriority({
+  boundaries: [
+    { id: 'header', priority: 100, render: Header },
+    { id: 'sidebar', priority: 50, render: Sidebar },
+    { id: 'content', priority: 75, render: Content },
+  ],
+});
+```
+
+### Islands Architecture
+
+```typescript
+import { 
+  defineIsland, 
+  hydrateIslands,
+  createReactIslandAdapter 
+} from '@flight-framework/core/islands';
+
+// Define an island component
+const Counter = defineIsland({
+  name: 'counter',
+  component: CounterComponent,
+  hydrate: 'visible', // 'load' | 'visible' | 'idle' | 'interaction'
+});
+
+// Client-side hydration
+hydrateIslands({
+  adapter: createReactIslandAdapter(),
+});
+```
+
+### Middleware
+
+```typescript
+import { createMiddlewareChain } from '@flight-framework/core/middleware';
+
+const middleware = createMiddlewareChain([
+  async (ctx, next) => {
+    const start = Date.now();
+    await next();
+    console.log(`Request took ${Date.now() - start}ms`);
+  },
+  authMiddleware,
+  loggingMiddleware,
+]);
+```
+
+### Error Handling
+
+```typescript
+import { 
+  FlightError, 
+  createError, 
+  isFlightError,
+  createNotFound,
+  createForbidden,
+} from '@flight-framework/core/errors';
+
+// Create typed errors
+throw createNotFound('Page not found');
+throw createForbidden('Access denied');
+
+// Create custom errors
+throw createError({
+  statusCode: 422,
+  message: 'Validation failed',
+  data: { field: 'email', error: 'Invalid format' },
+});
+
+// Type guards
+if (isFlightError(error)) {
+  console.log(error.statusCode, error.digest);
+}
+```
+
+### React Integration
+
+```typescript
+import { ErrorProvider, useError, useFlightError } from '@flight-framework/core/react';
+
+// Wrap your app
+<ErrorProvider onError={console.error}>
+  <App />
+</ErrorProvider>
+
+// Use in components
+function MyComponent() {
+  const { error, clearError } = useFlightError();
+  
+  if (error) {
+    return <ErrorDisplay error={error} onRetry={clearError} />;
+  }
+  
+  return <Content />;
+}
+```
+
+### Metadata (SEO)
+
+```typescript
+import { renderMetadataToHead, type Metadata } from '@flight-framework/core';
+
+const metadata: Metadata = {
+  title: 'My Page',
+  description: 'Page description',
+  openGraph: {
+    title: 'OG Title',
+    image: '/og-image.png',
+  },
+};
+
+const headHtml = renderMetadataToHead(metadata);
+```
+
+### Route Rules (ISR/SSG)
+
+```typescript
+import { defineConfig } from '@flight-framework/core';
+
+export default defineConfig({
+  routeRules: {
+    '/': { prerender: true },
+    '/blog/**': { isr: 3600 },
+    '/api/**': { ssr: true },
+    '/static/**': { static: true },
+  },
+});
+```
+
+### Revalidation
+
+```typescript
+import { 
+  revalidatePath, 
+  revalidateTag,
+  createRevalidateHandler 
+} from '@flight-framework/core';
+
+// On-demand revalidation
+await revalidatePath('/blog/my-post');
+await revalidateTag('blog-posts');
+
+// Create revalidation API handler
+const handler = createRevalidateHandler({
+  secret: process.env.REVALIDATE_SECRET,
+});
+```
+
+## Environment Utilities
+
+```typescript
+import { 
+  isServer, 
+  isBrowser, 
+  isProduction,
+  isDevelopment 
+} from '@flight-framework/core/utils';
+
+if (isServer()) {
+  // Server-only code
+}
+
+if (isDevelopment()) {
+  console.log('Debug info');
+}
+```
+
+## Module Exports
+
+| Export | Description |
+|--------|-------------|
+| `@flight-framework/core` | Main entry with all primitives |
+| `@flight-framework/core/router` | Routing utilities |
+| `@flight-framework/core/cache` | Caching system |
+| `@flight-framework/core/server` | HTTP server |
+| `@flight-framework/core/render` | Rendering modes |
+| `@flight-framework/core/middleware` | Middleware chain |
+| `@flight-framework/core/actions` | Server actions |
+| `@flight-framework/core/streaming` | Streaming SSR |
+| `@flight-framework/core/islands` | Islands architecture |
+| `@flight-framework/core/errors` | Error handling |
+| `@flight-framework/core/react` | React integration |
+| `@flight-framework/core/rsc` | React Server Components |
+| `@flight-framework/core/config` | Configuration |
+| `@flight-framework/core/utils` | Environment utilities |
+
+## TypeScript
+
+Full TypeScript support with exported types for all APIs:
+
+```typescript
+import type {
+  FlightConfig,
+  Route,
+  RouteMatch,
+  Cache,
+  CacheAdapter,
+  Middleware,
+  FlightError,
+  Metadata,
+  StreamingHints,
+} from '@flight-framework/core';
+```
+
+## License
+
+MIT

package/dist/chunk-FSJNOPYE.js

@@ -0,0 +1,197 @@
+import { isProduction, isDevelopment } from './chunk-YHEVHRLH.js';
+
+// src/errors/index.ts
+var FlightError = class extends Error {
+  /** HTTP status code */
+  statusCode;
+  /** Short status message */
+  statusMessage;
+  /** Additional error data */
+  data;
+  /** Whether this is a fatal error (shows full-screen) */
+  fatal;
+  /** Unique digest for production error correlation */
+  digest;
+  constructor(options) {
+    super(options.message || options.statusMessage || "An error occurred");
+    this.name = "FlightError";
+    this.statusCode = options.statusCode;
+    this.statusMessage = options.statusMessage || getDefaultStatusMessage(options.statusCode);
+    this.data = options.data;
+    this.fatal = options.fatal ?? false;
+    if (isProduction()) {
+      this.digest = generateDigest();
+    }
+    if (options.cause) {
+      this.cause = options.cause;
+      if (options.cause.stack) {
+        this.stack = `${this.stack}
+Caused by: ${options.cause.stack}`;
+      }
+    }
+  }
+  /**
+   * Convert to plain object for serialization
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      statusCode: this.statusCode,
+      statusMessage: this.statusMessage,
+      data: this.data,
+      fatal: this.fatal,
+      digest: this.digest
+    };
+  }
+};
+var BadRequestError = class extends FlightError {
+  constructor(message, data) {
+    super({ statusCode: 400, message, data });
+    this.name = "BadRequestError";
+  }
+};
+var UnauthorizedError = class extends FlightError {
+  constructor(message, data) {
+    super({ statusCode: 401, message: message || "Unauthorized", data });
+    this.name = "UnauthorizedError";
+  }
+};
+var ForbiddenError = class extends FlightError {
+  constructor(message, data) {
+    super({ statusCode: 403, message: message || "Forbidden", data });
+    this.name = "ForbiddenError";
+  }
+};
+var NotFoundError = class extends FlightError {
+  constructor(message, data) {
+    super({ statusCode: 404, message: message || "Not Found", data });
+    this.name = "NotFoundError";
+  }
+};
+var InternalError = class extends FlightError {
+  constructor(message, data) {
+    super({ statusCode: 500, message: message || "Internal Server Error", data });
+    this.name = "InternalError";
+  }
+};
+function createError(options) {
+  if (typeof options === "string") {
+    return new FlightError({ statusCode: 500, message: options });
+  }
+  return new FlightError(options);
+}
+function notFound(message, data) {
+  throw new NotFoundError(message, data);
+}
+function forbidden(message, data) {
+  throw new ForbiddenError(message, data);
+}
+function unauthorized(message, data) {
+  throw new UnauthorizedError(message, data);
+}
+function showError(error) {
+  let flightError;
+  if (typeof error === "string") {
+    flightError = new FlightError({ statusCode: 500, message: error });
+  } else if (error instanceof FlightError) {
+    flightError = error;
+  } else {
+    flightError = new FlightError(error);
+  }
+  if (typeof window !== "undefined") {
+    window.__FLIGHT_ERROR__ = flightError;
+    window.dispatchEvent(new CustomEvent("flight:error", {
+      detail: flightError,
+      bubbles: true
+    }));
+  }
+}
+function clearError(options) {
+  if (typeof window !== "undefined") {
+    window.__FLIGHT_ERROR__ = null;
+    window.dispatchEvent(new CustomEvent("flight:error-clear", { bubbles: true }));
+    if (options?.redirect) {
+      window.location.href = options.redirect;
+    }
+  }
+}
+function getError() {
+  if (typeof window !== "undefined") {
+    return window.__FLIGHT_ERROR__ ?? null;
+  }
+  return null;
+}
+function isFlightError(error) {
+  return error instanceof FlightError;
+}
+function isNotFoundError(error) {
+  return error instanceof NotFoundError || isFlightError(error) && error.statusCode === 404;
+}
+function isForbiddenError(error) {
+  return error instanceof ForbiddenError || isFlightError(error) && error.statusCode === 403;
+}
+function isUnauthorizedError(error) {
+  return error instanceof UnauthorizedError || isFlightError(error) && error.statusCode === 401;
+}
+function getErrorStatusCode(error) {
+  if (isFlightError(error)) {
+    return error.statusCode;
+  }
+  return 500;
+}
+function createErrorResponse(error) {
+  const flightError = isFlightError(error) ? error : new InternalError(error instanceof Error ? error.message : "Unknown error");
+  return new Response(
+    JSON.stringify({
+      error: flightError.statusMessage,
+      message: flightError.message,
+      statusCode: flightError.statusCode,
+      digest: flightError.digest,
+      ...isDevelopment() && flightError.data ? { data: flightError.data } : {}
+    }),
+    {
+      status: flightError.statusCode,
+      headers: {
+        "Content-Type": "application/json"
+      }
+    }
+  );
+}
+function getDefaultStatusMessage(statusCode) {
+  const messages = {
+    400: "Bad Request",
+    401: "Unauthorized",
+    403: "Forbidden",
+    404: "Not Found",
+    405: "Method Not Allowed",
+    408: "Request Timeout",
+    409: "Conflict",
+    410: "Gone",
+    422: "Unprocessable Entity",
+    429: "Too Many Requests",
+    500: "Internal Server Error",
+    501: "Not Implemented",
+    502: "Bad Gateway",
+    503: "Service Unavailable",
+    504: "Gateway Timeout"
+  };
+  return messages[statusCode] || "Error";
+}
+function generateDigest() {
+  if (typeof crypto !== "undefined" && crypto.randomUUID) {
+    return crypto.randomUUID().slice(0, 8);
+  }
+  return Math.random().toString(36).slice(2, 10);
+}
+function wrapWithDigest(error) {
+  const wrapped = error;
+  if (!wrapped.digest) {
+    wrapped.digest = generateDigest();
+  }
+  return wrapped;
+}
+
+export { BadRequestError, FlightError, ForbiddenError, InternalError, NotFoundError, UnauthorizedError, clearError, createError, createErrorResponse, forbidden, getError, getErrorStatusCode, isFlightError, isForbiddenError, isNotFoundError, isUnauthorizedError, notFound, showError, unauthorized, wrapWithDigest };
+//# sourceMappingURL=chunk-FSJNOPYE.js.map
+//# sourceMappingURL=chunk-FSJNOPYE.js.map

package/dist/chunk-FSJNOPYE.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors/index.ts"],"names":[],"mappings":"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","file":"chunk-FSJNOPYE.js","sourcesContent":["/**\r\n * @flight-framework/core - Error Handling\r\n * \r\n * Comprehensive error handling utilities for Flight applications.\r\n * All utilities are OPTIONAL - developers can use their own error handling.\r\n * \r\n * Philosophy: Flight OFFERS these utilities, but never IMPOSES them.\r\n * Using throw new Error() works perfectly fine - this is your choice.\r\n */\r\n\r\nimport { isProduction, isDevelopment } from '../utils/env.js';\r\n\r\n// ============================================================================\r\n// Types\r\n// ============================================================================\r\n\r\n/**\r\n * Options for creating a Flight error\r\n */\r\nexport interface FlightErrorOptions {\r\n    /** HTTP status code */\r\n    statusCode: number;\r\n    /** Short status message (e.g., \"Not Found\") */\r\n    statusMessage?: string;\r\n    /** Detailed error message */\r\n    message?: string;\r\n    /** Additional data to include with the error */\r\n    data?: Record<string, unknown>;\r\n    /** If true, shows full-screen error page instead of error boundary */\r\n    fatal?: boolean;\r\n    /** Original error that caused this error */\r\n    cause?: Error;\r\n}\r\n\r\n/**\r\n * Extended error props with digest for production error correlation\r\n */\r\nexport interface FlightErrorProps {\r\n    /** The error object */\r\n    error: Error & { digest?: string };\r\n    /** Function to attempt recovery by re-rendering */\r\n    reset: () => void;\r\n}\r\n\r\n/**\r\n * Reset details provided to onReset callback\r\n */\r\nexport interface ResetDetails {\r\n    /** Reason for the reset */\r\n    reason: 'imperative-api' | 'keys';\r\n    /** Arguments passed to resetErrorBoundary (if imperative) */\r\n    args?: unknown[];\r\n    /** Previous resetKeys values (if keys changed) */\r\n    prev?: unknown[];\r\n    /** New resetKeys values (if keys changed) */\r\n    next?: unknown[];\r\n}\r\n\r\n/**\r\n * Options for error boundary behavior\r\n */\r\nexport interface ErrorBoundaryOptions {\r\n    /** Keys that trigger automatic reset when changed */\r\n    resetKeys?: unknown[];\r\n    /** Callback when error boundary resets */\r\n    onReset?: (details: ResetDetails) => void;\r\n    /** Callback when error is caught */\r\n    onError?: (error: Error, info: { componentStack?: string }) => void;\r\n}\r\n\r\n// ============================================================================\r\n// FlightError Class\r\n// ============================================================================\r\n\r\n/**\r\n * Custom error class with status code and metadata support.\r\n * \r\n * You can use this class or regular Error - Flight handles both.\r\n * \r\n * @example\r\n * ```typescript\r\n * throw new FlightError({\r\n *     statusCode: 404,\r\n *     message: 'User not found',\r\n *     data: { userId: '123' }\r\n * });\r\n * ```\r\n */\r\nexport class FlightError extends Error {\r\n    /** HTTP status code */\r\n    readonly statusCode: number;\r\n    /** Short status message */\r\n    readonly statusMessage: string;\r\n    /** Additional error data */\r\n    readonly data?: Record<string, unknown>;\r\n    /** Whether this is a fatal error (shows full-screen) */\r\n    readonly fatal: boolean;\r\n    /** Unique digest for production error correlation */\r\n    readonly digest?: string;\r\n\r\n    constructor(options: FlightErrorOptions) {\r\n        super(options.message || options.statusMessage || 'An error occurred');\r\n\r\n        this.name = 'FlightError';\r\n        this.statusCode = options.statusCode;\r\n        this.statusMessage = options.statusMessage || getDefaultStatusMessage(options.statusCode);\r\n        this.data = options.data;\r\n        this.fatal = options.fatal ?? false;\r\n\r\n        // Generate digest in production for error correlation\r\n        // Using typeof check for SSR/browser compatibility\r\n        if (isProduction()) {\r\n            this.digest = generateDigest();\r\n        }\r\n\r\n        // Preserve original error stack if cause provided\r\n        if (options.cause) {\r\n            this.cause = options.cause;\r\n            if (options.cause.stack) {\r\n                this.stack = `${this.stack}\\nCaused by: ${options.cause.stack}`;\r\n            }\r\n        }\r\n    }\r\n\r\n    /**\r\n     * Convert to plain object for serialization\r\n     */\r\n    toJSON(): Record<string, unknown> {\r\n        return {\r\n            name: this.name,\r\n            message: this.message,\r\n            statusCode: this.statusCode,\r\n            statusMessage: this.statusMessage,\r\n            data: this.data,\r\n            fatal: this.fatal,\r\n            digest: this.digest,\r\n        };\r\n    }\r\n}\r\n\r\n// ============================================================================\r\n// HTTP Error Classes (Convenience)\r\n// ============================================================================\r\n\r\n/**\r\n * 400 Bad Request error\r\n */\r\nexport class BadRequestError extends FlightError {\r\n    constructor(message?: string, data?: Record<string, unknown>) {\r\n        super({ statusCode: 400, message, data });\r\n        this.name = 'BadRequestError';\r\n    }\r\n}\r\n\r\n/**\r\n * 401 Unauthorized error\r\n */\r\nexport class UnauthorizedError extends FlightError {\r\n    constructor(message?: string, data?: Record<string, unknown>) {\r\n        super({ statusCode: 401, message: message || 'Unauthorized', data });\r\n        this.name = 'UnauthorizedError';\r\n    }\r\n}\r\n\r\n/**\r\n * 403 Forbidden error\r\n */\r\nexport class ForbiddenError extends FlightError {\r\n    constructor(message?: string, data?: Record<string, unknown>) {\r\n        super({ statusCode: 403, message: message || 'Forbidden', data });\r\n        this.name = 'ForbiddenError';\r\n    }\r\n}\r\n\r\n/**\r\n * 404 Not Found error\r\n */\r\nexport class NotFoundError extends FlightError {\r\n    constructor(message?: string, data?: Record<string, unknown>) {\r\n        super({ statusCode: 404, message: message || 'Not Found', data });\r\n        this.name = 'NotFoundError';\r\n    }\r\n}\r\n\r\n/**\r\n * 500 Internal Server Error\r\n */\r\nexport class InternalError extends FlightError {\r\n    constructor(message?: string, data?: Record<string, unknown>) {\r\n        super({ statusCode: 500, message: message || 'Internal Server Error', data });\r\n        this.name = 'InternalError';\r\n    }\r\n}\r\n\r\n// ============================================================================\r\n// Factory Functions\r\n// ============================================================================\r\n\r\n/**\r\n * Create a FlightError with the specified options.\r\n * \r\n * This is a convenience function - you can also use `new FlightError()` directly\r\n * or just `throw new Error()` - Flight handles all cases.\r\n * \r\n * @example\r\n * ```typescript\r\n * // With full options\r\n * throw createError({\r\n *     statusCode: 404,\r\n *     message: 'Product not found',\r\n *     data: { productId: 'abc123' }\r\n * });\r\n * \r\n * // Simple string shorthand (becomes 500 error)\r\n * throw createError('Something went wrong');\r\n * ```\r\n */\r\nexport function createError(options: FlightErrorOptions | string): FlightError {\r\n    if (typeof options === 'string') {\r\n        return new FlightError({ statusCode: 500, message: options });\r\n    }\r\n    return new FlightError(options);\r\n}\r\n\r\n/**\r\n * Create a 404 Not Found error.\r\n * Convenience function equivalent to `createError({ statusCode: 404, ... })`.\r\n * \r\n * @example\r\n * ```typescript\r\n * if (!user) {\r\n *     throw notFound('User not found');\r\n * }\r\n * ```\r\n */\r\nexport function notFound(message?: string, data?: Record<string, unknown>): never {\r\n    throw new NotFoundError(message, data);\r\n}\r\n\r\n/**\r\n * Create a 403 Forbidden error.\r\n * \r\n * @example\r\n * ```typescript\r\n * if (!user.isAdmin) {\r\n *     throw forbidden('Admin access required');\r\n * }\r\n * ```\r\n */\r\nexport function forbidden(message?: string, data?: Record<string, unknown>): never {\r\n    throw new ForbiddenError(message, data);\r\n}\r\n\r\n/**\r\n * Create a 401 Unauthorized error.\r\n * \r\n * @example\r\n * ```typescript\r\n * if (!session) {\r\n *     throw unauthorized('Please log in to continue');\r\n * }\r\n * ```\r\n */\r\nexport function unauthorized(message?: string, data?: Record<string, unknown>): never {\r\n    throw new UnauthorizedError(message, data);\r\n}\r\n\r\n// ============================================================================\r\n// Error State Management (Client-Side)\r\n// ============================================================================\r\n\r\n// Global error state for client-side\r\ndeclare global {\r\n    interface Window {\r\n        __FLIGHT_ERROR__?: FlightError | null;\r\n    }\r\n}\r\n\r\n/**\r\n * Programmatically show an error page.\r\n * \r\n * This triggers the nearest error boundary or navigates to the error page.\r\n * Only works on the client side.\r\n * \r\n * @example\r\n * ```typescript\r\n * // Show error with full options\r\n * showError({\r\n *     statusCode: 500,\r\n *     message: 'Connection lost'\r\n * });\r\n * \r\n * // Simple string shorthand\r\n * showError('Something went wrong');\r\n * ```\r\n */\r\nexport function showError(error: FlightErrorOptions | FlightError | string): void {\r\n    let flightError: FlightError;\r\n\r\n    if (typeof error === 'string') {\r\n        flightError = new FlightError({ statusCode: 500, message: error });\r\n    } else if (error instanceof FlightError) {\r\n        flightError = error;\r\n    } else {\r\n        flightError = new FlightError(error);\r\n    }\r\n\r\n    // Client-side: dispatch custom event for error boundaries\r\n    if (typeof window !== 'undefined') {\r\n        window.__FLIGHT_ERROR__ = flightError;\r\n        window.dispatchEvent(new CustomEvent('flight:error', {\r\n            detail: flightError,\r\n            bubbles: true\r\n        }));\r\n    }\r\n}\r\n\r\n/**\r\n * Clear the current error state and optionally redirect.\r\n * \r\n * Use this to dismiss an error and return to normal state.\r\n * \r\n * @example\r\n * ```typescript\r\n * // Just clear the error\r\n * clearError();\r\n * \r\n * // Clear and redirect to home\r\n * clearError({ redirect: '/' });\r\n * ```\r\n */\r\nexport function clearError(options?: { redirect?: string }): void {\r\n    if (typeof window !== 'undefined') {\r\n        window.__FLIGHT_ERROR__ = null;\r\n        window.dispatchEvent(new CustomEvent('flight:error-clear', { bubbles: true }));\r\n\r\n        if (options?.redirect) {\r\n            window.location.href = options.redirect;\r\n        }\r\n    }\r\n}\r\n\r\n/**\r\n * Get the current error from global state.\r\n * Returns null if no error is active.\r\n */\r\nexport function getError(): FlightError | null {\r\n    if (typeof window !== 'undefined') {\r\n        return window.__FLIGHT_ERROR__ ?? null;\r\n    }\r\n    return null;\r\n}\r\n\r\n// ============================================================================\r\n// Type Guards\r\n// ============================================================================\r\n\r\n/**\r\n * Check if an error is a FlightError\r\n */\r\nexport function isFlightError(error: unknown): error is FlightError {\r\n    return error instanceof FlightError;\r\n}\r\n\r\n/**\r\n * Check if an error is a NotFoundError (404)\r\n */\r\nexport function isNotFoundError(error: unknown): error is NotFoundError {\r\n    return error instanceof NotFoundError ||\r\n        (isFlightError(error) && error.statusCode === 404);\r\n}\r\n\r\n/**\r\n * Check if an error is a ForbiddenError (403)\r\n */\r\nexport function isForbiddenError(error: unknown): error is ForbiddenError {\r\n    return error instanceof ForbiddenError ||\r\n        (isFlightError(error) && error.statusCode === 403);\r\n}\r\n\r\n/**\r\n * Check if an error is an UnauthorizedError (401)\r\n */\r\nexport function isUnauthorizedError(error: unknown): error is UnauthorizedError {\r\n    return error instanceof UnauthorizedError ||\r\n        (isFlightError(error) && error.statusCode === 401);\r\n}\r\n\r\n/**\r\n * Get the status code from any error.\r\n * Returns 500 for non-FlightError errors.\r\n */\r\nexport function getErrorStatusCode(error: unknown): number {\r\n    if (isFlightError(error)) {\r\n        return error.statusCode;\r\n    }\r\n    return 500;\r\n}\r\n\r\n// ============================================================================\r\n// Response Helpers\r\n// ============================================================================\r\n\r\n/**\r\n * Create an error Response from a FlightError.\r\n * \r\n * @example\r\n * ```typescript\r\n * try {\r\n *     // ... some operation\r\n * } catch (error) {\r\n *     return createErrorResponse(error);\r\n * }\r\n * ```\r\n */\r\nexport function createErrorResponse(error: unknown): Response {\r\n    const flightError = isFlightError(error)\r\n        ? error\r\n        : new InternalError(error instanceof Error ? error.message : 'Unknown error');\r\n\r\n    return new Response(\r\n        JSON.stringify({\r\n            error: flightError.statusMessage,\r\n            message: flightError.message,\r\n            statusCode: flightError.statusCode,\r\n            digest: flightError.digest,\r\n            ...(isDevelopment() && flightError.data\r\n                ? { data: flightError.data }\r\n                : {}),\r\n        }),\r\n        {\r\n            status: flightError.statusCode,\r\n            headers: {\r\n                'Content-Type': 'application/json',\r\n            },\r\n        }\r\n    );\r\n}\r\n\r\n// ============================================================================\r\n// Utilities\r\n// ============================================================================\r\n\r\n/**\r\n * Get default status message for HTTP status code\r\n */\r\nfunction getDefaultStatusMessage(statusCode: number): string {\r\n    const messages: Record<number, string> = {\r\n        400: 'Bad Request',\r\n        401: 'Unauthorized',\r\n        403: 'Forbidden',\r\n        404: 'Not Found',\r\n        405: 'Method Not Allowed',\r\n        408: 'Request Timeout',\r\n        409: 'Conflict',\r\n        410: 'Gone',\r\n        422: 'Unprocessable Entity',\r\n        429: 'Too Many Requests',\r\n        500: 'Internal Server Error',\r\n        501: 'Not Implemented',\r\n        502: 'Bad Gateway',\r\n        503: 'Service Unavailable',\r\n        504: 'Gateway Timeout',\r\n    };\r\n    return messages[statusCode] || 'Error';\r\n}\r\n\r\n/**\r\n * Generate a short digest for error correlation.\r\n * Used in production to correlate client errors with server logs\r\n * without exposing stack traces.\r\n */\r\nfunction generateDigest(): string {\r\n    // Use crypto if available (Node.js, modern browsers)\r\n    if (typeof crypto !== 'undefined' && crypto.randomUUID) {\r\n        return crypto.randomUUID().slice(0, 8);\r\n    }\r\n    // Fallback for older environments\r\n    return Math.random().toString(36).slice(2, 10);\r\n}\r\n\r\n/**\r\n * Wrap an error with a digest if it doesn't have one.\r\n * Useful for adding correlation IDs to third-party errors.\r\n */\r\nexport function wrapWithDigest<T extends Error>(error: T): T & { digest: string } {\r\n    const wrapped = error as T & { digest: string };\r\n    if (!wrapped.digest) {\r\n        wrapped.digest = generateDigest();\r\n    }\r\n    return wrapped;\r\n}\r\n"]}

package/dist/{chunk-VOBQDQKX.js → chunk-LBYDTULN.js}

@@ -1,6 +1,6 @@
+import { resolveConfig } from './chunk-IXMD5QH2.js';
 import { createRouter } from './chunk-GCQZ4FHI.js';
 import { createMiddlewareChain, createContextFromRequest, createResponseFromContext } from './chunk-KWFX6WHG.js';
-import { resolveConfig } from './chunk-IXMD5QH2.js';
 
 // src/server/index.ts
 function detectRuntime() {
@@ -219,5 +219,5 @@ function getRuntime() {
 }
 
 export { createServer, getRuntime, isFlightServer };
-//# sourceMappingURL=chunk-VOBQDQKX.js.map
-//# sourceMappingURL=chunk-VOBQDQKX.js.map
+//# sourceMappingURL=chunk-LBYDTULN.js.map
+//# sourceMappingURL=chunk-LBYDTULN.js.map