@visulima/storage 1.0.0-alpha.9 → 1.0.0

package/dist/storage/types.d.ts

@@ -1,221 +0,0 @@
-import type { Readable } from "node:stream";
-import type { Cache } from "../utils/cache.d.ts";
-import type { RetryConfig } from "../utils/retry.d.ts";
-import type { HttpError, HttpErrorBody, Metrics, Validation } from "../utils/types.d.ts";
-import type { LocalMetaStorageOptions } from "./local/local-meta-storage.d.ts";
-import type MetaStorage from "./meta-storage.d.ts";
-import type { File, FileInit, FilePart, FileQuery, FileReturn, UploadFile } from "./utils/index.d.ts";
-export interface MetaStorageOptions {
-    logger?: Console;
-    prefix?: string;
-    suffix?: string;
-}
-export type OnCreate<TFile extends File = File> = (file: TFile) => Promise<void> | void;
-export type OnUpdate<TFile extends File = File> = (file: TFile) => Promise<void> | void;
-export type OnComplete<TFile extends File = File, TResponse = unknown, TRequest = unknown> = (file: TFile, response: TResponse, request?: TRequest) => Promise<void> | void;
-export type OnDelete<TFile extends File = File> = (file: TFile) => Promise<void> | void;
-export type OnError<TBody = HttpErrorBody> = (error: HttpError<TBody>) => Promise<void> | void;
-export interface PurgeList {
-    items: UploadFile[];
-    maxAgeMs: number;
-}
-export interface ExpirationOptions {
-    /**
-     * Age of the upload, after which it is considered expired and can be deleted
-     */
-    maxAge: number | string;
-    /**
-     * Auto purging interval for expired upload
-     */
-    purgeInterval?: number | string;
-    /**
-     * Auto prolong expiring upload
-     */
-    rolling?: boolean;
-}
-export interface BaseStorageOptions<T extends File = File> extends GenericStorageConfig {
-    /** Allowed MIME types */
-    allowMIME?: string[];
-    /** The full path of the folder where the uploaded asset will be stored. */
-    assetFolder?: string;
-    /** Cache instance to use for caching */
-    cache?: Cache;
-    /**
-     * Automatic cleaning of abandoned and completed upload
-     * @example
-     * ```ts
-     * app.use(
-     *   '/upload',
-     *   Upload.upload({
-     *     directory: 'upload',
-     *     expiration: { maxAge: '6h', purgeInterval: '30min' },
-     *     onComplete
-     *   })
-     * );
-     * ```
-     */
-    expiration?: ExpirationOptions;
-    /** File naming function */
-    filename?: (file: T) => string;
-    /**
-     * File name validation function.
-     * Returns true if the filename is valid, false otherwise.
-     * @default Cloud storage platforms: permissive (only blocks path traversal and null bytes)
-     * @default DiskStorage: strict (blocks filesystem-incompatible characters)
-     * @example
-     * ```ts
-     * fileNameValidation: (name: string) => {
-     *   // Custom validation logic
-     *   return name.length > 0 && !name.includes('../');
-     * }
-     * ```
-     */
-    fileNameValidation?: (name: string) => boolean;
-    /** Logger injection */
-    logger?: Console;
-    /** Limiting the size of custom metadata */
-    maxMetadataSize?: number | string;
-    /** File size limit */
-    maxUploadSize?: number | string;
-    /** Provide custom meta storage  */
-    metaStorage?: MetaStorage<T>;
-    /** Metrics injection for observability */
-    metrics?: Metrics;
-    /** Callback function that is called when an upload is completed */
-    onComplete?: OnComplete<T>;
-    /** Callback function that is called when a new upload is created */
-    onCreate?: OnCreate<T>;
-    /** Callback function that is called when an upload is cancelled */
-    onDelete?: OnDelete<T>;
-    /** Customize error response */
-    onError?: OnError;
-    /** Callback function that is called when an upload is updated */
-    onUpdate?: OnUpdate<T>;
-    /** Force relative URI in Location header */
-    useRelativeLocation?: boolean;
-    /** Upload validation options */
-    validation?: Validation<T>;
-}
-export type DiskStorageOptions<T extends File> = BaseStorageOptions<T> & {
-    /**
-     * Uploads directory.
-     */
-    directory: string;
-    /**
-     * Configuring metafile storage on the local disk
-     * @example
-     * ```ts
-     * const storage = new DiskStorage({
-     *   directory: 'upload',
-     *   metaStorageConfig: { directory: '/tmp/upload-metafiles', prefix: '.' }
-     * });
-     * ```
-     */
-    metaStorageConfig?: LocalMetaStorageOptions;
-};
-export type DiskStorageWithChecksumOptions<T extends File> = DiskStorageOptions<T> & {
-    /**
-     * Enable/disable file/range checksum calculation
-     */
-    checksum?: boolean | "md5" | "sha1";
-};
-/**
- * Unified storage configuration
- */
-export interface GenericStorageConfig {
-    /** Allow additional properties for specific storage backends */
-    [key: string]: unknown;
-    /** Base path/prefix for all operations */
-    basePath?: string;
-    /** Cache TTL */
-    cacheTTL?: number;
-    /** Supported checksum algorithms */
-    checksumTypes?: string[];
-    /** Logger instance */
-    logger?: Console;
-    /** Maximum file size */
-    maxFileSize?: number | string;
-    /** Metrics instance for observability */
-    metrics?: Metrics;
-    /** Retry configuration for transient failures */
-    retryConfig?: RetryConfig;
-}
-/**
- * Batch operation result for a single file
- */
-export interface BatchOperationResult<T extends File = File> {
-    /** Error message if operation failed */
-    error?: string;
-    /** File that was successfully operated on */
-    file?: T;
-    /** File ID */
-    id: string;
-    /** Whether the operation was successful */
-    success: boolean;
-}
-/**
- * Response from batch operations (deleteBatch, copyBatch, moveBatch)
- */
-export interface BatchOperationResponse<T extends File = File> {
-    /** Failed operations with error details */
-    failed: {
-        error: string;
-        id: string;
-    }[];
-    /** Total number of failed operations */
-    failedCount: number;
-    /** Successfully processed files */
-    successful: T[];
-    /** Total number of successful operations */
-    successfulCount: number;
-}
-/**
- * Generic storage operations that all backends should support
- */
-export interface GenericStorageOperations<T extends File = File, TReturn extends FileReturn = FileReturn> {
-    /** Copy a file */
-    copy: (source: string, destination: string, options?: {
-        storageClass?: string;
-    }) => Promise<T>;
-    /** Copy multiple files */
-    copyBatch?: (operations: {
-        destination: string;
-        options?: {
-            storageClass?: string;
-        };
-        source: string;
-    }[]) => Promise<BatchOperationResponse<T>>;
-    /** Create a new file upload */
-    create: (config: FileInit) => Promise<T>;
-    /** Delete a file */
-    delete: (query: FileQuery) => Promise<T>;
-    /** Delete multiple files */
-    deleteBatch?: (ids: string[]) => Promise<BatchOperationResponse<T>>;
-    /** Check if file exists */
-    exists: (query: FileQuery) => Promise<boolean>;
-    /** Get file data */
-    get: (query: FileQuery) => Promise<TReturn>;
-    /** Get file as a readable stream */
-    getStream?: (query: FileQuery) => Promise<{
-        headers?: Record<string, string>;
-        size?: number;
-        stream: Readable;
-    }>;
-    /** Get signed URL for upload (if supported) */
-    getUploadUrl?: (query: FileQuery, expiresIn?: number) => Promise<string>;
-    /** Get file URL (if supported) */
-    getUrl?: (query: FileQuery, expiresIn?: number) => Promise<string>;
-    /** List files */
-    list: (limit?: number) => Promise<T[]>;
-    /** Move a file */
-    move: (source: string, destination: string) => Promise<T>;
-    /** Move multiple files */
-    moveBatch?: (operations: {
-        destination: string;
-        source: string;
-    }[]) => Promise<BatchOperationResponse<T>>;
-    /** Update file metadata */
-    update: (query: FileQuery, metadata: Partial<T>) => Promise<T>;
-    /** Write data to a file */
-    write: (part: FilePart | FileQuery) => Promise<T>;
-}

