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

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

@@ -0,0 +1,135 @@
+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, FileReturn> {
+    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/index.d.ts

@@ -0,0 +1,4 @@
+export { default as DiskStorage } from "./disk-storage.d.ts";
+export { default as DiskStorageWithChecksum } from "./disk-storage-with-checksum.d.ts";
+export type { LocalMetaStorageOptions } from "./local-meta-storage.d.ts";
+export { default as LocalMetaStorage } from "./local-meta-storage.d.ts";

package/dist/storage/local/index.js

@@ -0,0 +1,3 @@
+export { D as DiskStorage } from '../../packem_shared/disk-storage-Bh2wy3YW.js';
+export { default as DiskStorageWithChecksum } from '../../packem_shared/DiskStorageWithChecksum-BJTmMklc.js';
+export { L as LocalMetaStorage } from '../../packem_shared/local-meta-storage-By-3SNBI.js';

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

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

@@ -0,0 +1,30 @@
+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/index.d.ts

@@ -0,0 +1,4 @@
+export { default as NetlifyBlobFile } from "./netlify-blob-file.d.ts";
+export { default as NetlifyBlobMetaStorage } from "./netlify-blob-meta-storage.d.ts";
+export { default as NetlifyBlobStorage } from "./netlify-blob-storage.d.ts";
+export type { NetlifyBlobStorageOptions } from "./types.d.ts";

package/dist/storage/netlify-blob/index.js

@@ -0,0 +1,3 @@
+export { default as NetlifyBlobFile } from '../../packem_shared/NetlifyBlobFile-CXzyjqrD.js';
+export { default as NetlifyBlobMetaStorage } from '../../packem_shared/NetlifyBlobMetaStorage-DxZ5aDvD.js';
+export { default as NetlifyBlobStorage } from '../../packem_shared/NetlifyBlobStorage-CLPtjHqd.js';

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

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

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

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

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