@flightdev/core 0.6.7

package/dist/errors/index.d.ts

@@ -0,0 +1,267 @@
+/**
+ * @flightdev/core - Error Handling
+ *
+ * Comprehensive error handling utilities for Flight applications.
+ * All utilities are OPTIONAL - developers can use their own error handling.
+ *
+ * Philosophy: Flight OFFERS these utilities, but never IMPOSES them.
+ * Using throw new Error() works perfectly fine - this is your choice.
+ */
+/**
+ * Options for creating a Flight error
+ */
+interface FlightErrorOptions {
+    /** HTTP status code */
+    statusCode: number;
+    /** Short status message (e.g., "Not Found") */
+    statusMessage?: string;
+    /** Detailed error message */
+    message?: string;
+    /** Additional data to include with the error */
+    data?: Record<string, unknown>;
+    /** If true, shows full-screen error page instead of error boundary */
+    fatal?: boolean;
+    /** Original error that caused this error */
+    cause?: Error;
+}
+/**
+ * Extended error props with digest for production error correlation
+ */
+interface FlightErrorProps {
+    /** The error object */
+    error: Error & {
+        digest?: string;
+    };
+    /** Function to attempt recovery by re-rendering */
+    reset: () => void;
+}
+/**
+ * Reset details provided to onReset callback
+ */
+interface ResetDetails {
+    /** Reason for the reset */
+    reason: 'imperative-api' | 'keys';
+    /** Arguments passed to resetErrorBoundary (if imperative) */
+    args?: unknown[];
+    /** Previous resetKeys values (if keys changed) */
+    prev?: unknown[];
+    /** New resetKeys values (if keys changed) */
+    next?: unknown[];
+}
+/**
+ * Options for error boundary behavior
+ */
+interface ErrorBoundaryOptions {
+    /** Keys that trigger automatic reset when changed */
+    resetKeys?: unknown[];
+    /** Callback when error boundary resets */
+    onReset?: (details: ResetDetails) => void;
+    /** Callback when error is caught */
+    onError?: (error: Error, info: {
+        componentStack?: string;
+    }) => void;
+}
+/**
+ * Custom error class with status code and metadata support.
+ *
+ * You can use this class or regular Error - Flight handles both.
+ *
+ * @example
+ * ```typescript
+ * throw new FlightError({
+ *     statusCode: 404,
+ *     message: 'User not found',
+ *     data: { userId: '123' }
+ * });
+ * ```
+ */
+declare class FlightError extends Error {
+    /** HTTP status code */
+    readonly statusCode: number;
+    /** Short status message */
+    readonly statusMessage: string;
+    /** Additional error data */
+    readonly data?: Record<string, unknown>;
+    /** Whether this is a fatal error (shows full-screen) */
+    readonly fatal: boolean;
+    /** Unique digest for production error correlation */
+    readonly digest?: string;
+    constructor(options: FlightErrorOptions);
+    /**
+     * Convert to plain object for serialization
+     */
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * 400 Bad Request error
+ */
+declare class BadRequestError extends FlightError {
+    constructor(message?: string, data?: Record<string, unknown>);
+}
+/**
+ * 401 Unauthorized error
+ */
+declare class UnauthorizedError extends FlightError {
+    constructor(message?: string, data?: Record<string, unknown>);
+}
+/**
+ * 403 Forbidden error
+ */
+declare class ForbiddenError extends FlightError {
+    constructor(message?: string, data?: Record<string, unknown>);
+}
+/**
+ * 404 Not Found error
+ */
+declare class NotFoundError extends FlightError {
+    constructor(message?: string, data?: Record<string, unknown>);
+}
+/**
+ * 500 Internal Server Error
+ */
+declare class InternalError extends FlightError {
+    constructor(message?: string, data?: Record<string, unknown>);
+}
+/**
+ * Create a FlightError with the specified options.
+ *
+ * This is a convenience function - you can also use `new FlightError()` directly
+ * or just `throw new Error()` - Flight handles all cases.
+ *
+ * @example
+ * ```typescript
+ * // With full options
+ * throw createError({
+ *     statusCode: 404,
+ *     message: 'Product not found',
+ *     data: { productId: 'abc123' }
+ * });
+ *
+ * // Simple string shorthand (becomes 500 error)
+ * throw createError('Something went wrong');
+ * ```
+ */
+declare function createError(options: FlightErrorOptions | string): FlightError;
+/**
+ * Create a 404 Not Found error.
+ * Convenience function equivalent to `createError({ statusCode: 404, ... })`.
+ *
+ * @example
+ * ```typescript
+ * if (!user) {
+ *     throw notFound('User not found');
+ * }
+ * ```
+ */
+declare function notFound(message?: string, data?: Record<string, unknown>): never;
+/**
+ * Create a 403 Forbidden error.
+ *
+ * @example
+ * ```typescript
+ * if (!user.isAdmin) {
+ *     throw forbidden('Admin access required');
+ * }
+ * ```
+ */
+declare function forbidden(message?: string, data?: Record<string, unknown>): never;
+/**
+ * Create a 401 Unauthorized error.
+ *
+ * @example
+ * ```typescript
+ * if (!session) {
+ *     throw unauthorized('Please log in to continue');
+ * }
+ * ```
+ */
+declare function unauthorized(message?: string, data?: Record<string, unknown>): never;
+declare global {
+    interface Window {
+        __FLIGHT_ERROR__?: FlightError | null;
+    }
+}
+/**
+ * Programmatically show an error page.
+ *
+ * This triggers the nearest error boundary or navigates to the error page.
+ * Only works on the client side.
+ *
+ * @example
+ * ```typescript
+ * // Show error with full options
+ * showError({
+ *     statusCode: 500,
+ *     message: 'Connection lost'
+ * });
+ *
+ * // Simple string shorthand
+ * showError('Something went wrong');
+ * ```
+ */
+declare function showError(error: FlightErrorOptions | FlightError | string): void;
+/**
+ * Clear the current error state and optionally redirect.
+ *
+ * Use this to dismiss an error and return to normal state.
+ *
+ * @example
+ * ```typescript
+ * // Just clear the error
+ * clearError();
+ *
+ * // Clear and redirect to home
+ * clearError({ redirect: '/' });
+ * ```
+ */
+declare function clearError(options?: {
+    redirect?: string;
+}): void;
+/**
+ * Get the current error from global state.
+ * Returns null if no error is active.
+ */
+declare function getError(): FlightError | null;
+/**
+ * Check if an error is a FlightError
+ */
+declare function isFlightError(error: unknown): error is FlightError;
+/**
+ * Check if an error is a NotFoundError (404)
+ */
+declare function isNotFoundError(error: unknown): error is NotFoundError;
+/**
+ * Check if an error is a ForbiddenError (403)
+ */
+declare function isForbiddenError(error: unknown): error is ForbiddenError;
+/**
+ * Check if an error is an UnauthorizedError (401)
+ */
+declare function isUnauthorizedError(error: unknown): error is UnauthorizedError;
+/**
+ * Get the status code from any error.
+ * Returns 500 for non-FlightError errors.
+ */
+declare function getErrorStatusCode(error: unknown): number;
+/**
+ * Create an error Response from a FlightError.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *     // ... some operation
+ * } catch (error) {
+ *     return createErrorResponse(error);
+ * }
+ * ```
+ */
+declare function createErrorResponse(error: unknown): Response;
+/**
+ * Wrap an error with a digest if it doesn't have one.
+ * Useful for adding correlation IDs to third-party errors.
+ */
+declare function wrapWithDigest<T extends Error>(error: T): T & {
+    digest: string;
+};
+
+export { BadRequestError, type ErrorBoundaryOptions, FlightError, type FlightErrorOptions, type FlightErrorProps, ForbiddenError, InternalError, NotFoundError, type ResetDetails, UnauthorizedError, clearError, createError, createErrorResponse, forbidden, getError, getErrorStatusCode, isFlightError, isForbiddenError, isNotFoundError, isUnauthorizedError, notFound, showError, unauthorized, wrapWithDigest };

package/dist/errors/index.js

@@ -0,0 +1,4 @@
+export { BadRequestError, FlightError, ForbiddenError, InternalError, NotFoundError, UnauthorizedError, clearError, createError, createErrorResponse, forbidden, getError, getErrorStatusCode, isFlightError, isForbiddenError, isNotFoundError, isUnauthorizedError, notFound, showError, unauthorized, wrapWithDigest } from '../chunk-Q7BS5QC5.js';
+import '../chunk-LWVETFJV.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/errors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/file-router/index.d.ts

@@ -0,0 +1,184 @@
+/**
+ * @flightdev/core - File Router
+ *
+ * Auto-discovery of routes from file system.
+ * Similar to Next.js App Router and Nuxt server/api patterns.
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+type Handler = (context: unknown) => Response | Promise<Response>;
+type Middleware = (context: unknown, next: () => Promise<Response>) => Response | Promise<Response>;
+interface FileRoute {
+    /** HTTP method (GET, POST, etc) or 'ALL' */
+    method: HttpMethod | 'ALL';
+    /** Route path with params (e.g., /users/:id) */
+    path: string;
+    /** Original file path */
+    filePath: string;
+    /** Handler function (for APIs) */
+    handler?: Handler;
+    /** Route-specific middleware */
+    middleware?: Middleware[];
+    /** Route type: 'page' for SSR pages, 'api' for API endpoints */
+    type: 'page' | 'api';
+    /** Component function (for pages) */
+    component?: () => unknown;
+    /** Page metadata (title, description, etc) */
+    meta?: Record<string, unknown>;
+    /** Parallel route slot name (for @folder convention) */
+    slot?: string;
+    /** Intercepting route info (for (.) (..) (...) convention) */
+    interceptInfo?: {
+        /** Number of levels to intercept: 1 = same, 2 = parent, 3+ = root */
+        level: number;
+        /** Target route segment to intercept */
+        target: string;
+        /** Original path that triggers interception */
+        interceptPath: string;
+    };
+}
+interface FileRouterOptions {
+    /** Root directory to scan (default: src/routes) */
+    directory: string;
+    /** File extensions to consider (default: ['.ts', '.js']) */
+    extensions?: string[];
+    /** Whether to watch for changes (default: false in prod) */
+    watch?: boolean;
+    /**
+     * Custom module loader for development with Vite.
+     * Pass vite.ssrLoadModule to load TSX files correctly.
+     * Falls back to native import() if not provided.
+     */
+    moduleLoader?: (filePath: string) => Promise<any>;
+}
+interface ScanResult {
+    routes: FileRoute[];
+    errors: string[];
+}
+/**
+ * Scan a directory for route files
+ */
+declare function scanRoutes(options: FileRouterOptions): Promise<ScanResult>;
+/**
+ * Load routes with their handlers or components
+ * @param scanResult - Result from scanRoutes
+ * @param moduleLoader - Optional custom loader (use vite.ssrLoadModule for dev)
+ */
+declare function loadRoutes(scanResult: ScanResult, moduleLoader?: (filePath: string) => Promise<any>): Promise<FileRoute[]>;
+interface FileRouter {
+    routes: FileRoute[];
+    refresh: () => Promise<void>;
+}
+/**
+ * Create a file-based router
+ *
+ * @example
+ * ```typescript
+ * import { createFileRouter } from '@flightdev/core/file-router';
+ * import { createServer } from '@flightdev/http';
+ *
+ * const router = await createFileRouter({ directory: './src/routes' });
+ * const app = createServer();
+ *
+ * // Register all discovered routes
+ * for (const route of router.routes) {
+ *     app[route.method.toLowerCase()](route.path, route.handler);
+ * }
+ * ```
+ */
+declare function createFileRouter(options: FileRouterOptions): Promise<FileRouter>;
+/**
+ * Resolved parallel route slots for a layout.
+ * Each slot name maps to its resolved component or null if not matched.
+ */
+interface ResolvedSlots {
+    [slotName: string]: {
+        /** The component to render */
+        component: () => unknown;
+        /** The full route information */
+        route: FileRoute;
+    } | null;
+}
+/**
+ * Resolve parallel route slots for a given path.
+ *
+ * Parallel routes use the @folder convention to define named slots
+ * that can render alongside the main content in a layout.
+ *
+ * @param routes - All loaded routes from the file router
+ * @param currentPath - The current URL path to resolve slots for
+ * @returns Object mapping slot names to their resolved components
+ *
+ * @example
+ * ```typescript
+ * // Given routes from @modal/ and @sidebar/ directories
+ * const slots = resolveParallelSlots(router.routes, '/dashboard');
+ *
+ * // In layout:
+ * if (slots.modal) {
+ *     renderModal(slots.modal.component);
+ * }
+ * ```
+ */
+declare function resolveParallelSlots(routes: FileRoute[], currentPath: string): ResolvedSlots;
+/**
+ * Get the default page for an unmatched slot.
+ *
+ * When a parallel route slot doesn't have a matching route for the current path,
+ * it should render its default.page if one exists, or null.
+ *
+ * @param routes - All loaded routes
+ * @param slotName - Name of the slot (without @)
+ * @param basePath - Base path to search from
+ * @returns The default route for the slot, or null
+ */
+declare function getSlotDefault(routes: FileRoute[], slotName: string, basePath?: string): FileRoute | null;
+/**
+ * Get all slot names used in the routes.
+ *
+ * @param routes - All loaded routes
+ * @returns Array of unique slot names
+ */
+declare function getSlotNames(routes: FileRoute[]): string[];
+/**
+ * Check if a navigation should be intercepted by an intercepting route.
+ *
+ * Intercepting routes use the (.) (..) (...) convention:
+ * - (.)segment - intercepts from same level
+ * - (..)segment - intercepts from parent level
+ * - (...)segment - intercepts from root
+ *
+ * @param routes - All loaded routes
+ * @param fromPath - Current path where navigation originates
+ * @param toPath - Target path the user wants to navigate to
+ * @returns The intercepting route if found, null otherwise
+ *
+ * @example
+ * ```typescript
+ * // User is on /feed and clicks link to /photo/123
+ * const intercepted = findInterceptingRoute(routes, '/feed', '/photo/123');
+ *
+ * if (intercepted) {
+ *     // Render intercepted.component as modal instead of navigating
+ *     showModal(intercepted);
+ * }
+ * ```
+ */
+declare function findInterceptingRoute(routes: FileRoute[], fromPath: string, toPath: string): FileRoute | null;
+/**
+ * Check if an intercepting route should be dismissed on this navigation.
+ *
+ * @param currentRoute - The currently active intercepting route
+ * @param toPath - The path being navigated to
+ * @returns true if the interception should be dismissed
+ */
+declare function shouldDismissIntercept(currentRoute: FileRoute | null, toPath: string): boolean;
+/**
+ * Get route params from a path match.
+ *
+ * @param routePath - The route pattern with params (e.g., /photo/:id)
+ * @param actualPath - The actual URL path (e.g., /photo/123)
+ * @returns Object with matched params, or null if no match
+ */
+declare function extractRouteParams(routePath: string, actualPath: string): Record<string, string> | null;
+
+export { type FileRoute, type FileRouter, type FileRouterOptions, type Handler, type HttpMethod, type Middleware, type ResolvedSlots, type ScanResult, createFileRouter, extractRouteParams, findInterceptingRoute, getSlotDefault, getSlotNames, loadRoutes, resolveParallelSlots, scanRoutes, shouldDismissIntercept };

