@visulima/storage 1.0.0-alpha.14 → 1.0.0-alpha.16

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

@@ -1,91 +0,0 @@
-import type { HttpError } from "../../utils/types.d.ts";
-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 GCSFile from "./gcs-file.d.ts";
-import type { ClientError, GCStorageOptions } from "./types.d.ts";
-/**
- * Google cloud storage based backend.
- * @example
- * ```ts
- *  const storage = new GCStorage({
- *    bucket: <YOUR_BUCKET>,
- *    keyFile: <PATH_TO_KEY_FILE>,
- *    metaStorage: new MetaStorage(),
- *    clientDirectUpload: true,
- *    maxUploadSize: '15GB',
- *    allowMIME: ['video/*', 'image/*'],
- *    filename: file => file.originalName
- *  });
- * ```
- * @remarks
- * ## Supported Operations
- * - ✅ create, write, delete, get, list, update, copy, move
- * - ✅ Batch operations: deleteBatch, copyBatch, moveBatch (inherited from BaseStorage)
- * - ✅ exists: Implemented (checks metadata and GCS object)
- * - ❌ getStream: Not implemented (use get() for file retrieval)
- * - ❌ getUrl: Not implemented (GCS public URLs not supported)
- * - ❌ getUploadUrl: Not implemented (resumable upload URLs handled internally)
- */
-declare class GCStorage extends BaseStorage {
-    static readonly name: string;
-    checksumTypes: string[];
-    protected meta: MetaStorage;
-    private readonly bucket;
-    private authClient;
-    private readonly storageBaseURI;
-    private readonly uploadBaseURI;
-    private readonly isCustomEndpoint;
-    private readonly retryOptions;
-    private readonly useAuthWithCustomEndpoint;
-    private readonly userProject;
-    constructor(config: GCStorageOptions);
-    normalizeError(error: ClientError): HttpError;
-    create(config: FileInit): Promise<GCSFile>;
-    write(part: FilePart | FileQuery | GCSFile): Promise<GCSFile>;
-    /**
-     * 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<GCSFile>;
-    /**
-     * 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<GCSFile>;
-    /**
-     * 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<GCSFile>;
-    /**
-     * Gets an uploaded file by ID with content buffer.
-     * @param query File query object containing the file ID.
-     * @param query.id Unique identifier of the file to retrieve.
-     * @returns Promise resolving to file object with content buffer.
-     * @throws {UploadError} If the file cannot be found (ERRORS.FILE_NOT_FOUND) or has expired (ERRORS.GONE).
-     */
-    get({ id }: FileQuery): Promise<FileReturn>;
-    /**
-     * Checks if a file exists by verifying both metadata and the actual GCS object.
-     * Returns true only if both the metadata and the GCS object exist.
-     * @param query File query containing the file ID to check.
-     * @returns Promise resolving to true if both metadata and GCS object exist, false otherwise.
-     */
-    exists({ id }: FileQuery): Promise<boolean>;
-    list(limit?: number): Promise<GCSFile[]>;
-    protected internalWrite(part: GCSFile & Partial<FilePart>): Promise<number>;
-    private internalOnComplete;
-    private makeRequest;
-    private accessCheck;
-}
-export default GCStorage;

package/dist/storage/gcs/types.d.ts

@@ -1,54 +0,0 @@
-import type { RetryConfig } from "gaxios";
-import type { GoogleAuth, GoogleAuthOptions } from "google-auth-library";
-import type { LocalMetaStorageOptions } from "../local/local-meta-storage.d.ts";
-import type { BaseStorageOptions, MetaStorageOptions } from "../types.d.ts";
-interface StorageSettings {
-    projectId: string;
-    retryOptions?: RetryConfig;
-    storageAPI?: string;
-    uploadAPI?: string;
-    useAuthWithCustomEndpoint?: boolean;
-    userProject?: string;
-}
-export interface ClientError extends Error {
-    code: string;
-    config: Record<string, unknown>;
-    response?: Record<string, unknown>;
-}
-export interface GCStorageOptions extends BaseStorageOptions, Omit<GoogleAuthOptions, "authClient" | "projectId">, StorageSettings {
-    /**
-     * Google Cloud Storage bucket
-     */
-    bucket?: string;
-    /**
-     * Force compatible client upload directly to GCS
-     */
-    clientDirectUpload?: boolean;
-    /**
-     * Configure metafiles storage
-     * @example
-     * ```ts
-     * Using local metafiles
-     * const storage = new GCStorage({
-     *   bucket: 'upload',
-     *   metaStorageConfig: { directory: '/tmp/upload-metafiles' }
-     * })
-     * ```
-     * Using a separate bucket for metafiles
-     * ```ts
-     * const storage = new GCStorage({
-     *   bucket: 'upload',
-     *   metaStorageConfig: { bucket: 'upload-metafiles' }
-     * })
-     * ```
-     */
-    metaStorageConfig?: GCSMetaStorageOptions | LocalMetaStorageOptions;
-}
-export interface GCSMetaStorageOptions extends MetaStorageOptions, Omit<GoogleAuthOptions, "authClient" | "projectId">, StorageSettings {
-    /**
-     * @internal
-     */
-    authClient?: GoogleAuth;
-    bucket?: string;
-}
-export {};

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