package/dist/storage/utils/file/file.d.ts

@@ -1,25 +0,0 @@
-import type { Metadata } from "./metadata.d.ts";
-import type { FileInit, UploadEventType } from "./types.d.ts";
-type DateType = Date | number | string;
-declare class File implements FileInit {
-    bytesWritten: number;
-    contentType: string;
-    originalName: string;
-    id: string;
-    metadata: Metadata;
-    name: string;
-    size?: number;
-    status?: UploadEventType;
-    expiredAt?: DateType;
-    createdAt?: DateType;
-    modifiedAt?: DateType;
-    hash?: {
-        algorithm: string;
-        value: string;
-    };
-    content?: Buffer;
-    ETag?: string;
-    constructor({ contentType, expiredAt, metadata, originalName, size }: FileInit);
-}
-export type UploadFile = Readonly<File>;
-export default File;

package/dist/storage/utils/file/get-file-status.d.ts

@@ -1,9 +0,0 @@
-import type File from "./file.d.ts";
-import type { UploadEventType } from "./types.d.ts";
-/**
- * Determines the upload status of a file based on its current state.
- * @param file File object to check status for
- * @returns Upload event type: 'completed' if fully uploaded, 'part' if partially uploaded, 'created' if just started
- */
-declare const getFileStatus: (file: File) => UploadEventType;
-export default getFileStatus;