package/dist/file-router/index.js

@@ -0,0 +1,3 @@
+export { createFileRouter, extractRouteParams, findInterceptingRoute, getSlotDefault, getSlotNames, loadRoutes, resolveParallelSlots, scanRoutes, shouldDismissIntercept } from '../chunk-JX4YSCBH.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/file-router/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/file-router/streaming-hints.d.ts

@@ -0,0 +1,129 @@
+/**
+ * @flightdev/core - File Router Streaming Hints
+ *
+ * Per-route streaming configuration through exports.
+ * The user defines streaming behavior at the route level.
+ *
+ * @example
+ * ```typescript
+ * // src/routes/products/[id].page.tsx
+ *
+ * // Static export for streaming hints
+ * export const streaming = {
+ *     enabled: true,
+ *     timeout: 5000,
+ *     priority: 'high',
+ * };
+ *
+ * // Or dynamic function based on params
+ * export function getStreamingConfig(params: { id: string }) {
+ *     return {
+ *         enabled: params.id !== 'preview',
+ *         timeout: 3000,
+ *     };
+ * }
+ *
+ * export default function ProductPage({ params }) {
+ *     return <Product id={params.id} />;
+ * }
+ * ```
+ */
+/**
+ * Static streaming configuration export
+ */
+interface StreamingHints {
+    /** Whether streaming is enabled for this route (default: true) */
+    enabled?: boolean;
+    /** Timeout before aborting streaming (ms) */
+    timeout?: number;
+    /** Priority hint for streaming scheduler */
+    priority?: 'high' | 'normal' | 'low';
+    /** Expected suspense boundary IDs */
+    boundaries?: string[];
+    /** Force static rendering (no streaming) */
+    forceStatic?: boolean;
+    /** Cache the static version */
+    cache?: {
+        /** Time to cache in seconds */
+        ttl?: number;
+        /** Stale-while-revalidate time in seconds */
+        swr?: number;
+        /** Cache tags for invalidation */
+        tags?: string[];
+    };
+}
+/**
+ * Dynamic streaming configuration function
+ */
+type GetStreamingConfig<TParams = Record<string, string>> = (params: TParams, request?: Request) => StreamingHints | Promise<StreamingHints>;
+/**
+ * Route module with streaming exports
+ */
+interface StreamingRouteModule {
+    /** Default component/handler */
+    default: unknown;
+    /** Static streaming configuration */
+    streaming?: StreamingHints;
+    /** Dynamic streaming configuration function */
+    getStreamingConfig?: GetStreamingConfig;
+    /** Other route exports (metadata, generateStaticParams, etc.) */
+    [key: string]: unknown;
+}
+/**
+ * Resolved streaming configuration for a request
+ */
+interface ResolvedStreamingConfig extends StreamingHints {
+    /** Source of the configuration */
+    source: 'static' | 'dynamic' | 'default';
+    /** Route path */
+    routePath: string;
+}
+/**
+ * Default streaming hints when none are specified
+ */
+declare const DEFAULT_STREAMING_HINTS: Required<StreamingHints>;
+/**
+ * Resolve streaming configuration for a route request
+ */
+declare function resolveStreamingConfig(module: StreamingRouteModule, params: Record<string, string>, request?: Request, routePath?: string): Promise<ResolvedStreamingConfig>;
+/**
+ * Load route module and extract streaming configuration
+ */
+declare function loadRouteWithStreaming(filePath: string, moduleLoader?: (path: string) => Promise<StreamingRouteModule>): Promise<{
+    module: StreamingRouteModule;
+    hasStreamingConfig: boolean;
+    hasGetStreamingConfig: boolean;
+}>;
+/**
+ * Determine if streaming should be used based on config and request
+ */
+declare function shouldStream(config: ResolvedStreamingConfig, request?: Request): {
+    stream: boolean;
+    reason: string;
+};
+/**
+ * Create an abort controller with timeout
+ */
+declare function createStreamingController(timeout: number): {
+    controller: AbortController;
+    signal: AbortSignal;
+    cleanup: () => void;
+};
+/**
+ * Generate cache key for a streaming route
+ */
+declare function generateCacheKey(routePath: string, params: Record<string, string>, _config: StreamingHints): string;
+/**
+ * Cache headers for static streaming fallback
+ */
+declare function getStreamingCacheHeaders(config: StreamingHints): Record<string, string>;
+/**
+ * Check if a module has streaming configuration
+ */
+declare function hasStreamingConfig(module: unknown): module is StreamingRouteModule;
+/**
+ * Validate streaming hints object
+ */
+declare function isValidStreamingHints(obj: unknown): obj is StreamingHints;
+
+export { DEFAULT_STREAMING_HINTS, type GetStreamingConfig, type ResolvedStreamingConfig, type StreamingHints, type StreamingRouteModule, createStreamingController, generateCacheKey, getStreamingCacheHeaders, hasStreamingConfig, isValidStreamingHints, loadRouteWithStreaming, resolveStreamingConfig, shouldStream };

