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

package/dist/storage/storage.d.ts

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

package/dist/storage/types.d.ts

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

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

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

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

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

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

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

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