package/dist/storage/utils/file/has-content.d.ts

@@ -1,9 +0,0 @@
-import type { FilePart } from "./types.d.ts";
-/**
- * Type guard to check if a partial file part has valid content.
- * Validates that the part has a valid start position and body stream.
- * @param part Partial file part to check
- * @returns True if the part has valid content (start >= 0 and body exists)
- */
-declare const hasContent: (part: Partial<FilePart>) => part is FilePart;
-export default hasContent;

package/dist/storage/utils/file/index.d.ts

@@ -1,10 +0,0 @@
-export type { UploadFile } from "./file.d.ts";
-export { default as File } from "./file.d.ts";
-export { default as getFileStatus } from "./get-file-status.d.ts";
-export { default as hasContent } from "./has-content.d.ts";
-export { default as isExpired } from "./is-expired.d.ts";
-export { isMetadata, Metadata } from "./metadata.d.ts";
-export { default as partMatch } from "./part-match.d.ts";
-export type { Checksum, FileInit, FilePart, FileQuery, FileReturn, UploadEventType } from "./types.d.ts";
-export { default as updateMetadata } from "./update-metadata.d.ts";
-export { default as updateSize } from "./update-size.d.ts";

package/dist/storage/utils/file/is-expired.d.ts

@@ -1,8 +0,0 @@
-import type File from "./file.d.ts";
-/**
- * Checks if a file has expired based on its expiredAt timestamp.
- * @param file File object to check expiration for
- * @returns True if the file has expired, false otherwise
- */
-declare const isExpired: (file: File) => boolean;
-export default isExpired;

package/dist/storage/utils/file/metadata.d.ts

@@ -1,18 +0,0 @@
-export declare class Metadata {
-    [key: string]: unknown;
-    psize?: number | string;
-    pname?: string;
-    pfiletype?: string;
-    ptype?: string;
-    pmimeType?: string;
-    pcontentType?: string;
-    ptitle?: string;
-    pfilename?: string;
-    poriginalName?: string;
-    plastModified?: number | string;
-}
-export declare const isMetadata: (raw: unknown) => raw is Metadata;
-export declare const validateKey: (key: string) => boolean;
-export declare const validateValue: (value: string) => boolean;
-export declare const stringifyMetadata: (metadata: NonNullable<Metadata>) => string;
-export declare const parseMetadata: (string_?: string) => Metadata;

package/dist/storage/utils/file/part-match.d.ts

@@ -1,11 +0,0 @@
-import type File from "./file.d.ts";
-import type { FilePart } from "./types.d.ts";
-/**
- * Validates if a file part matches the expected file size and offset constraints.
- * Checks that the part doesn't exceed file size boundaries.
- * @param part Partial file part to validate
- * @param file File object to validate against
- * @returns True if the part is valid for the file, false otherwise
- */
-declare const partMatch: (part: Partial<FilePart>, file: File) => boolean;
-export default partMatch;

package/dist/storage/utils/file/types.d.ts