package/dist/file-router/streaming-hints.js

@@ -0,0 +1,3 @@
+export { DEFAULT_STREAMING_HINTS, createStreamingController, generateCacheKey, getStreamingCacheHeaders, hasStreamingConfig, isValidStreamingHints, loadRouteWithStreaming, resolveStreamingConfig, shouldStream } from '../chunk-ZJU5M4IB.js';
+//# sourceMappingURL=streaming-hints.js.map
+//# sourceMappingURL=streaming-hints.js.map

package/dist/file-router/streaming-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"streaming-hints.js"}

package/dist/handlers/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * @flightdev/core - Route Handlers
+ *
+ * Types and utilities for route handlers.
+ * Similar to Next.js Route Handlers pattern.
+ */
+/**
+ * HTTP methods supported by route handlers
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+/**
+ * Context passed to route handlers
+ */
+interface RouteHandlerContext {
+    /** Route parameters (e.g., { id: '123' }) */
+    params: Record<string, string>;
+    /** Query string parameters */
+    searchParams: URLSearchParams;
+}
+/**
+ * Route handler function signature
+ *
+ * @example
+ * ```typescript
+ * // src/routes/api/users/[id].ts
+ * export const GET: RouteHandler = async (request, context) => {
+ *     const { id } = context.params;
+ *     return Response.json({ userId: id });
+ * };
+ *
+ * export const PUT: RouteHandler = async (request, context) => {
+ *     const body = await request.json();
+ *     return Response.json({ updated: true, data: body });
+ * };
+ * ```
+ */
+type RouteHandler = (request: Request, context: RouteHandlerContext) => Response | Promise<Response>;
+/**
+ * Create a route handler context from request
+ */
+declare function createRouteContext(request: Request, params?: Record<string, string>): RouteHandlerContext;
+/**
+ * Helper to create JSON response
+ */
+declare function json<T>(data: T, init?: ResponseInit): Response;
+/**
+ * Helper to create redirect response
+ */
+declare function redirect(url: string, status?: 301 | 302 | 303 | 307 | 308): Response;
+/**
+ * Helper to create error response
+ */
+declare function error(message: string, status?: number): Response;
+/**
+ * Helper to get request body as typed object
+ */
+declare function parseBody<T>(request: Request): Promise<T>;
+
+export { type HttpMethod, type RouteHandler, type RouteHandlerContext, createRouteContext, error, json, parseBody, redirect };

package/dist/handlers/index.js

@@ -0,0 +1,3 @@
+export { createRouteContext, error, json, parseBody, redirect } from '../chunk-IPP44XY6.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/handlers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}