@visulima/storage 1.0.0-alpha.1 → 1.0.0-alpha.3

package/dist/utils/file-path-url-matcher.d.ts

@@ -0,0 +1,18 @@
+declare const filePathUrlMatcher: (path: string) => {
+    params: PathMatch;
+    path: string;
+} | undefined;
+/**
+ * Parsed URL components from file path matching.
+ */
+export type PathMatch = {
+    /** File extension (e.g., "jpg", "png") */
+    ext?: string;
+    /** Metadata request type (e.g., "metadata") */
+    metadata?: string;
+    /** Path segments before the UUID */
+    path?: string[];
+    /** File UUID identifier */
+    uuid: string;
+};
+export default filePathUrlMatcher;

package/dist/utils/headers.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Enhanced HTTP header utilities using remix-run/headers for type-safe header manipulation.
+ * This module provides internal utilities for the storage package to handle complex headers.
+ */
+import { Accept, ContentDisposition, ContentType, SuperHeaders } from "@remix-run/headers";
+import type { Headers as UploadHeaders } from "./types.d.ts";
+/**
+ * Cache-Control directive options
+ */
+export interface CacheControlOptions {
+    immutable?: boolean;
+    maxAge?: number;
+    minFresh?: number;
+    mustRevalidate?: boolean;
+    noCache?: boolean;
+    noStore?: boolean;
+    private?: boolean;
+    proxyRevalidate?: boolean;
+    public?: boolean;
+    sMaxAge?: number;
+    staleIfError?: number;
+    staleWhileRevalidate?: number;
+}
+/**
+ * Utility functions for working with HTTP headers using \@remix-run/headers.
+ */
+export declare const HeaderUtilities: {
+    /**
+     * Check if client accepts a specific media type based on Accept header.
+     * @param acceptHeader HTTP Accept header value
+     * @param mediaType Media type to check for acceptance
+     * @returns True if the media type is accepted by the client
+     */
+    acceptsMediaType(acceptHeader: string | undefined, mediaType: string): boolean;
+    /**
+     * Create Cache-Control header value from options.
+     * @param options Cache control directives configuration
+     * @returns Cache-Control header value string
+     */
+    createCacheControl(options: CacheControlOptions): string;
+    /**
+     * Create common cache control presets with predefined configurations.
+     * @param preset Preset name ('no-cache', 'no-store', 'public', 'private', or 'immutable')
+     * @returns Cache-Control header value string for the preset
+     */
+    createCacheControlPreset(preset: "no-cache" | "no-store" | "public" | "private" | "immutable"): string;
+    /**
+     * Create Content-Disposition header for file downloads with optional filename.
+     * @param options
+     * @param options.filename Filename for the download
+     * @param options.filenameSplat Alternative filename format
+     * @param options.type Disposition type ('inline' or 'attachment')
+     * @returns Content-Disposition header value string
+     */
+    createContentDisposition(options: {
+        filename?: string;
+        filenameSplat?: string;
+        type: "inline" | "attachment";
+    }): string;
+    /**
+     * Create Content-Type header value from structured data with optional charset and boundary.
+     * @param options
+     * @param options.boundary Multipart boundary string
+     * @param options.charset Character encoding (e.g., 'utf8')
+     * @param options.mediaType MIME media type (e.g., 'application/json')
+     * @returns Content-Type header value string
+     */
+    createContentType(options: {
+        boundary?: string;
+        charset?: string;
+        mediaType: string;
+    }): string;
+    /**
+     * Get content type with charset if not already present.
+     * @param contentType Content-Type header value to ensure charset for
+     * @param defaultCharset Default charset to use if not present (default: 'utf8')
+     * @returns Content-Type header value with charset ensured
+     */
+    ensureCharset(contentType: string, defaultCharset?: string): string;
+    /**
+     * Convert our Headers type to EnhancedHeaders from remix-run/headers.
+     * @param headers Headers in array or object format
+     * @returns SuperHeaders instance with converted header values
+     */
+    fromHeaders(headers: UploadHeaders): SuperHeaders;
+    /**
+     * Get preferred media type from Accept header based on quality factors and supported types.
+     * @param acceptHeader HTTP Accept header value
+     * @param supportedTypes Array of supported MIME types to match against
+     * @returns Best matching media type or undefined if no match found
+     */
+    getPreferredMediaType(acceptHeader: string | undefined, supportedTypes: string[]): string | undefined;
+    /**
+     * Parse Accept header with quality factor support.
+     * @param headerValue HTTP Accept header value to parse
+     * @returns Accept instance or undefined if header is invalid or missing
+     */
+    parseAccept(headerValue: string | undefined): Accept | undefined;
+    /**
+     * Parse Content-Disposition header into structured object.
+     * @param headerValue HTTP Content-Disposition header value to parse
+     * @returns ContentDisposition instance or undefined if header is invalid or missing
+     */
+    parseContentDisposition(headerValue: string | undefined): ContentDisposition | undefined;
+    /**
+     * Parse Content-Type header with structured access to media type, charset, and boundary.
+     * @param headerValue HTTP Content-Type header value to parse
+     * @returns ContentType instance or undefined if header is invalid or missing
+     */
+    parseContentType(headerValue: string | undefined): ContentType | undefined;
+};

