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

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

@@ -1,46 +0,0 @@
-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

@@ -1,64 +0,0 @@
-/**
- * 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

@@ -1,108 +0,0 @@
-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

@@ -1,22 +0,0 @@
-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;

package/dist/utils/validator.d.ts

@@ -1,36 +0,0 @@
-import type { Validation } from "./types.d.ts";
-import ValidationError from "./validation-error.d.ts";
-/**
- * Configurable validation system for file upload constraints.
- * Supports multiple validation rules with custom error responses.
- * @template T - The type being validated
- */
-export declare class Validator<T> {
-    private prefix;
-    private validators;
-    /**
-     * Creates a new Validator instance.
-     * @param prefix Prefix for generated error codes (default: "ValidationError")
-     */
-    constructor(prefix?: string);
-    /**
-     * Adds validation rules to the validator.
-     * Each rule must include an `isValid` function.
-     * @param config Validation configuration object
-     * @throws TypeError if any validator is missing the isValid function
-     */
-    add(config: Validation<T>): void;
-    /**
-     * Verifies an object against all configured validation rules.
-     * Throws ValidationError on first validation failure.
-     * @param t Object to validate
-     * @throws ValidationError if validation fails
-     */
-    verify(t: T): Promise<never | void>;
-}
-/**
- * Type guard to check if an error is a ValidationError instance.
- * @param error Error to check
- * @returns True if the error is a ValidationError
- */
-export declare const isValidationError: (error: unknown) => error is ValidationError;