@flight-framework/core 0.2.3 → 0.2.5

package/dist/errors/index.d.ts

@@ -0,0 +1,267 @@
+/**
+ * @flight-framework/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-FSJNOPYE.js';
+import '../chunk-YHEVHRLH.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/index.d.ts

@@ -19,6 +19,8 @@ export { DEFAULT_STREAMING_HINTS, GetStreamingConfig, ResolvedStreamingConfig, S
 export { ServerContext as RSCServerContext, createServerContext, isNotFoundError, isRedirectError as isRscRedirectError, notFound, redirect as rscRedirect } from './rsc/context.js';
 export { BoundaryType as RSCBoundaryType, detectBoundaryType, hasUseClientDirective, hasUseServerDirective } from './rsc/boundaries.js';
 export { ClientComponent, ComponentType as RSCComponentType, RenderContext as RSCRenderContext, ServerComponent, composeComponents, createAsyncComponent, createClientBoundary, createRenderContext, deserializeProps, executeServerComponent, revalidatePath as rscRevalidatePath, revalidateTag as rscRevalidateTag, serializeProps, serverFetch, withErrorBoundary } from './rsc/legacy.js';
+export { BadRequestError, ErrorBoundaryOptions, FlightError, FlightErrorOptions, FlightErrorProps, ForbiddenError, InternalError, NotFoundError, ResetDetails, UnauthorizedError, clearError, createError, createErrorResponse, forbidden as createForbidden, notFound as createNotFound, unauthorized as createUnauthorized, getError, getErrorStatusCode, isFlightError, isForbiddenError as isForbidden, isNotFoundError as isNotFound, isUnauthorizedError as isUnauthorized, showError, wrapWithDigest } from './errors/index.js';
+export { getEnvironment, isBrowser, isDevelopment, isProduction, isServer, isTest } from './utils/index.js';
 
 /**
  * @flight-framework/core - Route Rules Configuration

package/dist/index.js

@@ -1,33 +1,36 @@
-export { createIslandRegistry, createPreactIslandAdapter, createReactIslandAdapter, createSolidIslandAdapter, createVueIslandAdapter, defineIsland, hydrateIslands, registerFlightIslandElement, registerIsland, renderIsland, renderIslands, setIslandAdapter } from './chunk-WFAWAHJH.js';
-export { DEFAULT_STREAMING_HINTS, createStreamingController, generateCacheKey, getStreamingCacheHeaders, hasStreamingConfig, isValidStreamingHints, loadRouteWithStreaming, resolveStreamingConfig, shouldStream } from './chunk-XSY5AAXT.js';
-export { streamWithPriority, validateDependencies } from './chunk-WOEIJWGJ.js';
 export { MetricsAggregator, createHttpObserver, createInstrumentedStream, createLoggerObserver } from './chunk-6BDCTUQY.js';
 export { DEFAULT_BOT_PATTERNS, addStreamingHeaders, createConditionalStreamer, createStreamingResponse as createConditionalStreamingResponse, createStaticResponse, isBot, isSlowConnection, prefersNoStream, streamIf, supportsStreaming } from './chunk-XOIYNY4I.js';
 export { createHTMXStreamAdapter, createReactStreamAdapter, createSolidStreamAdapter, createStreamAdapter, createSvelteStreamAdapter, createVueStreamAdapter } from './chunk-MQQLYWZZ.js';
+export { createIslandRegistry, createPreactIslandAdapter, createReactIslandAdapter, createSolidIslandAdapter, createVueIslandAdapter, defineIsland, hydrateIslands, registerFlightIslandElement, registerIsland, renderIsland, renderIslands, setIslandAdapter } from './chunk-WFAWAHJH.js';
+export { DEFAULT_STREAMING_HINTS, createStreamingController, generateCacheKey, getStreamingCacheHeaders, hasStreamingConfig, isValidStreamingHints, loadRouteWithStreaming, resolveStreamingConfig, shouldStream } from './chunk-XSY5AAXT.js';
+export { streamWithPriority, validateDependencies } from './chunk-WOEIJWGJ.js';
+import './chunk-SUILH4ID.js';
+export { createServer } from './chunk-LBYDTULN.js';
+export { defineConfig } from './chunk-IXMD5QH2.js';
 export { createFileRouter, loadRoutes, scanRoutes } from './chunk-54HPVE7N.js';
 export { RedirectError, redirect as actionRedirect, cookies, executeAction, executeFormAction, getAction, handleActionRequest, isRedirectError, parseFormData, registerAction } from './chunk-3QP3E7HS.js';
 export { createRouteContext, error, json, parseBody, redirect } from './chunk-W6D62JCI.js';
 export { createLazyContent, createStreamingResponse, createStreamingSSR, renderWithStreaming, streamParallel, streamSequential } from './chunk-RSVA2EYO.js';
 import './chunk-63SCEXD7.js';
+export { createServerContext, isNotFoundError, isRedirectError as isRscRedirectError, notFound, redirect as rscRedirect } from './chunk-62C7LX2E.js';
 import './chunk-PVUMB632.js';
 import './chunk-P6WSBVDT.js';
+import './chunk-K2CQZPCG.js';
 export { composeComponents, createAsyncComponent, createClientBoundary, createRenderContext, deserializeProps, executeServerComponent, revalidatePath as rscRevalidatePath, revalidateTag as rscRevalidateTag, serializeProps, serverFetch, withErrorBoundary } from './chunk-3ZSSRE6M.js';
 import './chunk-ZIE56LCA.js';
+export { detectBoundaryType, hasUseClientDirective, hasUseServerDirective } from './chunk-PDW5WCMW.js';
 import './chunk-Y22AMGTM.js';
-import './chunk-MDQNNIHH.js';
 import './chunk-TASAT7KB.js';
 import './chunk-2F2QU6RC.js';
 import './chunk-VPFMHGEV.js';
-import './chunk-K2CQZPCG.js';
-export { detectBoundaryType, hasUseClientDirective, hasUseServerDirective } from './chunk-PDW5WCMW.js';
-export { createServerContext, isNotFoundError, isRedirectError as isRscRedirectError, notFound, redirect as rscRedirect } from './chunk-62C7LX2E.js';
+import './chunk-MDQNNIHH.js';
+export { BadRequestError, FlightError, ForbiddenError, InternalError, NotFoundError, UnauthorizedError, clearError, createError, createErrorResponse, forbidden as createForbidden, notFound as createNotFound, unauthorized as createUnauthorized, getError, getErrorStatusCode, isFlightError, isForbiddenError as isForbidden, isNotFoundError as isNotFound, isUnauthorizedError as isUnauthorized, showError, wrapWithDigest } from './chunk-FSJNOPYE.js';
+import './chunk-PL37KFRJ.js';
+export { getEnvironment, isBrowser, isDevelopment, isProduction, isServer, isTest } from './chunk-YHEVHRLH.js';
+export { createRouter } from './chunk-GCQZ4FHI.js';
 import './chunk-ZVC3ZWLM.js';
 export { cacheKey, cached, createCache, dedupe, jsonSerializer, memory } from './chunk-R7SQAREQ.js';
-import './chunk-SUILH4ID.js';
-export { createServer } from './chunk-VOBQDQKX.js';
-export { createRouter } from './chunk-GCQZ4FHI.js';
 export { createMiddlewareChain } from './chunk-KWFX6WHG.js';
-export { defineConfig } from './chunk-IXMD5QH2.js';
 import { promises } from 'fs';
 import { dirname, join } from 'path';