package/dist/utils/http.d.ts

@@ -0,0 +1,92 @@
+import type { IncomingMessage, OutgoingHttpHeader, ServerResponse } from "node:http";
+import { Readable } from "node:stream";
+import type { Headers, IncomingMessageWithBody } from "./types.d.ts";
+/**
+ * Reads the body of an HTTP request as a string with optional size limit.
+ * @param request HTTP request object to read body from
+ * @param encoding Text encoding to use (defaults to 'utf8')
+ * @param limit Maximum body size in characters (throws error if exceeded)
+ * @returns Promise resolving to the request body as a string
+ */
+export declare const readBody: (request: IncomingMessage, encoding: BufferEncoding, limit: number | undefined) => Promise<string>;
+/**
+ * Retrieve the value of a specific header of an HTTP request.
+ * @param request request object
+ * @param name name of the header
+ * @param all if true, returns  all values of the header, comma-separated, otherwise returns the last value.
+ */
+/**
+ * Get a header value. If `all` is true, returns the comma-joined value.
+ */
+export declare const getHeader: (request: IncomingMessage, name: string, all?: boolean) => string;
+/**
+ * Extracts JSON metadata from an HTTP request body.
+ * Parses the request body as JSON if the content type is 'application/json'.
+ * @param request HTTP request with potential body data
+ * @param limit Maximum body size limit in bytes (default: 16MB)
+ * @returns Parsed metadata object, or empty object if not JSON
+ */
+export declare const getMetadata: (request: IncomingMessageWithBody<Record<string, unknown>>, limit?: number) => Promise<Record<string, unknown>>;
+/**
+ * Appends value to the end of the multi-value header
+ */
+/** Append a value to a multi-valued response header. */
+export declare const appendHeader: (response: ServerResponse, name: string, value: OutgoingHttpHeader) => void;
+/**
+ * Sets the value of a specific header of an HTTP response.
+ */
+/** Set multiple response headers and expose them for CORS. */
+export declare const setHeaders: (response: ServerResponse, headers?: Headers) => void;
+/**
+ * Extracts host with port from a HTTP or HTTPS request.
+ * Prefers x-forwarded-host header for proxy compatibility.
+ * @param request HTTP request object
+ * @returns Host string with port (e.g., "example.com:8080")
+ */
+export declare const extractHost: (request: IncomingMessage & {
+    host?: string;
+    hostname?: string;
+}) => string;
+/**
+ * Extracts protocol from a HTTP or HTTPS request.
+ * Prefers x-forwarded-proto header for proxy compatibility.
+ * @param request HTTP request object
+ * @returns Protocol string ('http' or 'https')
+ */
+export declare const extractProto: (request: IncomingMessage) => string;
+/**
+ * Try build a protocol:hostname:port string from a request object.
+ */
+/** Build protocol://host from an IncomingMessage using forwarded headers. */
+export declare const getBaseUrl: (request: IncomingMessage) => string;
+/**
+ * Extracts the real path from a request URL, excluding query parameters.
+ * Prefers originalUrl for Express compatibility.
+ * @internal
+ * @param request HTTP request object
+ * @returns The path component of the URL without query parameters
+ * @throws TypeError if path is undefined
+ */
+export declare const getRealPath: (request: IncomingMessage & {
+    originalUrl?: string;
+}) => string;
+/**
+ * @internal
+ */
+export declare const uuidRegex: RegExp;
+/**
+ * Extracts a UUID identifier from the request URL path.
+ * Uses regex pattern to match UUID-like strings in the URL.
+ * @internal
+ * @param request HTTP request object
+ * @returns The extracted UUID identifier
+ * @throws TypeError if no valid ID is found in the path
+ */
+export declare const getIdFromRequest: (request: IncomingMessage & {
+    originalUrl?: string;
+}) => string;
+/**
+ * Converts a request to a Node.js Readable stream.
+ * Handles both Node.js IncomingMessage and Web API Request objects.
+ */
+export declare const getRequestStream: (request: IncomingMessage | Request) => Readable;