@@ -1,37 +0,0 @@
-import type { Readable } from "node:stream";
-import type { Metadata } from "./metadata.d.ts";
-export interface FileInit {
-    contentType?: string;
-    expiredAt?: Date | number | string;
-    metadata: Metadata;
-    originalName?: string;
-    size?: number | string;
-    storageClass?: string;
-    ttl?: number | string;
-}
-export interface FileReturn extends Omit<Required<FileInit>, "storageClass" | "ttl" | "expiredAt"> {
-    content: Buffer;
-    ETag?: string;
-    expiredAt?: Date | number | string;
-    id: string;
-    modifiedAt?: Date | number | string;
-    name: string;
-    storageClass?: string;
-}
-type UploadEventTypeValue = "completed" | "created" | "deleted" | "part" | "updated";
-export type UploadEventType = UploadEventTypeValue;
-export interface FileQuery {
-    id: string;
-    name?: string;
-    size?: number;
-}
-export interface Checksum {
-    checksum?: string;
-    checksumAlgorithm?: string;
-}
-export interface FilePart extends Checksum, FileQuery {
-    body: Readable;
-    contentLength?: number;
-    start: number;
-}
-export {};

package/dist/storage/utils/file/update-metadata.d.ts

@@ -1,10 +0,0 @@
-import type File from "./file.d.ts";
-/**
- * Updates a file object with new metadata using deep merge.
- * Also updates the originalName based on the merged metadata.
- * @param file File object to update
- * @param metadata Partial metadata to merge into the file
- * @template T - File type extending base File class
- */
-declare const updateMetadata: <T extends File>(file: T, metadata: Partial<T>) => void;
-export default updateMetadata;

package/dist/storage/utils/file/update-size.d.ts

@@ -1,10 +0,0 @@
-import type File from "./file.d.ts";
-/**
- * Updates a file's size, but only if the new size is smaller than the current size.
- * This prevents accidental size increases that could indicate data corruption.
- * @param file File object to update
- * @param size New size value
- * @returns The updated file object
- */
-declare const updateSize: (file: File, size: number) => File;
-export default updateSize;

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

@@ -1,32 +0,0 @@
-import type { LocalMetaStorageOptions } from "../local/local-meta-storage.d.ts";
-import type { BaseStorageOptions } from "../types.d.ts";
-import type VercelBlobFile from "./vercel-blob-file.d.ts";
-export interface VercelBlobStorageOptions extends BaseStorageOptions<VercelBlobFile> {
-    /**
-     * Configure metafiles storage
-     * @example
-     * Using local metafiles
-     * ```ts
-     * const storage = new VercelBlobStorage({
-     *   token: process.env.BLOB_READ_WRITE_TOKEN,
-     *   metaStorageConfig: { directory: '/tmp/upload-metafiles' }
-     * })
-     * ```
-     */
-    metaStorageConfig?: LocalMetaStorageOptions;
-    /**
-     * Enable multipart uploads for large files
-     * Can be a boolean to always use multipart, or a number (in bytes) as threshold
-     * @default false
-     * @example
-     * // Always use multipart uploads
-     * multipart: true
-     * // Use multipart for files larger than 100MB
-     * multipart: 100 * 1024 * 1024
-     */
-    multipart?: boolean | number;
-    /**
-     * Vercel Blob read-write token
-     */
-    token?: string;
-}

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

@@ -1,16 +0,0 @@
-import { File } from "../utils/index.d.ts";
-declare class VercelBlobFile extends File {
-    /**
-     * The blob's public URL
-     */
-    url?: string;
-    /**
-     * The blob's download URL (may be different from url for private blobs)
-     */
-    downloadUrl?: string;
-    /**
-     * The blob's pathname within the store
-     */
-    pathname?: string;
-}
-export default VercelBlobFile;

package/dist/storage/vercel-blob/vercel-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 VercelBlobFile from "./vercel-blob-file.d.ts";
-declare class VercelBlobMetaStorage extends LocalMetaStorage<VercelBlobFile> {
-    constructor(config?: LocalMetaStorageOptions);
-}
-export default VercelBlobMetaStorage;

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

