pdf-oxide-fips 0.3.47

package/lib/errors.d.ts

@@ -0,0 +1,382 @@
+/**
+ * Unified Error Handling for PDF Oxide
+ *
+ * Provides comprehensive exception hierarchy consistent across all language bindings.
+ * Uses 4-digit error codes organized by category (1000-9999).
+ *
+ * Error Code System:
+ * - 1000-1999: Parse errors
+ * - 2000-2999: I/O errors
+ * - 3000-3999: Encryption errors
+ * - 4000-4999: State errors
+ * - 5000-5999: Unsupported feature errors
+ * - 6000-6999: Validation errors
+ * - 7000-7999: Rendering errors
+ * - 8000-8999: Search errors
+ * - 9000-9999: Other errors (compliance, OCR, etc.)
+ */
+import type { PdfErrorDetails } from './types/common';
+/**
+ * Error categories for classification and handling
+ */
+export declare enum ErrorCategory {
+    VALIDATION = "validation",
+    IO = "io",
+    ENCRYPTION = "encryption",
+    PARSING = "parsing",
+    RENDERING = "rendering",
+    SEARCH = "search",
+    PERMISSION = "permission",
+    RESOURCE = "resource",
+    STATE = "state",
+    UNSUPPORTED = "unsupported",
+    COMPLIANCE = "compliance",
+    OCR = "ocr",
+    SIGNATURE = "signature",
+    REDACTION = "redaction",
+    UNKNOWN = "unknown"
+}
+/**
+ * Error severity levels for prioritization and monitoring
+ */
+export declare enum ErrorSeverity {
+    LOW = "low",
+    MEDIUM = "medium",
+    HIGH = "high",
+    CRITICAL = "critical"
+}
+/**
+ * Recovery information for error handling
+ */
+export interface ErrorRecovery {
+    canRetry: boolean;
+    retryAfterMs?: number;
+    suggestions: string[];
+    alternativeApproach?: string;
+}
+/**
+ * Base class for all PDF Oxide errors.
+ *
+ * @class PdfException
+ * @extends {Error}
+ * @property {string} code - 4-digit error code (XXXX format)
+ * @property {string} message - Human-readable error message
+ * @property {PdfErrorDetails} details - Additional context information
+ *
+ * @example
+ * try {
+ *   // PDF operation
+ * } catch (err) {
+ *   if (err instanceof PdfException) {
+ *     console.log(`[${err.code}] ${err.message}`);
+ *     console.log('Context:', err.details);
+ *   }
+ * }
+ */
+export declare class PdfException extends Error {
+    readonly code: string;
+    readonly message: string;
+    readonly details: PdfErrorDetails;
+    readonly category: ErrorCategory;
+    readonly severity: ErrorSeverity;
+    readonly recovery: ErrorRecovery;
+    /**
+     * Creates a new PdfException.
+     *
+     * @param code - 4-digit error code
+     * @param message - Human-readable error message
+     * @param category - Error category for classification
+     * @param severity - Error severity level
+     * @param details - Additional context information
+     * @param recovery - Recovery information
+     */
+    constructor(code: string, message: string, category?: ErrorCategory, severity?: ErrorSeverity, details?: PdfErrorDetails, recovery?: Partial<ErrorRecovery>);
+    /**
+     * Adds operational context to this exception for better diagnostics.
+     *
+     * @param operation - Name of the operation that failed
+     * @param context - Additional context key-value pairs
+     * @returns This exception for method chaining
+     *
+     * @example
+     * throw new FileNotFound('Not found')
+     *   .withContext('openFile', { path: '/tmp/doc.pdf' });
+     */
+    withContext(operation: string, context?: Record<string, any>): this;
+    /**
+     * Get a comprehensive error message with all details
+     * @returns Formatted error message with context and suggestions
+     */
+    getFullMessage(): string;
+    /**
+     * Convert error to JSON for logging/monitoring
+     * @returns JSON representation of the error
+     */
+    toJSON(): {
+        name: string;
+        code: string;
+        message: string;
+        category: ErrorCategory;
+        severity: ErrorSeverity;
+        details: PdfErrorDetails;
+        recovery: ErrorRecovery;
+        stack: string | undefined;
+    };
+}
+export declare class ParseException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class InvalidStructure extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class CorruptedData extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class UnsupportedVersion extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class IoException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class FileNotFound extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class PermissionDenied extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class DiskFull extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class NetworkError extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class EncryptionException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class InvalidPassword extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class DecryptionFailed extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class UnsupportedAlgorithm extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class InvalidStateException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class DocumentClosed extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class OperationNotAllowed extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class InvalidOperation extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class UnsupportedFeatureException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class FeatureNotImplemented extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class FormatNotSupported extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class EncodingNotSupported extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class ValidationException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class InvalidParameter extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class InvalidValue extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class MissingRequired extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class TypeMismatch extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class RenderingException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class RenderFailed extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class UnsupportedRenderFormat extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class InsufficientMemory extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class SearchException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class SearchFailed extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class InvalidPattern extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class IndexCorrupted extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class SignatureException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class CertificateLoadFailed extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class SigningFailed extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class RedactionException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class AccessibilityException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class OptimizationException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class ComplianceException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class InvalidCompliance extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class ValidationFailed extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class OcrException extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class RecognitionFailed extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class LanguageNotSupported extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class ImageProcessingFailed extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class UnknownError extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+export declare class InternalError extends PdfException {
+    constructor(message: string, details?: PdfErrorDetails);
+}
+/**
+ * Maps Rust error type names to JavaScript exception types.
+ */
+export declare const ERROR_MAP: Record<string, new (message: string, details?: PdfErrorDetails) => PdfException>;
+/**
+ * Maps a Rust error type to a JavaScript exception.
+ *
+ * @param rustErrorType - Rust error type name
+ * @param message - Error message
+ * @param details - Additional context
+ * @returns Appropriate error instance
+ *
+ * @example
+ * try {
+ *   // Native call
+ * } catch (err) {
+ *   const jsErr = mapError('FileNotFound', 'File does not exist', { path: '/tmp/doc.pdf' });
+ *   throw jsErr;
+ * }
+ */
+export declare function mapError(rustErrorType: string, message: string, details?: PdfErrorDetails): PdfException;
+/**
+ * Maps a numeric FFI error code from the Rust layer to a JavaScript exception.
+ *
+ * FFI Error Codes:
+ * - 0: Success (no error)
+ * - 1: I/O error
+ * - 2: Parse error
+ * - 3: Encryption error
+ * - 4: Invalid state error
+ * - 5: Rendering unsupported
+ * - 6: OCR unsupported
+ * - 7: Invalid argument
+ * - 8: Signature error
+ * - 100: Internal/generic error
+ *
+ * @param errorCode - Numeric FFI error code from native layer
+ * @param message - Optional error message override
+ * @returns Appropriate error instance
+ *
+ * @example
+ * const errorCode = nativeCall();
+ * if (errorCode !== 0) {
+ *   throw mapFfiErrorCode(errorCode, 'Operation failed');
+ * }
+ */
+export declare function mapFfiErrorCode(errorCode: number, message?: string): PdfException;
+/**
+ * Creates an error with optional context.
+ *
+ * @param code - 4-digit error code
+ * @param message - Error message
+ * @param options - Configuration options
+ * @returns Created exception
+ *
+ * @example
+ * const err = createError('7100', 'Rendering failed', {
+ *   operation: 'renderPage',
+ *   context: { page: 0, format: 'png' }
+ * });
+ */
+export declare function createError(code: string, message: string, options?: {
+    operation?: string;
+    context?: Record<string, any>;
+}): PdfException;
+/**
+ * Maps native error to appropriate PDF exception.
+ *
+ * @param error - The error to wrap
+ * @returns Wrapped exception
+ *
+ * @example
+ * try {
+ *   // Native call
+ * } catch (err) {
+ *   const wrapped = wrapError(err);
+ *   console.log(wrapped.code); // e.g., "2100"
+ * }
+ */
+export declare function wrapError(error: unknown): PdfException;
+/**
+ * Function signature for methods to be wrapped
+ */
+type MethodFunction = (...args: any[]) => any;
+type AsyncMethodFunction = (...args: any[]) => Promise<any>;
+/**
+ * Creates a method wrapper that catches native errors and converts them.
+ *
+ * @param fn - The method to wrap
+ * @param thisArg - The context (this) to bind
+ * @returns Wrapped function with error conversion
+ *
+ * @example
+ * const wrapped = wrapMethod(nativeMethod, this);
+ * const result = wrapped(arg1, arg2); // Throws PdfException on error
+ */
+export declare function wrapMethod<T extends MethodFunction>(fn: T, thisArg?: any): T;
+/**
+ * Creates an async method wrapper that catches native errors.
+ *
+ * @param fn - The async method to wrap
+ * @param thisArg - The context (this) to bind
+ * @returns Wrapped async function with error conversion
+ *
+ * @example
+ * const wrapped = wrapAsyncMethod(nativeAsyncMethod, this);
+ * const result = await wrapped(arg1, arg2); // Throws PdfException on error
+ */
+export declare function wrapAsyncMethod<T extends AsyncMethodFunction>(fn: T, thisArg?: any): T;
+export {};