package/dist/utils/locker.d.ts

@@ -0,0 +1,26 @@
+import { LRUCache as Cache } from "lru-cache";
+/**
+ * A simple lock map keyed by strings, backed by LRUCache. Locks
+ * automatically expire according to the configured TTL preventing deadlocks.
+ */
+declare class Locker<K extends string = string, V extends string = string> extends Cache<K, V, number> {
+    /**
+     * Creates a new Locker instance with configurable TTL and cache options.
+     * @param options LRU cache configuration options
+     */
+    constructor(options?: Cache.Options<K, V, number>);
+    /**
+     * Acquires a lock for the specified key.
+     * Throws an error if the key is already locked.
+     * @param key The key to lock
+     * @returns The lock token (same as the key)
+     * @throws Error if the key is already locked
+     */
+    lock(key: K): string;
+    /**
+     * Releases the lock for the specified key.
+     * @param key The key to unlock
+     */
+    unlock(key: K): void;
+}
+export default Locker;

package/dist/utils/pipes/stream-checksum.d.ts

@@ -0,0 +1,47 @@
+import type { BinaryToTextEncoding } from "node:crypto";
+import { PassThrough, Transform } from "node:stream";
+/**
+ * Transform stream that validates checksums as data passes through.
+ * Calculates hash of streaming data and validates against expected checksum.
+ */
+export declare class StreamChecksum extends Transform {
+    readonly checksum: string;
+    readonly algorithm: string;
+    private readonly encoding;
+    length: number;
+    private digest;
+    private hash;
+    /**
+     * Gets the calculated digest value after the stream has finished processing.
+     * @returns The digest value in the configured encoding, or empty string if not yet calculated
+     */
+    get calculatedDigest(): string;
+    /**
+     * Creates a new StreamChecksum transform stream.
+     * @param checksum Expected checksum value to validate against
+     * @param algorithm Hash algorithm to use (e.g., 'md5', 'sha256')
+     * @param encoding Encoding for the checksum comparison (defaults to 'base64')
+     */
+    constructor(checksum: string, algorithm: string, encoding?: BinaryToTextEncoding);
+    /**
+     * Transform method that updates the hash with incoming data.
+     * @param chunk Buffer chunk to process
+     * @param _encoding Unused encoding parameter
+     * @param done Callback to signal completion
+     */
+    _transform(chunk: Buffer, _encoding: string, done: () => void): void;
+    /**
+     * Finalization method that validates the checksum.
+     * @param callback Callback called with error if checksum validation fails
+     */
+    _flush(callback: (error?: Error) => void): void;
+}
+/**
+ * Factory function that returns either a StreamChecksum transform or a PassThrough stream.
+ * Returns PassThrough when no algorithm is provided.
+ * @param checksum Expected checksum value
+ * @param algorithm Hash algorithm (if empty, returns PassThrough)
+ * @param encoding Encoding for checksum comparison
+ * @returns StreamChecksum instance or PassThrough stream
+ */
+export declare const streamChecksum: (checksum: string, algorithm: string, encoding?: BinaryToTextEncoding) => PassThrough | StreamChecksum;

package/dist/utils/pipes/stream-length.d.ts

@@ -0,0 +1,22 @@
+import { Transform } from "node:stream";
+/**
+ * Transform stream that tracks byte length and enforces size limits.
+ * Counts total bytes passing through and optionally enforces a maximum limit.
+ */
+declare class StreamLength extends Transform {
+    readonly limit: number;
+    length: number;
+    /**
+     * Creates a new StreamLength transform stream.
+     * @param limit Maximum number of bytes allowed (defaults to infinity)
+     */
+    constructor(limit?: number);
+    /**
+     * Transform method that counts bytes and enforces size limits.
+     * @param chunk Buffer chunk to process
+     * @param _encoding Unused encoding parameter
+     * @param callback Callback called with error if limit exceeded
+     */
+    _transform(chunk: Buffer, _encoding: string, callback: (error?: Error) => void): void;
+}
+export default StreamLength;