@@ -1,76 +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 type { VercelBlobStorageOptions } from "./types.d.ts";
-import VercelBlobFile from "./vercel-blob-file.d.ts";
-/**
- * Vercel Blob storage based backend.
- * @example
- * ```ts
- * const storage = new VercelBlobStorage({
- *   token: process.env.BLOB_READ_WRITE_TOKEN,
- *   metaStorageConfig: { directory: '/tmp/upload-metafiles' }
- * });
- * ```
- * @remarks
- * ## Supported Operations
- * - ✅ create, write, delete, get, copy, move
- * - ✅ Batch operations: deleteBatch, copyBatch, moveBatch (inherited from BaseStorage)
- * - ✅ exists: Implemented (checks metadata and Vercel Blob)
- * - ❌ getStream: Not implemented (use get() for file retrieval)
- * - ❌ list: Not implemented (Vercel Blob API doesn't support listing)
- * - ❌ update: Not implemented (Vercel Blob API doesn't support metadata updates)
- * - ❌ getUrl: Not implemented (Vercel Blob URLs available via Vercel Blob API)
- * - ❌ getUploadUrl: Not implemented (Vercel Blob upload URLs handled internally)
- */
-declare class VercelBlobStorage extends BaseStorage<VercelBlobFile, FileReturn> {
-    static readonly name: string;
-    checksumTypes: string[];
-    protected meta: MetaStorage<VercelBlobFile>;
-    private readonly token;
-    private readonly multipart;
-    constructor(config: VercelBlobStorageOptions);
-    create(config: FileInit): Promise<VercelBlobFile>;
-    write(part: FilePart | FileQuery | VercelBlobFile): Promise<VercelBlobFile>;
-    /**
-     * 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<VercelBlobFile>;
-    /**
-     * Checks if a file exists by verifying both metadata and the actual Vercel 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<VercelBlobFile>;
-    /**
-     * 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<VercelBlobFile>;
-    list(limit?: number): Promise<VercelBlobFile[]>;
-    private internalOnComplete;
-    /**
-     * Determines if multipart upload should be used for the given file.
-     * @param file File object to check.
-     * @returns True if multipart upload should be used, false otherwise.
-     */
-    private shouldUseMultipart;
-}
-export default VercelBlobStorage;

package/dist/transformer/base-transformer.d.ts

@@ -1,63 +0,0 @@
-import { Readable } from "node:stream";
-import type { BaseStorage } from "../storage/storage.d.ts";
-import type { File, FileReturn } from "../storage/utils/index.d.ts";
-import type { Cache } from "../utils/cache.d.ts";
-import type { BaseTransformerConfig } from "./types.d.ts";
-/**
- * Abstract base class for all media transformers.
- *
- * Provides a common interface and shared functionality for image, video, and audio transformers.
- * All transformers must implement the abstract methods defined here.
- */
-declare abstract class BaseTransformer<Config extends BaseTransformerConfig, CacheValue extends object, TFile extends File = File, TFileReturn extends FileReturn = FileReturn> {
-    protected readonly storage: BaseStorage<TFile, TFileReturn>;
-    protected config: Config;
-    protected logger?: Console;
-    protected cache?: Cache<string, CacheValue>;
-    /**
-     * Creates a new BaseTransformer instance with common functionality.
-     * @param storage The storage backend for retrieving and storing files.
-     * @param config Configuration options for the transformer.
-     * @param logger Optional logger instance for logging operations.
-     * @protected
-     */
-    protected constructor(storage: BaseStorage<TFile, TFileReturn>, config: Config, logger?: Console);
-    /**
-     * Transforms a file with the given steps.
-     * @param fileId Unique identifier of the file to transform.
-     * @param steps Array of transformation steps to apply.
-     * @returns Promise resolving to transformation result.
-     */
-    abstract transform(fileId: string, steps: any[]): Promise<any>;
-    /**
-     * Streams transform of a file with the given steps (for large files).
-     * @param fileId Unique identifier of the file to transform.
-     * @param steps Array of transformation steps to apply.
-     * @returns Promise resolving to streaming result with headers, size, and stream.
-     */
-    transformStream?(fileId: string, steps: any[]): Promise<{
-        headers?: Record<string, string>;
-        size?: number;
-        stream: Readable;
-    }>;
-    /**
-     * Clears cache for a specific file or all files.
-     * @param fileId Optional file identifier to clear cache for specific file.
-     */
-    clearCache(fileId?: string): void;
-    /**
-     * Gets cache statistics.
-     * @returns Cache statistics including max size and current size.
-     */
-    getCacheStats(): {
-        maxSize: number;
-        size: number;
-    };
-    /**
-     * Gets content type from transformation result based on format.
-     * @param result Transformation result object containing format information.
-     * @returns Content type string (MIME type).
-     */
-    protected getContentTypeFromResult(result: any): string;
-}
-export default BaseTransformer;