@@ -1,7 +0,0 @@
-import type { GaxiosError, RetryConfig } from "gaxios";
-import type { FilePart } from "../utils/index.d.ts";
-import type GCSFile from "./gcs-file.d.ts";
-export declare const getRangeEnd: (range: string) => number;
-export declare const buildContentRange: (part: GCSFile & Partial<FilePart>) => string;
-export declare const shouldRetry: (error: GaxiosError) => boolean;
-export declare const retryOptions: RetryConfig;

package/dist/storage/local/disk-storage-with-checksum.d.ts

@@ -1,15 +0,0 @@
-import { ERRORS } from "../../utils/errors.d.ts";
-import type { DiskStorageWithChecksumOptions } from "../types.d.ts";
-import type { File, FilePart, FileQuery } from "../utils/index.d.ts";
-import DiskStorage from "./disk-storage.d.ts";
-/**
- * Additionally calculates checksum of the file/range.
- */
-declare class DiskStorageWithChecksum<TFile extends File = File> extends DiskStorage<TFile> {
-    private hashes;
-    constructor(config: DiskStorageWithChecksumOptions<TFile>);
-    delete({ id }: FileQuery): Promise<TFile>;
-    write(part: FilePart | FileQuery): Promise<TFile>;
-    protected lazyWrite(part: File & FilePart): Promise<[number, ERRORS?]>;
-}
-export default DiskStorageWithChecksum;

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