package/dist/utils/primitives/get-last-one.d.ts

@@ -0,0 +1,3 @@
+/** Return the last element of an array. */
+declare const getLastOne: <T>(value: T[]) => T;
+export default getLastOne;

package/dist/utils/primitives/is-record.d.ts

@@ -0,0 +1,2 @@
+declare const isRecord: (x: unknown) => x is Record<string, unknown>;
+export default isRecord;

package/dist/utils/primitives/map-values.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Maps object values using a transformation function.
+ * @param object The source object to map values from
+ * @param function_ The function to transform each value
+ * @returns A new object with transformed values
+ * @template T - The type of the transformed values
+ */
+declare const mapValues: <T>(object: Record<string, unknown>, function_: (value: unknown) => T) => Record<string, T>;
+export default mapValues;

package/dist/utils/primitives/pick.d.ts

@@ -0,0 +1,2 @@
+declare const pick: <T, K extends keyof T>(object: T, whitelist: K[]) => Pick<T, K>;
+export default pick;

package/dist/utils/primitives/to-milliseconds.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Convert a human-readable duration string to milliseconds.
+ * @param value Duration value (number in ms or human-readable string)
+ * @returns Duration in milliseconds, or undefined if parsing fails
+ * @example
+ * ```ts
+ * toMilliseconds("5m") // 300000
+ * toMilliseconds(5000) // 5000
+ * ```
+ */
+declare const toMilliseconds: (value: number | string | undefined) => number | undefined;
+export default toMilliseconds;

package/dist/utils/primitives/to-seconds.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Convert a human-readable duration string to seconds.
+ * @param value Duration value (number in seconds or human-readable string)
+ * @returns Duration in seconds
+ * @example
+ * ```ts
+ * toSeconds("5m") // 300
+ * toSeconds(300) // 300
+ * ```
+ */
+declare const toSeconds: (value: number | string) => number;
+export default toSeconds;

package/dist/utils/range-checksum.d.ts

@@ -0,0 +1,33 @@
+import type { BinaryToTextEncoding, Hash } from "node:crypto";
+import { Transform } from "node:stream";
+import type { RangeChecksum as IRangeChecksum, RangeHasher as IRangeHasher } from "./types.d.ts";
+/**
+ * Transform stream that calculates checksums for specific file ranges.
+ * Used for validating partial file integrity during resumable uploads.
+ */
+declare class RangeChecksum extends Transform implements IRangeChecksum {
+    readonly path: string;
+    hash: Hash;
+    private readonly hashCopy;
+    private hashes;
+    /**
+     * Creates a new RangeChecksum transform stream.
+     * @param hashes Range hasher instance managing multiple file hashes
+     * @param path File path identifier for this checksum operation
+     */
+    constructor(hashes: IRangeHasher, path: string);
+    /**
+     * Resets the hash state to its initial value.
+     * Useful for reusing the checksum calculator for multiple operations.
+     */
+    reset(): void;
+    /**
+     * Returns the current hash digest in the specified encoding.
+     * @param encoding Output encoding format (default: 'hex')
+     * @returns Hash digest as a string
+     */
+    digest(encoding?: BinaryToTextEncoding): string;
+    _transform(chunk: Buffer, _encoding: string, done: () => void): void;
+    _flush(callback: (error?: Error) => void): void;
+}
+export default RangeChecksum;

package/dist/utils/range-hasher.d.ts

