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

package/dist/storage/local/local-meta-storage.d.ts

@@ -1,32 +0,0 @@
-import MetaStorage from "../meta-storage.d.ts";
-import type { MetaStorageOptions } from "../types.d.ts";
-import type { File } from "../utils/index.d.ts";
-/**
- * Stores upload metafiles on local disk
- */
-declare class LocalMetaStorage<T extends File = File> extends MetaStorage<T> {
-    readonly directory: string;
-    constructor(config?: LocalMetaStorageOptions);
-    /**
-     * Returns metafile path.
-     * @param id upload id
-     */
-    getMetaPath: (id: string) => string;
-    /**
-     * Returns upload id from metafile path.
-     * @internal
-     */
-    getIdFromPath: (metaFilePath: string) => string;
-    save(id: string, file: T): Promise<T>;
-    touch(id: string, file: T): Promise<T>;
-    get(id: string): Promise<T>;
-    delete(id: string): Promise<void>;
-    private accessCheck;
-}
-export interface LocalMetaStorageOptions extends MetaStorageOptions {
-    /**
-     * Where the upload metadata should be stored
-     */
-    directory?: string;
-}
-export default LocalMetaStorage;

package/dist/storage/meta-storage.d.ts

@@ -1,30 +0,0 @@
-import type { MetaStorageOptions } from "./types.d.ts";
-import type { File } from "./utils/index.d.ts";
-/**
- * Stores upload metadata.
- */
-declare class MetaStorage<T extends File = File> {
-    prefix: string;
-    suffix: string;
-    protected readonly logger?: Console;
-    constructor(config?: MetaStorageOptions);
-    /**
-     * Saves upload metadata.
-     */
-    save(_id: string, file: T): Promise<T>;
-    /**
-     * Deletes an upload metadata.
-     */
-    delete(_id: string): Promise<void>;
-    /**
-     * Retrieves upload metadata.
-     */
-    get(_id: string): Promise<T>;
-    /**
-     * Marks upload active.
-     */
-    touch(_id: string, _file: T): Promise<T>;
-    getMetaName(id: string): string;
-    getIdFromMetaName(name: string): string;
-}
-export default MetaStorage;

package/dist/storage/netlify-blob/netlify-blob-file.d.ts

@@ -1,12 +0,0 @@
-import { File } from "../utils/index.d.ts";
-declare class NetlifyBlobFile extends File {
-    /**
-     * The blob's public URL
-     */
-    url?: string;
-    /**
-     * The blob's pathname within the store
-     */
-    pathname?: string;
-}
-export default NetlifyBlobFile;

package/dist/storage/netlify-blob/netlify-blob-meta-storage.d.ts

@@ -1,7 +0,0 @@
-import type { LocalMetaStorageOptions } from "../local/local-meta-storage.d.ts";
-import LocalMetaStorage from "../local/local-meta-storage.d.ts";
-import type NetlifyBlobFile from "./netlify-blob-file.d.ts";
-declare class NetlifyBlobMetaStorage extends LocalMetaStorage<NetlifyBlobFile> {
-    constructor(config?: LocalMetaStorageOptions);
-}
-export default NetlifyBlobMetaStorage;

package/dist/storage/netlify-blob/netlify-blob-storage.d.ts

