@nextrush/errors 3.0.0

package/dist/index.d.ts

@@ -0,0 +1,583 @@
+import { Context, Middleware, Next } from '@nextrush/types';
+
+/**
+ * @nextrush/errors - Base Error Classes
+ *
+ * Foundational error classes for NextRush framework.
+ *
+ * @packageDocumentation
+ */
+/**
+ * Base error class for all NextRush errors
+ */
+declare class NextRushError extends Error {
+    /** HTTP status code */
+    readonly status: number;
+    /** Error code for programmatic handling */
+    readonly code: string;
+    /** Whether error message is safe to expose to client */
+    readonly expose: boolean;
+    /** Additional error details */
+    readonly details?: Record<string, unknown>;
+    /** Original error that caused this error */
+    readonly cause?: unknown;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        expose?: boolean;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+    /**
+     * Convert error to JSON representation
+     */
+    toJSON(): Record<string, unknown>;
+    /**
+     * Create a response-safe version of the error
+     */
+    toResponse(): {
+        status: number;
+        body: Record<string, unknown>;
+    };
+}
+/**
+ * Get default message for an HTTP status code
+ */
+declare function getHttpStatusMessage(status: number): string;
+/**
+ * Base class for HTTP errors
+ */
+declare class HttpError extends NextRushError {
+    constructor(status: number, message?: string, options?: {
+        code?: string;
+        expose?: boolean;
+        details?: Record<string, unknown>;
+        cause?: unknown;
+    });
+}
+
+/**
+ * @nextrush/errors - HTTP Error Classes
+ *
+ * Standard HTTP error classes for common status codes.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Options for creating HTTP errors
+ */
+interface HttpErrorOptions {
+    code?: string;
+    expose?: boolean;
+    details?: Record<string, unknown>;
+    cause?: unknown;
+}
+/**
+ * 400 Bad Request - Invalid syntax or malformed request
+ */
+declare class BadRequestError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 401 Unauthorized - Authentication required
+ */
+declare class UnauthorizedError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 402 Payment Required - Payment needed
+ */
+declare class PaymentRequiredError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 403 Forbidden - Access denied
+ */
+declare class ForbiddenError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 404 Not Found - Resource not found
+ */
+declare class NotFoundError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 405 Method Not Allowed - HTTP method not supported
+ */
+declare class MethodNotAllowedError extends HttpError {
+    readonly allowedMethods: string[];
+    constructor(allowedMethods?: string[], message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 406 Not Acceptable - Cannot produce acceptable response
+ */
+declare class NotAcceptableError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 407 Proxy Authentication Required
+ */
+declare class ProxyAuthRequiredError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 408 Request Timeout - Client took too long
+ */
+declare class RequestTimeoutError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 409 Conflict - Request conflicts with current state
+ */
+declare class ConflictError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 410 Gone - Resource permanently deleted
+ */
+declare class GoneError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 411 Length Required - Content-Length header required
+ */
+declare class LengthRequiredError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 412 Precondition Failed - Precondition in headers not met
+ */
+declare class PreconditionFailedError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 413 Payload Too Large - Request body too large
+ */
+declare class PayloadTooLargeError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 414 URI Too Long - Request URI too long
+ */
+declare class UriTooLongError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 415 Unsupported Media Type - Content type not supported
+ */
+declare class UnsupportedMediaTypeError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 416 Range Not Satisfiable - Cannot satisfy Range header
+ */
+declare class RangeNotSatisfiableError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 417 Expectation Failed - Cannot meet Expect header
+ */
+declare class ExpectationFailedError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 418 I'm a Teapot - RFC 2324
+ */
+declare class ImATeapotError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 422 Unprocessable Entity - Semantic errors
+ */
+declare class UnprocessableEntityError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 423 Locked - Resource is locked
+ */
+declare class LockedError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 424 Failed Dependency - Dependent request failed
+ */
+declare class FailedDependencyError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 425 Too Early - Request replayed too early
+ */
+declare class TooEarlyError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 426 Upgrade Required - Client should upgrade protocol
+ */
+declare class UpgradeRequiredError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 428 Precondition Required - Origin server requires conditional request
+ */
+declare class PreconditionRequiredError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 429 Too Many Requests - Rate limit exceeded
+ */
+declare class TooManyRequestsError extends HttpError {
+    readonly retryAfter?: number;
+    constructor(message?: string, options?: HttpErrorOptions & {
+        retryAfter?: number;
+    });
+}
+/**
+ * 431 Request Header Fields Too Large
+ */
+declare class RequestHeaderFieldsTooLargeError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 451 Unavailable For Legal Reasons
+ */
+declare class UnavailableForLegalReasonsError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 500 Internal Server Error - Generic server error
+ */
+declare class InternalServerError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 501 Not Implemented - Feature not implemented
+ */
+declare class NotImplementedError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 502 Bad Gateway - Invalid upstream response
+ */
+declare class BadGatewayError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 503 Service Unavailable - Server temporarily unavailable
+ */
+declare class ServiceUnavailableError extends HttpError {
+    readonly retryAfter?: number;
+    constructor(message?: string, options?: HttpErrorOptions & {
+        retryAfter?: number;
+    });
+}
+/**
+ * 504 Gateway Timeout - Upstream timeout
+ */
+declare class GatewayTimeoutError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 505 HTTP Version Not Supported
+ */
+declare class HttpVersionNotSupportedError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 506 Variant Also Negotiates
+ */
+declare class VariantAlsoNegotiatesError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 507 Insufficient Storage
+ */
+declare class InsufficientStorageError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 508 Loop Detected
+ */
+declare class LoopDetectedError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 510 Not Extended
+ */
+declare class NotExtendedError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+/**
+ * 511 Network Authentication Required
+ */
+declare class NetworkAuthRequiredError extends HttpError {
+    constructor(message?: string, options?: HttpErrorOptions);
+}
+
+/**
+ * @nextrush/errors - Validation Error Classes
+ *
+ * Specialized errors for input validation.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Single validation issue
+ */
+interface ValidationIssue {
+    /** Field path (e.g., 'user.email' or 'items[0].name') */
+    path: string;
+    /** Error message for this field */
+    message: string;
+    /** Validation rule that failed */
+    rule?: string;
+    /** Expected value or constraint */
+    expected?: unknown;
+    /** Actual value received */
+    received?: unknown;
+}
+/**
+ * Validation error with multiple issues
+ */
+declare class ValidationError extends NextRushError {
+    /** List of validation issues */
+    readonly issues: ValidationIssue[];
+    constructor(issues: ValidationIssue[], message?: string);
+    /**
+     * Create from a single field error
+     */
+    static fromField(path: string, message: string, rule?: string): ValidationError;
+    /**
+     * Create from multiple field errors
+     */
+    static fromFields(errors: Record<string, string>): ValidationError;
+    /**
+     * Check if a specific field has errors
+     */
+    hasErrorFor(path: string): boolean;
+    /**
+     * Get errors for a specific field
+     */
+    getErrorsFor(path: string): ValidationIssue[];
+    /**
+     * Get first error message for a field
+     */
+    getFirstError(path: string): string | undefined;
+    /**
+     * Convert to flat error object
+     */
+    toFlatObject(): Record<string, string>;
+    toJSON(): Record<string, unknown>;
+}
+/**
+ * Required field missing
+ */
+declare class RequiredFieldError extends ValidationError {
+    constructor(field: string);
+}
+/**
+ * Field type mismatch
+ */
+declare class TypeMismatchError extends ValidationError {
+    constructor(field: string, expected: string, received: string);
+}
+/**
+ * Value out of range
+ */
+declare class RangeValidationError extends ValidationError {
+    constructor(field: string, min?: number, max?: number);
+}
+/**
+ * String length violation
+ */
+declare class LengthError extends ValidationError {
+    constructor(field: string, min?: number, max?: number);
+}
+/**
+ * Pattern mismatch
+ */
+declare class PatternError extends ValidationError {
+    constructor(field: string, pattern: string, message?: string);
+}
+/**
+ * Invalid email format
+ */
+declare class InvalidEmailError extends ValidationError {
+    constructor(field?: string);
+}
+/**
+ * Invalid URL format
+ */
+declare class InvalidUrlError extends ValidationError {
+    constructor(field?: string);
+}
+
+/**
+ * @nextrush/errors - Error Factory
+ *
+ * Factory functions for creating errors.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Create an HTTP error by status code
+ */
+declare function createError(status: number, message?: string, options?: HttpErrorOptions): HttpError;
+/**
+ * Create a 400 Bad Request error
+ */
+declare function badRequest(message?: string, options?: HttpErrorOptions): BadRequestError;
+/**
+ * Create a 401 Unauthorized error
+ */
+declare function unauthorized(message?: string, options?: HttpErrorOptions): UnauthorizedError;
+/**
+ * Create a 403 Forbidden error
+ */
+declare function forbidden(message?: string, options?: HttpErrorOptions): ForbiddenError;
+/**
+ * Create a 404 Not Found error
+ */
+declare function notFound(message?: string, options?: HttpErrorOptions): NotFoundError;
+/**
+ * Create a 405 Method Not Allowed error
+ */
+declare function methodNotAllowed(allowedMethods?: string[], message?: string, options?: HttpErrorOptions): MethodNotAllowedError;
+/**
+ * Create a 409 Conflict error
+ */
+declare function conflict(message?: string, options?: HttpErrorOptions): ConflictError;
+/**
+ * Create a 422 Unprocessable Entity error
+ */
+declare function unprocessableEntity(message?: string, options?: HttpErrorOptions): UnprocessableEntityError;
+/**
+ * Create a 429 Too Many Requests error
+ */
+declare function tooManyRequests(message?: string, options?: HttpErrorOptions & {
+    retryAfter?: number;
+}): TooManyRequestsError;
+/**
+ * Create a 500 Internal Server Error
+ */
+declare function internalError(message?: string, options?: HttpErrorOptions): InternalServerError;
+/**
+ * Create a 502 Bad Gateway error
+ */
+declare function badGateway(message?: string, options?: HttpErrorOptions): BadGatewayError;
+/**
+ * Create a 503 Service Unavailable error
+ */
+declare function serviceUnavailable(message?: string, options?: HttpErrorOptions & {
+    retryAfter?: number;
+}): ServiceUnavailableError;
+/**
+ * Create a 504 Gateway Timeout error
+ */
+declare function gatewayTimeout(message?: string, options?: HttpErrorOptions): GatewayTimeoutError;
+/**
+ * Check if an error is a NextRush HttpError
+ */
+declare function isHttpError(error: unknown): error is HttpError;
+/**
+ * Get HTTP status from any error
+ *
+ * Checks NextRushError first (covers HttpError, ValidationError, and all subclasses),
+ * then falls back to duck-typed status property.
+ */
+declare function getErrorStatus(error: unknown): number;
+/**
+ * Get error message safe for client response
+ *
+ * Exposes message for any NextRushError (including ValidationError)
+ * when the error's expose flag is true.
+ */
+declare function getSafeErrorMessage(error: unknown): string;
+
+/**
+ * @nextrush/errors - Error Handler Middleware
+ *
+ * Middleware for handling errors in NextRush applications.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Minimal context interface for error handling.
+ *
+ * @deprecated Use `Context` from `@nextrush/types` instead.
+ * Kept for backward compatibility — will be removed in v4.
+ */
+interface ErrorContext {
+    method: string;
+    path: string;
+    status: number;
+    json: (data: unknown) => void;
+}
+/**
+ * Error handler middleware function type.
+ *
+ * @deprecated Use `Middleware` from `@nextrush/types` instead.
+ * Kept for backward compatibility — will be removed in v4.
+ */
+type ErrorMiddleware = Middleware;
+/**
+ * Error handler options
+ */
+interface ErrorHandlerOptions {
+    /** Include stack trace in development */
+    includeStack?: boolean;
+    /** Custom error logger */
+    logger?: (error: Error, ctx: Context) => void;
+    /** Custom error transformer */
+    transform?: (error: Error, ctx: Context) => Record<string, unknown>;
+    /** Handle specific error types */
+    handlers?: Map<new (...args: unknown[]) => Error, (error: Error, ctx: Context) => void>;
+}
+/**
+ * Create error handler middleware
+ *
+ * @example
+ * ```typescript
+ * const app = createApp();
+ *
+ * // Add error handler first
+ * app.use(errorHandler({
+ *   includeStack: process.env.NODE_ENV !== 'production',
+ *   logger: (err, ctx) => myLogger.error(err),
+ * }));
+ * ```
+ */
+declare function errorHandler(options?: ErrorHandlerOptions): Middleware;
+/**
+ * Not found handler middleware - catches unhandled requests
+ *
+ * @example
+ * ```typescript
+ * // Add at the end of middleware chain
+ * app.use(notFoundHandler());
+ * ```
+ */
+declare function notFoundHandler(message?: string): Middleware;
+/**
+ * Catch async errors wrapper for route handlers
+ *
+ * @example
+ * ```typescript
+ * router.get('/users/:id', catchAsync(async (ctx) => {
+ *   const user = await db.users.findById(ctx.params.id);
+ *   if (!user) throw new NotFoundError('User not found');
+ *   ctx.json(user);
+ * }));
+ * ```
+ *
+ * @deprecated This wrapper is redundant — async errors propagate naturally
+ * through the middleware chain and are caught by `errorHandler()`. Use the
+ * handler directly instead.
+ */
+declare function catchAsync(handler: (ctx: Context, next: Next) => Promise<void>): Middleware;
+
+export { BadGatewayError, BadRequestError, ConflictError, type ErrorContext, type ErrorHandlerOptions, type ErrorMiddleware, ExpectationFailedError, FailedDependencyError, ForbiddenError, GatewayTimeoutError, GoneError, HttpError, type HttpErrorOptions, HttpVersionNotSupportedError, ImATeapotError, InsufficientStorageError, InternalServerError, InvalidEmailError, InvalidUrlError, LengthError, LengthRequiredError, LockedError, LoopDetectedError, MethodNotAllowedError, NetworkAuthRequiredError, NextRushError, NotAcceptableError, NotExtendedError, NotFoundError, NotImplementedError, PatternError, PayloadTooLargeError, PaymentRequiredError, PreconditionFailedError, PreconditionRequiredError, ProxyAuthRequiredError, RangeNotSatisfiableError, RangeValidationError, RequestHeaderFieldsTooLargeError, RequestTimeoutError, RequiredFieldError, ServiceUnavailableError, TooEarlyError, TooManyRequestsError, TypeMismatchError, UnauthorizedError, UnavailableForLegalReasonsError, UnprocessableEntityError, UnsupportedMediaTypeError, UpgradeRequiredError, UriTooLongError, ValidationError, type ValidationIssue, VariantAlsoNegotiatesError, badGateway, badRequest, catchAsync, conflict, createError, errorHandler, forbidden, gatewayTimeout, getErrorStatus, getHttpStatusMessage, getSafeErrorMessage, internalError, isHttpError, methodNotAllowed, notFound, notFoundHandler, serviceUnavailable, tooManyRequests, unauthorized, unprocessableEntity };