@@ -0,0 +1,46 @@
+import type { Hash } from "node:crypto";
+import { LRUCache as Cache } from "lru-cache";
+import type { RangeChecksum as IRangeChecksum } from "./types.d.ts";
+/**
+ * LRU cache-based range hasher for incremental file integrity verification.
+ * Manages multiple file hash calculations with automatic cleanup and persistence.
+ */
+declare class RangeHasher extends Cache<string, Hash, number> {
+    algorithm: "md5" | "sha1";
+    /**
+     * Creates a new RangeHasher instance.
+     * @param algorithm Hash algorithm to use (default: 'sha1')
+     * @param options LRU cache configuration options
+     */
+    constructor(algorithm?: "md5" | "sha1", options?: Cache.Options<string, Hash, number>);
+    /**
+     * Returns the hex-encoded digest for a previously initialized path.
+     * @param path File path identifier
+     * @returns Hex-encoded hash digest, or empty string if not found
+     */
+    hex(path: string): string;
+    /**
+     * Returns the base64-encoded digest for a previously initialized path.
+     * @param path File path identifier
+     * @returns Base64-encoded hash digest, or empty string if not found
+     */
+    base64(path: string): string;
+    /**
+     * Initializes or continues a hasher for a file from the specified offset.
+     * Returns cached hash if available, otherwise calculates from filesystem.
+     * @param path File path to hash
+     * @param start Starting offset in bytes (default: 0)
+     * @returns Promise resolving to the hash instance
+     */
+    init(path: string, start?: number): Promise<Hash>;
+    /**
+     * Creates a transform stream that updates the rolling hash for a file path.
+     * Useful for incremental hashing during streaming operations.
+     * @param path File path identifier for hash tracking
+     * @returns RangeChecksum transform stream instance
+     */
+    digester(path: string): IRangeChecksum;
+    updateFromFs(path: string, start?: number, initial?: Hash): Promise<Hash>;
+    private fromFs;
+}
+export default RangeHasher;

package/dist/utils/retry.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Retry configuration options for storage operations
+ */
+export interface RetryConfig {
+    /**
+     * Multiplier for exponential backoff (e.g., 2 means delays double each retry)
+     * @default 2
+     */
+    backoffMultiplier?: number;
+    /**
+     * Custom function to calculate delay for a specific retry attempt
+     * @param attempt The current retry attempt (0-indexed)
+     * @param error The error that occurred
+     * @returns Delay in milliseconds, or undefined to use default exponential backoff
+     */
+    calculateDelay?: (attempt: number, error: unknown) => number | undefined;
+    /**
+     * Initial delay in milliseconds before first retry
+     * @default 1000
+     */
+    initialDelay?: number;
+    /**
+     * Maximum delay in milliseconds between retries
+     * @default 30000
+     */
+    maxDelay?: number;
+    /**
+     * Maximum number of retry attempts
+     * @default 3
+     */
+    maxRetries?: number;
+    /**
+     * HTTP status codes that should trigger a retry
+     * @default [408, 429, 500, 502, 503, 504]
+     */
+    retryableStatusCodes?: number[];
+    /**
+     * Custom function to determine if an error should be retried
+     * @param error The error that occurred
+     * @returns true if the error should be retried, false otherwise
+     */
+    shouldRetry?: (error: unknown) => boolean;
+}
+/**
+ * Determines if an error is retryable based on common patterns
+ * @param error The error to check
+ * @param retryableStatusCodes HTTP status codes that should trigger retry
+ * @returns true if the error is retryable
+ */
+export declare const isRetryableError: (error: unknown, retryableStatusCodes?: number[]) => boolean;
+/**
+ * Retry an async operation with exponential backoff
+ * @param fn The async function to retry
+ * @param config Retry configuration
+ * @returns The result of the function
+ * @throws The last error if all retries are exhausted
+ */
+export declare const retry: <T>(function_: () => Promise<T>, config?: RetryConfig) => Promise<T>;
+/**
+ * Create a retry wrapper function with pre-configured settings.
+ * @param config Retry configuration
+ * @returns A function that wraps async operations with retry logic
+ */
+export declare const createRetryWrapper: (config?: RetryConfig) => <T>(function_: () => Promise<T>) => Promise<T>;

package/dist/utils/types.d.ts

