@spfn/core 0.1.0-alpha.88 → 0.2.0-beta.1

package/dist/errors/index.d.ts

@@ -1,32 +1,310 @@
-import { D as DatabaseError } from '../database-errors-BNNmLTJE.js';
-export { C as ConnectionError, a as ConstraintViolationError, b as DeadlockError, c as DuplicateEntryError, E as EntityNotFoundError, Q as QueryError, T as TransactionError } from '../database-errors-BNNmLTJE.js';
+/**
+ * Serializable Error Base Class
+ *
+ * Base class for errors that can be serialized/deserialized across HTTP boundary.
+ * Automatically serializes public fields for transmission to client.
+ */
+/**
+ * Serialized error format for JSON transmission
+ */
+interface SerializedError {
+    __type: string;
+    message: string;
+    [key: string]: unknown;
+}
+/**
+ * Base class for all serializable errors
+ *
+ * Features:
+ * - Auto-serialization of public fields via toJSON()
+ * - Constructor accepts object with all fields
+ * - Type-safe error handling with instanceof
+ *
+ * @example
+ * ```typescript
+ * class PaymentFailedError extends SerializableError
+ * {
+ *     readonly statusCode = 402;
+ *     transactionId!: string;
+ *     reason!: 'insufficient_funds' | 'card_declined';
+ *
+ *     constructor(data: {
+ *         message: string;
+ *         transactionId: string;
+ *         reason: 'insufficient_funds' | 'card_declined';
+ *     })
+ *     {
+ *         super(data.message);
+ *         this.name = 'PaymentFailedError';
+ *         Object.assign(this, data);
+ *     }
+ * }
+ * ```
+ */
+declare abstract class SerializableError extends Error {
+    /**
+     * HTTP status code for this error type
+     */
+    abstract readonly statusCode: number;
+    /**
+     * Serialize error to JSON-compatible object
+     *
+     * Automatically includes:
+     * - __type: Constructor name for deserialization
+     * - message: Error message
+     * - All public instance properties (except name, stack)
+     */
+    toJSON(): SerializedError;
+}
+
+/**
+ * Error Registry
+ *
+ * Central registry for serializable error types.
+ * Enables automatic error deserialization on the client side.
+ */
+
+/**
+ * Error constructor type
+ */
+type SerializableErrorConstructor = new (data: any) => SerializableError;
+/**
+ * Input type for ErrorRegistry constructor
+ */
+type ErrorRegistryInput = SerializableErrorConstructor | SerializableErrorConstructor[] | ErrorRegistry;
+/**
+ * Error registry for serialization/deserialization
+ *
+ * @example
+ * ```typescript
+ * // Create registry with initial errors
+ * const registry = new ErrorRegistry([
+ *     errorRegistry,           // Another ErrorRegistry
+ *     PaymentFailedError,      // Single error class
+ *     [RefundError, OrderError], // Array of error classes
+ * ]);
+ *
+ * // Or create empty and append
+ * const registry = new ErrorRegistry();
+ * registry
+ *     .append(ValidationError)
+ *     .append([PaymentFailedError, RefundError]);
+ *
+ * // Deserialize from JSON
+ * const error = registry.deserialize({
+ *     __type: 'PaymentFailedError',
+ *     message: 'Payment failed',
+ *     transactionId: 'tx_123',
+ *     reason: 'insufficient_funds'
+ * });
+ *
+ * // error instanceof PaymentFailedError === true
+ * ```
+ */
+declare class ErrorRegistry {
+    private errors;
+    constructor(initialErrors?: ErrorRegistryInput[]);
+    /**
+     * Append error class(es) to the registry
+     *
+     * @param ErrorClass - Single error constructor
+     * @returns This registry for chaining
+     */
+    append(ErrorClass: SerializableErrorConstructor): this;
+    /**
+     * Append error class(es) to the registry
+     *
+     * @param ErrorClasses - Array of error constructors
+     * @returns This registry for chaining
+     */
+    append(ErrorClasses: SerializableErrorConstructor[]): this;
+    /**
+     * Concatenate another ErrorRegistry into this one
+     *
+     * @param registry - Another ErrorRegistry to merge
+     * @returns This registry for chaining
+     */
+    concat(registry: ErrorRegistry): this;
+    /**
+     * Check if error type is registered
+     *
+     * @param name - Error class name
+     */
+    has(name: string): boolean;
+    /**
+     * Deserialize error from JSON data
+     *
+     * @param data - Serialized error data with __type field
+     * @returns Deserialized error instance
+     * @throws Error if error type is not registered
+     */
+    deserialize(data: {
+        __type: string;
+        [key: string]: any;
+    }): SerializableError;
+    /**
+     * Try to deserialize error, return null if type unknown
+     *
+     * @param data - Serialized error data
+     * @returns Deserialized error or null
+     */
+    tryDeserialize(data: {
+        __type?: string;
+        [key: string]: any;
+    }): SerializableError | null;
+    /**
+     * Get all registered error types
+     */
+    getRegisteredTypes(): string[];
+}
+
+/**
+ * Database Error Classes
+ *
+ * Type-safe error handling with custom error class hierarchy
+ * Mapped to HTTP status codes for API responses
+ * All errors extend SerializableError for consistent JSON serialization
+ */
+
+/**
+ * Base Database Error
+ *
+ * Base class for all database-related errors
+ */
+declare class DatabaseError<TDetails extends Record<string, unknown> = Record<string, unknown>> extends SerializableError {
+    readonly statusCode: number;
+    readonly details?: TDetails;
+    constructor(data: {
+        message: string;
+        statusCode?: number;
+        details?: TDetails;
+    });
+}
+/**
+ * Connection Error (503 Service Unavailable)
+ *
+ * Database connection failure, connection pool exhaustion, etc.
+ */
+declare class ConnectionError extends DatabaseError {
+    constructor(data: {
+        message: string;
+        details?: Record<string, unknown>;
+    });
+}
+/**
+ * Query Error (500 Internal Server Error)
+ *
+ * SQL query execution failure, syntax errors, etc.
+ */
+declare class QueryError extends DatabaseError {
+    constructor(data: {
+        message: string;
+        statusCode?: number;
+        details?: Record<string, unknown>;
+    });
+}
+/**
+ * Entity Not Found Error (404 Not Found)
+ *
+ * Database entity does not exist
+ */
+declare class EntityNotFoundError extends QueryError {
+    readonly resource: string;
+    readonly id: string | number;
+    constructor(data: {
+        resource: string;
+        id: string | number;
+    });
+}
+/**
+ * Constraint Violation Error (400 Bad Request)
+ *
+ * Database constraint violation (NOT NULL, CHECK, FOREIGN KEY, etc.)
+ * This is different from HTTP ValidationError which validates request input
+ */
+declare class ConstraintViolationError extends QueryError {
+    constructor(data: {
+        message: string;
+        details?: Record<string, unknown>;
+    });
+}
+/**
+ * Transaction Error (500 Internal Server Error)
+ *
+ * Transaction start/commit/rollback failure
+ */
+declare class TransactionError extends DatabaseError {
+    constructor(data: {
+        message: string;
+        statusCode?: number;
+        details?: Record<string, unknown>;
+    });
+}
+/**
+ * Deadlock Error (409 Conflict)
+ *
+ * Database deadlock detected
+ */
+declare class DeadlockError extends TransactionError {
+    constructor(data: {
+        message: string;
+        details?: Record<string, unknown>;
+    });
+}
+/**
+ * Duplicate Entry Error (409 Conflict)
+ *
+ * Unique constraint violation (e.g., duplicate email)
+ */
+declare class DuplicateEntryError extends QueryError {
+    readonly field: string;
+    readonly value: string | number;
+    constructor(data: {
+        field: string;
+        value: string | number;
+    });
+}
+
+type databaseErrors_ConnectionError = ConnectionError;
+declare const databaseErrors_ConnectionError: typeof ConnectionError;
+type databaseErrors_ConstraintViolationError = ConstraintViolationError;
+declare const databaseErrors_ConstraintViolationError: typeof ConstraintViolationError;
+type databaseErrors_DatabaseError<TDetails extends Record<string, unknown> = Record<string, unknown>> = DatabaseError<TDetails>;
+declare const databaseErrors_DatabaseError: typeof DatabaseError;
+type databaseErrors_DeadlockError = DeadlockError;
+declare const databaseErrors_DeadlockError: typeof DeadlockError;
+type databaseErrors_DuplicateEntryError = DuplicateEntryError;
+declare const databaseErrors_DuplicateEntryError: typeof DuplicateEntryError;
+type databaseErrors_EntityNotFoundError = EntityNotFoundError;
+declare const databaseErrors_EntityNotFoundError: typeof EntityNotFoundError;
+type databaseErrors_QueryError = QueryError;
+declare const databaseErrors_QueryError: typeof QueryError;
+type databaseErrors_TransactionError = TransactionError;
+declare const databaseErrors_TransactionError: typeof TransactionError;
+declare namespace databaseErrors {
+  export { databaseErrors_ConnectionError as ConnectionError, databaseErrors_ConstraintViolationError as ConstraintViolationError, databaseErrors_DatabaseError as DatabaseError, databaseErrors_DeadlockError as DeadlockError, databaseErrors_DuplicateEntryError as DuplicateEntryError, databaseErrors_EntityNotFoundError as EntityNotFoundError, databaseErrors_QueryError as QueryError, databaseErrors_TransactionError as TransactionError };
+}
 
 /**
  * HTTP Error Classes
  *
  * Standard HTTP error classes for API responses
- * Covers common HTTP status codes beyond database errors
+ * All errors are serializable for type-safe client-side error handling
  */