@@ -1,93 +0,0 @@
-import type MetaStorage from "../meta-storage.d.ts";
-import { BaseStorage } from "../storage.d.ts";
-import type { FileInit, FilePart, FileQuery, FileReturn } from "../utils/index.d.ts";
-import NetlifyBlobFile from "./netlify-blob-file.d.ts";
-import type { NetlifyBlobStorageOptions } from "./types.d.ts";
-/**
- * Netlify Blob storage based backend.
- * @example
- * ```ts
- * const storage = new NetlifyBlobStorage({
- *   storeName: 'uploads',
- *   metaStorageConfig: { directory: '/tmp/upload-metafiles' }
- * });
- * ```
- * @remarks
- * ## Supported Operations
- * - ✅ create, write, delete, get, list, copy, move
- * - ✅ Batch operations: deleteBatch, copyBatch, moveBatch (inherited from BaseStorage)
- * - ✅ exists: Implemented (checks metadata and Netlify Blob)
- * - ✅ update: Implemented (updates metadata file, Netlify Blob API doesn't support blob metadata updates)
- * - ❌ getStream: Not implemented (use get() for file retrieval)
- * - ❌ getUrl: Not implemented (Netlify Blob URLs available via Netlify Blob API)
- * - ❌ getUploadUrl: Not implemented (Netlify Blob upload URLs handled internally)
- */
-declare class NetlifyBlobStorage extends BaseStorage<NetlifyBlobFile, FileReturn> {
-    static readonly name: string;
-    checksumTypes: string[];
-    protected meta: MetaStorage<NetlifyBlobFile>;
-    private readonly storeName;
-    private readonly siteID?;
-    private readonly token?;
-    private store;
-    private readonly retry;
-    constructor(config: NetlifyBlobStorageOptions);
-    create(config: FileInit): Promise<NetlifyBlobFile>;
-    write(part: FilePart | FileQuery | NetlifyBlobFile): Promise<NetlifyBlobFile>;
-    /**
-     * Deletes an upload and its metadata.
-     * @param query File query containing the file ID to delete.
-     * @param query.id File ID to delete.
-     * @returns Promise resolving to the deleted file object with status: "deleted".
-     * @throws {UploadError} If the file metadata cannot be found.
-     */
-    delete({ id }: FileQuery): Promise<NetlifyBlobFile>;
-    /**
-     * Checks if a file exists by verifying both metadata and the actual Netlify Blob.
-     * Returns true only if both the metadata and the blob exist.
-     * @param query File query containing the file ID to check.
-     * @returns Promise resolving to true if both metadata and blob exist, false otherwise.
-     */
-    exists({ id }: FileQuery): Promise<boolean>;
-    get({ id }: FileQuery): Promise<FileReturn>;
-    /**
-     * Copies an upload file to a new location.
-     * @param name Source file name/ID.
-     * @param destination Destination file name/ID.
-     * @returns Promise resolving to the copied file object.
-     * @throws {UploadError} If the source file cannot be found.
-     */
-    copy(name: string, destination: string): Promise<NetlifyBlobFile>;
-    /**
-     * Moves an upload file to a new location.
-     * @param name Source file name/ID.
-     * @param destination Destination file name/ID.
-     * @returns Promise resolving to the moved file object.
-     * @throws {UploadError} If the source file cannot be found.
-     */
-    move(name: string, destination: string): Promise<NetlifyBlobFile>;
-    /**
-     * Updates file metadata with user-provided key-value pairs.
-     * Updates the metadata file (overwrites it) but does not update Netlify Blob metadata
-     * since the Netlify Blob API doesn't support metadata updates.
-     * @param query File query containing the file ID to update.
-     * @param query.id File ID to update.
-     * @param metadata Partial file object containing fields to update.
-     * @returns Promise resolving to the updated file object.
-     * @throws {UploadError} If the file cannot be found (ERRORS.FILE_NOT_FOUND).
-     * @remarks
-     * Supports TTL (time-to-live) option: if metadata contains a 'ttl' field,
-     * it will be converted to an 'expiredAt' timestamp.
-     * TTL can be a number (milliseconds) or string (e.g., "1h", "30m", "7d").
-     */
-    update({ id }: FileQuery, metadata: Partial<NetlifyBlobFile>): Promise<NetlifyBlobFile>;
-    list(limit?: number): Promise<NetlifyBlobFile[]>;
-    private internalOnComplete;
-    /**
-     * Generate a URL for a blob in Netlify Blob store
-     * Note: Netlify Blob doesn't provide direct public URLs like Vercel Blob
-     * In production, you would typically serve these through Netlify Functions or Edge Functions
-     */
-    private getBlobUrl;
-}
-export default NetlifyBlobStorage;

package/dist/storage/netlify-blob/types.d.ts