@@ -0,0 +1,108 @@
+import type { BinaryToTextEncoding, Hash } from "node:crypto";
+import type { IncomingMessage } from "node:http";
+import type { Transform } from "node:stream";
+import type { LRUCache as Cache } from "lru-cache";
+/**
+ * Transform that computes a rolling checksum for a stream while passing
+ * data through unchanged.
+ */
+export interface RangeChecksum extends Transform {
+    /** Return the current digest in the selected encoding. */
+    digest: (encoding: BinaryToTextEncoding) => string;
+    hash: Hash;
+    path: string;
+    reset: () => void;
+}
+/**
+ * LRU-backed map of rolling hashers keyed by file path. Used to compute
+ * hex/base64 digests and resume hashing from an offset.
+ */
+export interface RangeHasher extends Cache<string, Hash> {
+    algorithm: "md5" | "sha1";
+    base64: (path: string) => string;
+    digester: (path: string) => RangeChecksum;
+    hex: (path: string) => string;
+    init: (path: string, start: number) => Promise<Hash>;
+    updateFromFs: (path: string, start: number, initial?: Hash) => Promise<Hash>;
+}
+/**
+ * Normalized HTTP error payload returned by handlers and storage backends.
+ */
+export interface HttpErrorBody {
+    code: string;
+    detail?: Record<string, unknown> | string;
+    message: string;
+    name?: string;
+    retryable?: boolean;
+    UploadErrorCode?: string;
+}
+/**
+ * Rich HTTP error including status code and optional headers/body.
+ */
+export interface HttpError<T = HttpErrorBody> extends UploadResponse<T> {
+    statusCode: number;
+}
+/**
+ * Node.js IncomingMessage with an optional parsed body attached.
+ */
+export interface IncomingMessageWithBody<T = unknown> extends IncomingMessage {
+    _body?: boolean;
+    body?: T;
+}
+export type Header = string[] | number | string;
+export type Headers = Record<string, Header>;
+export type ResponseBody = Record<string, unknown> | string | Buffer | Uint8Array;
+export type ResponseBodyType = "json" | "text";
+/**
+ * Tuple form for quick response definitions: [status, body, headers].
+ */
+export type ResponseTuple<T = ResponseBody> = [statusCode: number, body?: T, headers?: Headers];
+/**
+ * Structured response used across handlers and storage operations.
+ */
+export interface UploadResponse<T = ResponseBody> extends Record<string, unknown> {
+    body?: T;
+    headers?: Headers;
+    statusCode?: number;
+}
+/**
+ * Declarative validator configuration for a single rule.
+ */
+export interface ValidatorConfig<T> {
+    isValid?: (t: T) => Promise<boolean> | boolean;
+    response?: HttpError<HttpErrorBody> | ResponseTuple<ResponseBody>;
+    value?: unknown;
+}
+/** Map of rule-name -> validator configuration. */
+export type Validation<T> = Record<string, ValidatorConfig<T>>;
+/** Narrowed error response shape for validation failures. */
+export interface ValidationError extends HttpError {
+    code: string;
+}
+/**
+ * Metrics interface for observability.
+ * Provides counters, timers, and gauges for tracking storage operations.
+ */
+export interface Metrics {
+    /**
+     * Set a gauge metric value.
+     * @param name Metric name (e.g., "storage.files.size")
+     * @param value Gauge value
+     * @param attributes Optional attributes/labels
+     */
+    gauge: (name: string, value: number, attributes?: Record<string, string | number>) => void;
+    /**
+     * Increment a counter metric.
+     * @param name Metric name (e.g., "storage.operations.create.count")
+     * @param value Increment value (default: 1)
+     * @param attributes Optional attributes/labels (e.g., { storage: "s3", operation: "create" })
+     */
+    increment: (name: string, value?: number, attributes?: Record<string, string | number>) => void;
+    /**
+     * Record a duration/timing metric in milliseconds.
+     * @param name Metric name (e.g., "storage.operations.write.duration")
+     * @param duration Duration in milliseconds
+     * @param attributes Optional attributes/labels
+     */
+    timing: (name: string, duration: number, attributes?: Record<string, string | number>) => void;
+}

package/dist/utils/validation-error.d.ts

@@ -0,0 +1,22 @@
+import type { Headers, HttpErrorBody, ValidationError as IValidationError } from "./types.d.ts";
+/**
+ * Error class for validation failures with detailed error information.
+ * Implements the ValidationError interface for consistent error handling.
+ */
+declare class ValidationError extends Error implements IValidationError {
+    readonly code: string;
+    readonly statusCode: number;
+    readonly body: HttpErrorBody;
+    readonly headers: Headers;
+    readonly name: string;
+    [key: string]: unknown;
+    /**
+     * Creates a new ValidationError instance.
+     * @param code Machine-readable error code
+     * @param statusCode HTTP status code for the error
+     * @param body Error response body (string or structured object)
+     * @param headers HTTP headers to include in error response
+     */
+    constructor(code: string, statusCode: number, body: HttpErrorBody, headers: Headers);
+}
+export default ValidationError;