+
 /**
  * Base HTTP Error
  *
  * Base class for all HTTP-related errors
  */
-declare class HttpError<TDetails extends Record<string, unknown> = Record<string, unknown>> extends Error {
+declare class HttpError extends SerializableError {
     readonly statusCode: number;
-    readonly details?: TDetails;
-    readonly timestamp: Date;
-    constructor(message: string, statusCode: number, details?: TDetails);
-    /**
-     * Serialize error for API response
-     */
-    toJSON(): {
-        name: string;
+    details?: Record<string, unknown>;
+    constructor(data: {
         message: string;
         statusCode: number;
-        details: TDetails | undefined;
-        timestamp: string;
-    };
+        details?: Record<string, unknown>;
+    });
 }
 /**
  * Bad Request Error (400)
@@ -34,16 +312,32 @@ declare class HttpError<TDetails extends Record<string, unknown> = Record<string
  * Generic bad request - malformed syntax, invalid parameters, etc.
  */
 declare class BadRequestError extends HttpError {
-    constructor(message?: string, details?: Record<string, any>);
+    constructor(data?: {
+        message?: string;
+        details?: Record<string, any>;
+    });
 }
 /**
  * Validation Error (400)
  *
  * Input validation failure (request params, query, body)
- * Used by contract-based routing for automatic validation
+ * Used by define-route system for automatic validation
  */
 declare class ValidationError extends HttpError {
-    constructor(message: string, details?: Record<string, any>);
+    fields?: Array<{
+        path: string;
+        message: string;
+        value?: any;
+    }>;
+    constructor(data: {
+        message: string;
+        fields?: Array<{
+            path: string;
+            message: string;
+            value?: any;
+        }>;
+        details?: Record<string, any>;
+    });
 }
 /**
  * Unauthorized Error (401)
@@ -51,7 +345,10 @@ declare class ValidationError extends HttpError {
  * Authentication required or authentication failed
  */
 declare class UnauthorizedError extends HttpError {
-    constructor(message?: string, details?: Record<string, any>);
+    constructor(data?: {
+        message?: string;
+        details?: Record<string, any>;
+    });
 }
 /**
  * Forbidden Error (403)
@@ -59,25 +356,47 @@ declare class UnauthorizedError extends HttpError {
  * Authenticated but lacks permission to access resource
  */
 declare class ForbiddenError extends HttpError {
-    constructor(message?: string, details?: Record<string, any>);
+    constructor(data?: {
+        message?: string;
+        details?: Record<string, any>;
+    });
 }
 /**
  * Not Found Error (404)
  *
  * Requested resource does not exist
- * Generic HTTP 404 error (for database-specific NotFoundError, see database-errors.ts)
  */
 declare class NotFoundError extends HttpError {
-    constructor(message?: string, details?: Record<string, any>);
+    resource?: string;
+    constructor(data?: {
+        message?: string;
+        resource?: string;
+        details?: Record<string, any>;
+    });
 }
 /**
  * Conflict Error (409)
  *
  * Generic conflict - resource state conflict, concurrent modification, etc.
- * More general than DuplicateEntryError
  */
 declare class ConflictError extends HttpError {
-    constructor(message?: string, details?: Record<string, any>);
+    constructor(data?: {
+        message?: string;
+        details?: Record<string, any>;
+    });
+}
+/**
+ * Gone Error (410)
+ *
+ * Resource permanently deleted and no longer available
+ */
+declare class GoneError extends HttpError {
+    resource?: string;
+    constructor(data?: {
+        message?: string;
+        resource?: string;
+        details?: Record<string, any>;
+    });
 }
 /**
  * Too Many Requests Error (429)
@@ -85,7 +404,12 @@ declare class ConflictError extends HttpError {
  * Rate limit exceeded
  */
 declare class TooManyRequestsError extends HttpError {
-    constructor(message?: string, retryAfter?: number, details?: Record<string, any>);
+    retryAfter?: number;
+    constructor(data?: {
+        message?: string;
+        retryAfter?: number;
+        details?: Record<string, any>;
+    });
 }
 /**
  * Internal Server Error (500)
@@ -93,7 +417,25 @@ declare class TooManyRequestsError extends HttpError {
  * Generic server error when no specific error type applies
  */
 declare class InternalServerError extends HttpError {
-    constructor(message?: string, details?: Record<string, any>);
+    constructor(data?: {
+        message?: string;
+        details?: Record<string, any>;
+    });
+}
+/**
+ * Unsupported Media Type Error (415)
+ *
+ * Media type not supported - invalid file type, content type, etc.
+ */
+declare class UnsupportedMediaTypeError extends HttpError {
+    mediaType?: string;
+    supportedTypes?: string[];
+    constructor(data?: {
+        message?: string;
+        mediaType?: string;
+        supportedTypes?: string[];
+        details?: Record<string, any>;
+    });
 }
 /**
  * Unprocessable Entity Error (422)
@@ -101,7 +443,10 @@ declare class InternalServerError extends HttpError {
  * Request is well-formed but contains semantic errors
  */
 declare class UnprocessableEntityError extends HttpError {
-    constructor(message?: string, details?: Record<string, any>);
+    constructor(data?: {
+        message?: string;
+        details?: Record<string, any>;
+    });
 }
 /**
  * Service Unavailable Error (503)
@@ -109,7 +454,42 @@ declare class UnprocessableEntityError extends HttpError {
  * Service temporarily unavailable (maintenance, overload, etc.)
  */
 declare class ServiceUnavailableError extends HttpError {
-    constructor(message?: string, retryAfter?: number, details?: Record<string, any>);
+    retryAfter?: number;
+    constructor(data?: {
+        message?: string;
+        retryAfter?: number;
+        details?: Record<string, any>;
+    });
+}
+
+type httpErrors_BadRequestError = BadRequestError;
+declare const httpErrors_BadRequestError: typeof BadRequestError;
+type httpErrors_ConflictError = ConflictError;
+declare const httpErrors_ConflictError: typeof ConflictError;
+type httpErrors_ForbiddenError = ForbiddenError;
+declare const httpErrors_ForbiddenError: typeof ForbiddenError;
+type httpErrors_GoneError = GoneError;
+declare const httpErrors_GoneError: typeof GoneError;
+type httpErrors_HttpError = HttpError;
+declare const httpErrors_HttpError: typeof HttpError;
+type httpErrors_InternalServerError = InternalServerError;
+declare const httpErrors_InternalServerError: typeof InternalServerError;
+type httpErrors_NotFoundError = NotFoundError;
+declare const httpErrors_NotFoundError: typeof NotFoundError;
+type httpErrors_ServiceUnavailableError = ServiceUnavailableError;
+declare const httpErrors_ServiceUnavailableError: typeof ServiceUnavailableError;
+type httpErrors_TooManyRequestsError = TooManyRequestsError;
+declare const httpErrors_TooManyRequestsError: typeof TooManyRequestsError;
+type httpErrors_UnauthorizedError = UnauthorizedError;
+declare const httpErrors_UnauthorizedError: typeof UnauthorizedError;
+type httpErrors_UnprocessableEntityError = UnprocessableEntityError;
+declare const httpErrors_UnprocessableEntityError: typeof UnprocessableEntityError;
+type httpErrors_UnsupportedMediaTypeError = UnsupportedMediaTypeError;
+declare const httpErrors_UnsupportedMediaTypeError: typeof UnsupportedMediaTypeError;
+type httpErrors_ValidationError = ValidationError;
+declare const httpErrors_ValidationError: typeof ValidationError;
+declare namespace httpErrors {
+  export { httpErrors_BadRequestError as BadRequestError, httpErrors_ConflictError as ConflictError, httpErrors_ForbiddenError as ForbiddenError, httpErrors_GoneError as GoneError, httpErrors_HttpError as HttpError, httpErrors_InternalServerError as InternalServerError, httpErrors_NotFoundError as NotFoundError, httpErrors_ServiceUnavailableError as ServiceUnavailableError, httpErrors_TooManyRequestsError as TooManyRequestsError, httpErrors_UnauthorizedError as UnauthorizedError, httpErrors_UnprocessableEntityError as UnprocessableEntityError, httpErrors_UnsupportedMediaTypeError as UnsupportedMediaTypeError, httpErrors_ValidationError as ValidationError };
 }
 
 /**
@@ -133,4 +513,12 @@ declare function hasStatusCode(error: unknown): error is {
     statusCode: number;
 };
 
-export { BadRequestError, ConflictError, DatabaseError, ForbiddenError, HttpError, InternalServerError, NotFoundError, ServiceUnavailableError, TooManyRequestsError, UnauthorizedError, UnprocessableEntityError, ValidationError, hasStatusCode, isDatabaseError, isHttpError };
+/**
+ * Error Module Exports
+ *
+ * Entry point for error handling module with serialization support
+ */
+
+declare const errorRegistry: ErrorRegistry;
+
+export { BadRequestError, ConflictError, ConnectionError, ConstraintViolationError, DatabaseError, databaseErrors as DatabaseErrors, DeadlockError, DuplicateEntryError, EntityNotFoundError, ErrorRegistry, type ErrorRegistryInput, ForbiddenError, GoneError, HttpError, httpErrors as HttpErrors, InternalServerError, NotFoundError, QueryError, SerializableError, type SerializableErrorConstructor, type SerializedError, ServiceUnavailableError, TooManyRequestsError, TransactionError, UnauthorizedError, UnprocessableEntityError, UnsupportedMediaTypeError, ValidationError, errorRegistry, hasStatusCode, isDatabaseError, isHttpError };