@@ -1,135 +0,0 @@
-import type { Readable } from "node:stream";
-import { ERRORS } from "../../utils/errors.d.ts";
-import type { HttpError } from "../../utils/types.d.ts";
-import type MetaStorage from "../meta-storage.d.ts";
-import { BaseStorage } from "../storage.d.ts";
-import type { DiskStorageOptions } from "../types.d.ts";
-import type { FileInit, FilePart, FileQuery } from "../utils/index.d.ts";
-import { File } from "../utils/index.d.ts";
-import type { FileReturn } from "../utils/file/types.d.ts";
-/**
- * Local disk-based storage implementation.
- * @template TFile The file type used by this storage backend.
- * @remarks
- * ## Error Handling
- * - Filesystem operations throw errors directly (no retry logic)
- * - File not found errors are thrown immediately
- * - Permission errors are propagated as-is
- *
- * ## Retry Behavior
- * - No automatic retries (filesystem operations are typically immediate)
- * - Errors are thrown directly for immediate feedback
- *
- * ## File Paths
- * - Files are stored in the configured directory
- * - Metadata files use the `.META` suffix by default
- * - File paths are resolved relative to the storage directory
- */
-declare class DiskStorage<TFile extends File = File> extends BaseStorage<TFile> {
-    static readonly name: string;
-    checksumTypes: string[];
-    directory: string;
-    meta: MetaStorage<TFile>;
-    constructor(config: DiskStorageOptions<TFile>);
-    /**
-     * Normalizes errors with disk storage context.
-     * @param error The error to normalize.
-     * @returns Normalized HTTP error.
-     */
-    normalizeError(error: Error): HttpError;
-    /**
-     * Creates a new file upload and saves its metadata.
-     * @param fileInit File initialization configuration.
-     * @returns Promise resolving to the created file object.
-     * @throws {Error} If validation fails or file already exists and is completed.
-     * @remarks
-     * Supports TTL (time-to-live) option in fileInit.
-     * Creates the file on disk if it doesn't exist.
-     * Returns existing file if it's already completed.
-     */
-    create(fileInit: FileInit): Promise<TFile>;
-    /**
-     * Writes data to a file upload.
-     * @param part File part containing data to write, file query, or full file object.
-     * @returns Promise resolving to the updated file object.
-     * @throws {Error} If file is expired (ERRORS.GONE), locked (ERRORS.FILE_LOCKED), or conflicts occur (ERRORS.FILE_CONFLICT).
-     * @remarks
-     * Supports chunked uploads with start position.
-     * Automatically detects file type from stream on first chunk if contentType is not set.
-     * Validates checksum algorithms if provided.
-     * Uses file locking to prevent concurrent writes.
-     * Updates file status to "completed" when all bytes are written.
-     */
-    write(part: FilePart | FileQuery | TFile): Promise<TFile>;
-    /**
-     * 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 buffer.
-     * @throws {Error} If the file cannot be found (ERRORS.FILE_NOT_FOUND) or has expired (ERRORS.GONE).
-     * @remarks
-     * Loads the entire file content into memory as a Buffer.
-     * For large files, consider using getStream() instead.
-     * Includes ETag (MD5 hash) for content verification.
-     */
-    get({ id }: FileQuery): Promise<FileReturn>;
-    /**
-     * Checks if a file exists by verifying both metadata and the actual filesystem file.
-     * Returns true only if both the metadata and the file exist.
-     * @param query File query containing the file ID to check.
-     * @returns Promise resolving to true if both metadata and file exist, false otherwise.
-     */
-    exists({ id }: FileQuery): Promise<boolean>;
-    /**
-     * 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 Creates a readable stream directly from the file system for efficient memory usage.
-     */
-    getStream({ id }: FileQuery): Promise<{
-        headers?: Record<string, string>;
-        size?: number;
-        stream: Readable;
-    }>;
-    /**
-     * 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<TFile>;
-    /**
-     * 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<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 {Error} If the source file cannot be found.
-     */
-    move(name: string, destination: string): Promise<TFile>;
-    /**
-     * Retrieves a list of uploaded files.
-     * @returns Promise resolving to an array of file metadata objects.
-     * @remarks Walks the storage directory and returns all files, excluding metadata files.
-     */
-    list(): Promise<TFile[]>;
-    /**
-     * Returns path for the uploaded file
-     * If filename is already an absolute path, returns it as-is.
-     * Otherwise, joins it with the storage directory.
-     */
-    protected getFilePath(filename: string): string;
-    protected lazyWrite(part: File & FilePart): Promise<[number, ERRORS?]>;
-    private accessCheck;
-}
-export default DiskStorage;

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

@@ -1,27 +0,0 @@
-import MetaStorage from "../meta-storage.d.ts";
-import type { LocalMetaStorageOptions } from "../meta-storage-options.d.ts";
-import type { File } from "../utils/index.d.ts";
-export type { LocalMetaStorageOptions } from "../meta-storage-options.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 default LocalMetaStorage;

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

@@ -1,11 +0,0 @@
-export interface MetaStorageOptions {
-    logger?: Console;
-    prefix?: string;
-    suffix?: string;
-}
-export interface LocalMetaStorageOptions extends MetaStorageOptions {
-    /**
-     * Where the upload metadata should be stored
-     */
-    directory?: string;
-}

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

@@ -1,30 +0,0 @@
-import type { MetaStorageOptions } from "./meta-storage-options.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,6 +0,0 @@
-import type { LocalMetaStorageOptions } from "../local/local-meta-storage.d.ts";
-import LocalMetaStorage from "../local/local-meta-storage.d.ts";
-declare class NetlifyBlobMetaStorage extends LocalMetaStorage {
-    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 {
-    static readonly name: string;
-    checksumTypes: string[];
-    protected meta: MetaStorage;
-    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,29 +0,0 @@
-import type { LocalMetaStorageOptions } from "../local/local-meta-storage.d.ts";
-import type { BaseStorageOptions } from "../types.d.ts";
-export interface NetlifyBlobStorageOptions extends BaseStorageOptions {
-    /**
-     * 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;
-}