@@ -1,30 +0,0 @@
-import type { LocalMetaStorageOptions } from "../local/local-meta-storage.d.ts";
-import type { BaseStorageOptions } from "../types.d.ts";
-import type NetlifyBlobFile from "./netlify-blob-file.d.ts";
-export interface NetlifyBlobStorageOptions extends BaseStorageOptions<NetlifyBlobFile> {
-    /**
-     * Configure metafiles storage
-     * @example
-     * Using local metafiles
-     * ```ts
-     * const storage = new NetlifyBlobStorage({
-     *   storeName: 'uploads',
-     *   metaStorageConfig: { directory: '/tmp/upload-metafiles' }
-     * })
-     * ```
-     */
-    metaStorageConfig?: LocalMetaStorageOptions;
-    /**
-     * Netlify site ID (optional, used for explicit store access)
-     */
-    siteID?: string;
-    /**
-     * Netlify Blob store name
-     * @default 'default'
-     */
-    storeName?: string;
-    /**
-     * Netlify API token (optional, can use environment variable NETLIFY_TOKEN)
-     */
-    token?: string;
-}

package/dist/storage/storage.d.ts

@@ -1,353 +0,0 @@
-import { Readable } from "node:stream";
-import type { Cache } from "../utils/cache.d.ts";
-import type { ErrorResponses } from "../utils/errors.d.ts";
-import Locker from "../utils/locker.d.ts";
-import type { HttpError, Metrics } from "../utils/types.d.ts";
-import { Validator } from "../utils/validator.d.ts";
-import type MetaStorage from "./meta-storage.d.ts";
-import type { BaseStorageOptions, BatchOperationResponse, PurgeList } from "./types.d.ts";
-import type { File, FileInit, FilePart, FileQuery } from "./utils/index.d.ts";
-import type { FileReturn } from "./utils/file/types.d.ts";
-/**
- * Default filename validation for cloud storage platforms.
- * Permissive validation that only blocks dangerous patterns (path traversal, null bytes).
- * Cloud storage platforms (S3, Azure, GCS) accept most special characters and handle URL encoding automatically.
- */
-export declare const defaultCloudStorageFileNameValidation: (name: string) => boolean;
-/**
- * Default filename validation for local filesystems.
- * Stricter validation that blocks filesystem-incompatible characters.
- */
-export declare const defaultFilesystemFileNameValidation: (name: string) => boolean;
-/**
- * Abstract base class for all storage backends.
- * @template TFile The file type used by this storage backend.
- * @template TFileReturn The return type for file retrieval operations.
- * @remarks
- * ## Error Handling
- *
- * All storage operations follow consistent error handling patterns:
- * - Operations throw `UploadError` with specific error codes (see ERRORS enum)
- * - Common error codes: FILE_NOT_FOUND, GONE (expired), FILE_LOCKED, STORAGE_BUSY
- * - Errors are normalized with storage class context via `normalizeError()`
- * - Batch operations capture individual failures without stopping the batch
- *
- * ## Retry Behavior
- *
- * Storage implementations handle retries differently:
- *
- * ### Cloud Storage (S3, GCS, Azure, Netlify Blob)
- * - Use configurable retry wrappers via `retryConfig` option
- * - Default retryable status codes: 408, 429, 500, 502, 503, 504
- * - Retry logic handles transient network errors and rate limiting
- * - Custom `shouldRetry` functions can be provided for advanced retry logic
- *
- * ### Local Storage (DiskStorage)
- * - No automatic retries (filesystem operations are typically immediate)
- * - Errors are thrown directly for immediate feedback
- *
- * ## Operation Instrumentation
- *
- * All public operations are automatically instrumented via `instrumentOperation()`:
- * - Metrics are recorded for operation count, duration, and errors
- * - File sizes are tracked for operations that return file objects
- * - Error metrics include error messages for debugging
- *
- * ## Metadata Caching
- *
- * File metadata is automatically cached to reduce storage API calls:
- * - Cache is updated on save, delete, and get operations
- * - Cache is invalidated when metadata is deleted
- * - Implementations can override caching behavior if needed
- */
-export declare abstract class BaseStorage<TFile extends File = File, TFileReturn extends FileReturn = FileReturn> {
-    /**
-     * Hook called when a new file is created.
-     * @param file The newly created file object.
-     * @remarks This hook is called after file metadata is saved but before returning the file.
-     * Can be used for side effects like logging, notifications, or custom processing.
-     */
-    onCreate: (file: TFile) => Promise<void> | void;
-    /**
-     * Hook called when file metadata is updated.
-     * @param file The updated file object.
-     * @remarks This hook is called after metadata is updated and saved.
-     * Can be used for side effects like logging or custom processing.
-     */
-    onUpdate: (file: TFile) => Promise<void> | void;
-    /**
-     * Hook called when a file upload is completed.
-     * @param file The completed file object.
-     * @param response The response object that can be modified in place (headers, statusCode, body).
-     * @param request Optional request object for additional context.
-     * @remarks This hook is called when file status becomes "completed".
-     * The response object can be modified directly to add headers or change the status code.
-     */
-    onComplete: (file: TFile, response: unknown, request?: unknown) => Promise<void> | void;
-    /**
-     * Hook called when a file is deleted.
-     * @param file The deleted file object.
-     * @remarks This hook is called after the file is deleted but before returning.
-     * Can be used for side effects like cleanup or logging.
-     */
-    onDelete: (file: TFile) => Promise<void> | void;
-    /**
-     * Hook called when an error occurs during storage operations.
-     * @param error The HTTP error object that can be modified in place.
-     * @remarks This hook allows customizing error responses by modifying the error object.
-     * The error object can be modified to change headers, statusCode, or body properties.
-     * Error formatting happens in handlers after this hook is called.
-     */
-    onError: (error: HttpError) => Promise<void> | void;
-    isReady: boolean;
-    errorResponses: ErrorResponses;
-    cache: Cache<string, TFile>;
-    readonly logger?: Console;
-    readonly metrics: Metrics;
-    readonly genericConfig: BaseStorageOptions<TFile>;
-    maxMetadataSize: number;
-    checksumTypes: string[];
-    maxUploadSize: number;
-    protected expiration?: {
-        maxAge?: string | number;
-        purgeInterval?: string | number;
-        rolling?: boolean;
-    };
-    protected locker: Locker;
-    protected namingFunction: (file: TFile) => string;
-    protected validation: Validator<TFile>;
-    protected abstract meta: MetaStorage<TFile>;
-    protected assetFolder: string | undefined;
-    /**
-     * Limits the number of concurrent upload requests
-     */
-    protected concurrency?: number;
-    protected constructor(config: BaseStorageOptions<TFile>);
-    get tusExtension(): string[];
-    /**
-     * Validates a file against configured validation rules.
-     * @param file File object to validate.
-     * @returns Promise resolving to undefined if file is valid, throws ValidationError otherwise.
-     * @throws {ValidationError} If validation fails
-     */
-    validate(file: TFile): Promise<void>;
-    /**
-     * Checks if a file exists by querying its metadata.
-     * @param query File query containing the file ID to check.
-     * @param query.id File ID to check.
-     * @returns Promise resolving to true if file exists, false otherwise.
-     * @remarks This method does not throw errors - it returns false if the file is not found.
-     */
-    exists(query: FileQuery): Promise<boolean>;
-    /**
-     * Normalizes errors with storage-specific context.
-     * @param error The error to normalize.
-     * @returns Normalized HTTP error with storage class context added to the message.
-     * @remarks Errors are enhanced with the storage class name for better debugging.
-     */
-    normalizeError(error: Error): HttpError;
-    /**
-     * Gets the storage configuration.
-     * @returns The current storage configuration options.
-     */
-    get config(): BaseStorageOptions<TFile>;
-    /**
-     * Saves upload metadata to the metadata storage.
-     * @param file File object containing metadata to save.
-     * @returns Promise resolving to the saved file object.
-     * @remarks Updates timestamps and caches the file metadata.
-     */
-    saveMeta(file: TFile): Promise<TFile>;
-    /**
-     * Deletes upload metadata from the metadata storage.
-     * @param id File ID whose metadata should be deleted.
-     * @returns Promise resolving when metadata is deleted.
-     * @remarks Also removes the file from the cache.
-     */
-    deleteMeta(id: string): Promise<void>;
-    /**
-     * Retrieves upload metadata by file ID.
-     * @param id File ID to retrieve metadata for.
-     * @returns Promise resolving to the file metadata object.
-     * @throws {UploadError} If the file metadata cannot be found (ERRORS.FILE_NOT_FOUND).
-     * @remarks Caches the retrieved metadata for faster subsequent access.
-     */
-    getMeta(id: string): Promise<TFile>;
-    /**
-     * Checks if a file has expired and deletes it if so.
-     * @param file File object to check for expiration.
-     * @returns Promise resolving to the file object if not expired.
-     * @throws {UploadError} If the file has expired (ERRORS.GONE).
-     * @remarks If the file is expired, it is automatically deleted and the metadata is removed.
-     */
-    checkIfExpired(file: TFile): Promise<TFile>;
-    /**
-     * Searches for and purges expired uploads.
-     * @param maxAge Maximum age of files to keep (files older than this will be purged).
-     * Can be a number (milliseconds) or string (e.g., "1h", "30m", "7d").
-     * If not provided, uses the expiration.maxAge from configuration.
-     * @returns Promise resolving to a list of purged files.
-     * @remarks
-     * Errors during individual file deletions are logged but do not stop the purge process.
-     * Files with corrupted metadata are skipped with a warning.
-     * Uses rolling expiration if configured (based on modifiedAt) or fixed expiration (based on createdAt).
-     */
-    purge(maxAge?: number | string): Promise<PurgeList>;
-    /**
-     * Gets an uploaded file by ID.
-     * @param query File query containing the file ID to retrieve.
-     * @param query.id File ID to retrieve.
-     * @returns Promise resolving to the file data including content.
-     * @throws {UploadError} If the file cannot be found (ERRORS.FILE_NOT_FOUND) or has expired (ERRORS.GONE).
-     * @remarks This method loads the entire file content into memory. For large files, use getStream() instead.
-     */
-    abstract get({ id }: FileQuery): Promise<TFileReturn>;
-    /**
-     * Gets an uploaded file as a readable stream for efficient large file handling.
-     * @param query File query containing the file ID to stream.
-     * @param query.id File ID to stream.
-     * @returns Promise resolving to an object containing the stream, headers, and size.
-     * @throws {UploadError} If the file cannot be found (ERRORS.FILE_NOT_FOUND) or has expired (ERRORS.GONE).
-     * @remarks
-     * Default implementation falls back to get() and creates a stream from the buffer.
-     * Storage implementations should override this for better streaming performance.
-     * Headers include Content-Type, Content-Length, ETag, and Last-Modified.
-     */
-    getStream({ id }: FileQuery): Promise<{
-        headers?: Record<string, string>;
-        size?: number;
-        stream: Readable;
-    }>;
-    /**
-     * Retrieves a list of uploaded files.
-     * @param _limit Maximum number of files to return (default: 1000).
-     * @returns Promise resolving to an array of file metadata objects.
-     * @throws {Error} If not implemented by the storage backend.
-     * @remarks Storage implementations must override this method.
-     */
-    list(_limit?: number): Promise<TFile[]>;
-    /**
-     * Updates file metadata with user-provided key-value pairs.
-     * @param query File query containing the file ID to update.
-     * @param query.id File ID to update.
-     * @param metadata Partial file object containing fields to update.
-     * @returns Promise resolving to the updated file object.
-     * @throws {UploadError} If the file cannot be found (ERRORS.FILE_NOT_FOUND).
-     * @remarks
-     * Supports TTL (time-to-live) option: if metadata contains a 'ttl' field,
-     * it will be converted to an 'expiredAt' timestamp.
-     * TTL can be a number (milliseconds) or string (e.g., "1h", "30m", "7d").
-     */
-    update({ id }: FileQuery, metadata: Partial<File>): Promise<TFile>;
-    /**
-     * Creates a new upload and saves its metadata.
-     * @param file File initialization configuration.
-     * @returns Promise resolving to the created file object.
-     */
-    abstract create(file: FileInit): Promise<TFile>;
-    /**
-     * Writes part and/or returns status of an upload.
-     * @param part File part, query, or full file object to write.
-     * @returns Promise resolving to the updated file object.
-     */
-    abstract write(part: FilePart | FileQuery | TFile): Promise<TFile>;
-    /**
-     * Deletes an upload and its metadata.
-     * @param query File query containing the file ID to delete.
-     * @param query.id File ID to delete.
-     * @returns Promise resolving to the deleted file object with status: "deleted".
-     * @throws {UploadError} If the file metadata cannot be found.
-     */
-    abstract delete(query: FileQuery): Promise<TFile>;
-    /**
-     * Copies an upload file to a new location.
-     * @param name Source file name/ID.
-     * @param destination Destination file name/ID.
-     * @param options Optional copy options including storage class.
-     * @returns Promise resolving to the copied file object.
-     * @throws {UploadError} If the source file cannot be found.
-     */
-    abstract copy(name: string, destination: string, options?: {
-        storageClass?: string;
-    }): Promise<TFile>;
-    /**
-     * Moves an upload file to a new location.
-     * @param name Source file name/ID.
-     * @param destination Destination file name/ID.
-     * @returns Promise resolving to the moved file object.
-     * @throws {UploadError} If the source file cannot be found.
-     */
-    abstract move(name: string, destination: string): Promise<TFile>;
-    /**
-     * Deletes multiple files in a single batch operation.
-     * @param ids Array of file IDs to delete.
-     * @returns Promise resolving to batch operation response with successful and failed deletions.
-     * @remarks
-     * Processes all deletions in parallel using Promise.allSettled.
-     * Individual failures do not stop the batch operation.
-     * Each deletion is wrapped in error handling to capture failures.
-     * Metrics are recorded for the batch operation and individual failures.
-     * Returns both successful and failed operations with detailed error information.
-     */
-    deleteBatch(ids: string[]): Promise<BatchOperationResponse<TFile>>;
-    /**
-     * Copies multiple files in a single batch operation.
-     * @param operations Array of copy operations, each containing:
-     * source: Source file ID.
-     * destination: Destination file ID or path.
-     * options: Optional copy options including storage class.
-     * @returns Promise resolving to batch operation response with successful and failed copies.
-     * @remarks
-     * Processes all copies in parallel using Promise.allSettled.
-     * Individual failures do not stop the batch operation.
-     * Each copy operation is wrapped in error handling to capture failures.
-     * Metrics are recorded for the batch operation and individual failures.
-     * Returns both successful and failed operations with detailed error information.
-     */
-    copyBatch(operations: {
-        destination: string;
-        options?: {
-            storageClass?: string;
-        };
-        source: string;
-    }[]): Promise<BatchOperationResponse<TFile>>;
-    /**
-     * Moves multiple files in a single batch operation.
-     * @param operations Array of move operations, each containing:
-     * source: Source file ID.
-     * destination: Destination file ID or path.
-     * @returns Promise resolving to batch operation response with successful and failed moves.
-     * @remarks
-     * Processes all moves in parallel using Promise.allSettled.
-     * Individual failures do not stop the batch operation.
-     * Each move operation is wrapped in error handling to capture failures.
-     * Metrics are recorded for the batch operation and individual failures.
-     * Returns both successful and failed operations with detailed error information.
-     */
-    moveBatch(operations: {
-        destination: string;
-        source: string;
-    }[]): Promise<BatchOperationResponse<TFile>>;
-    /**
-     * Prevent upload from being accessed by multiple requests
-     */
-    protected lock(key: string): Promise<string>;
-    protected unlock(key: string): Promise<void>;
-    protected isUnsupportedChecksum(algorithm?: string): boolean;
-    protected startAutoPurge(purgeInterval: number): void;
-    protected updateTimestamps(file: TFile): TFile;
-    /**
-     * Instruments a storage operation with metrics and error tracking.
-     * @param operation Operation name (e.g., "create", "delete", "copy").
-     * @param function_ The operation function to execute.
-     * @param attributes Additional attributes to include in metrics.
-     * @returns Promise resolving to the operation result.
-     * @throws Re-throws any errors from the operation function.
-     * @remarks
-     * Records operation count, duration, and error metrics.
-     * Tracks file sizes for operations returning file objects.
-     * Error metrics include error messages for debugging.
-     * All public methods should use this wrapper for consistent instrumentation.
-     */
-    protected instrumentOperation<T>(operation: string, function_: () => Promise<T>, attributes?: Record<string, string | number>): Promise<T>;
-}