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

package/dist/storage/aws/s3-storage.d.ts

@@ -1,70 +0,0 @@
-import { Readable } from "node:stream";
-import type { HttpError } from "../../utils/types.d.ts";
-import type { FileInit, FileQuery } from "../utils/index.d.ts";
-import { S3BaseStorage } from "./s3-base-storage.d.ts";
-import S3ClientAdapter from "./s3-client-adapter.d.ts";
-import S3File from "./s3-file.d.ts";
-import type { AwsError, S3StorageOptions } from "./types.d.ts";
-/**
- * Amazon S3 storage implementation.
- * @example
- * ```ts
- * const storage = new S3Storage({
- *  bucket: <YOUR_BUCKET>,
- *  endpoint: <YOUR_ENDPOINT>,
- *  region: <YOUR_REGION>,
- *  credentials: {
- *    accessKeyId: <YOUR_ACCESS_KEY_ID>,
- *    secretAccessKey: <YOUR_SECRET_ACCESS_KEY>
- *  },
- *  metaStorageConfig: { directory: '/tmp/upload-metafiles' }
- * });
- * ```
- * @remarks
- * ## Error Handling
- * - S3 API errors are normalized with AWS-specific context
- * - Errors include S3 error codes and metadata for debugging
- * - Batch operations handle individual failures gracefully
- *
- * ## Retry Behavior
- * - All S3 API calls are wrapped with configurable retry logic via `retryConfig` option
- * - Default retryable status codes: 408 (Request Timeout), 429 (Too Many Requests),
- * 500 (Internal Server Error), 502 (Bad Gateway), 503 (Service Unavailable), 504 (Gateway Timeout)
- * - Retries server-side faults ($fault === "server") automatically
- * - Custom `shouldRetry` function can be provided for advanced retry logic
- * - Default retry configuration: maxRetries: 3, initialDelay: 1000ms, maxDelay: 30000ms, backoffMultiplier: 2 (exponential backoff)
- * - Retry wrapper handles transient network errors and rate limiting
- *
- * ## Multipart Uploads
- * - Large files are automatically split into multipart uploads
- * - Maximum 10,000 parts per upload (S3 limitation)
- * - Part size is configurable (default: 16MB, minimum: 5MB)
- * - Failed multipart uploads are automatically aborted
- *
- * ## Supported Operations
- * - ✅ create, write, delete, get, getStream, list, update, copy, move
- * - ✅ Batch operations: deleteBatch, copyBatch, moveBatch (inherited from BaseStorage)
- * - ✅ exists: Implemented (checks metadata and S3 object)
- * - ❌ getUrl: Not implemented (presigned URLs available via buildPresigned for clientDirectUpload)
- * - ❌ getUploadUrl: Not implemented (presigned URLs available via buildPresigned for clientDirectUpload)
- */
-declare class S3Storage extends S3BaseStorage {
-    static readonly name: string;
-    private s3Api;
-    constructor(config: S3StorageOptions);
-    /**
-     * Normalizes AWS S3 errors with S3-specific context.
-     */
-    normalizeError(error: AwsError): HttpError;
-    update({ id }: FileQuery, metadata: Partial<S3File>): Promise<S3File>;
-    getStream({ id }: FileQuery): Promise<{
-        headers?: Record<string, string>;
-        size?: number;
-        stream: Readable;
-    }>;
-    protected getS3Api(): S3ClientAdapter;
-    protected getFileClass(): new (config: FileInit) => S3File;
-    protected getAcl(): string | undefined;
-    protected accessCheck(_maxWaitTime?: number): Promise<void>;
-}
-export default S3Storage;

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

@@ -1,118 +0,0 @@
-import type { ObjectCannedACL, S3Client, S3ClientConfig } from "@aws-sdk/client-s3";
-import type { ResponseMetadata } from "@aws-sdk/types";
-import type { LocalMetaStorageOptions } from "../local/local-meta-storage.d.ts";
-import type { BaseStorageOptions, MetaStorageOptions } from "../types.d.ts";
-export type S3MetaStorageOptions = MetaStorageOptions & S3ClientConfig & {
-    bucket?: string;
-    /**
-     * @internal
-     */
-    client?: S3Client;
-    keyFile?: string;
-};
-export type S3StorageOptions = BaseStorageOptions & S3ClientConfig & {
-    /**
-     * Specifying access rules for uploaded files.
-     */
-    acl?: ObjectCannedACL;
-    /**
-     * S3 bucket name.
-     * @default 'node-Upload'
-     */
-    bucket?: string;
-    /**
-     * Force compatible client upload directly to S3 storage
-     */
-    clientDirectUpload?: boolean;
-    /**
-     * @deprecated Use standard auth providers
-     */
-    keyFile?: string;
-    /**
-     * Configure metafiles storage
-     * @example
-     * Using local metafiles
-     * ```ts
-     * const storage = new S3Storage({
-     *   bucket: 'upload',
-     *   region: 'eu-west-3',
-     *   metaStorageConfig: { directory: '/tmp/upload-metafiles' }
-     * })
-     * ```
-     * Using a separate bucket for metafiles
-     * ```ts
-     * const storage = new S3Storage({
-     *   bucket: 'upload',
-     *   region: 'eu-west-3',
-     *   metaStorageConfig: { bucket: 'upload-metafiles' }
-     * })
-     * ```
-     */
-    metaStorageConfig?: LocalMetaStorageOptions | S3MetaStorageOptions;
-    /**
-     * The parts size that the client should use for presigned multipart unloading.
-     * @default '16MB'
-     */
-    partSize?: number | string;
-};
-/**
- * SDK V3
- * A structure containing information about a service or networking error.
- */
-export interface AwsError extends Error {
-    $fault?: "client" | "server";
-    $metadata: ResponseMetadata;
-    $service?: string;
-    Code?: string;
-    Type?: string;
-}
-/**
- * SDK V2
- * A structure containing information about a service or networking error.
- */
-export interface AWSErrorV2 extends Error {
-    /**
-     * CloudFront request ID associated with the response.
-     */
-    cfId: string;
-    /**
-     * A unique short code representing the error that was emitted.
-     */
-    code: string;
-    /**
-     * Second request ID associated with the response from S3.
-     */
-    extendedRequestId: string;
-    /**
-     * Set when a networking error occurs to easily identify the endpoint of the request.
-     */
-    hostname: string;
-    /**
-     * A longer human readable error message.
-     */
-    message: string;
-    /**
-     * Set when a networking error occurs to easily identify the region of the request.
-     */
-    region: string;
-    /**
-     * The unique request ID associated with the response.
-     */
-    requestId: string;
-    /**
-     * Whether the error message is retryable.
-     */
-    retryable: boolean;
-    /**
-     * Amount of time (in seconds) that the request waited before being resent.
-     */
-    retryDelay: number;
-    /**
-     * In the case of a request that reached the service, this value contains the response status code.
-     */
-    statusCode: number;
-    /**
-     * The date time object when the error occurred.
-     */
-    time: Date;
-}

package/dist/storage/aws-light/aws-light-api-adapter.d.ts

@@ -1,130 +0,0 @@
-import { Readable } from "node:stream";
-import type { Part, S3ApiOperations } from "../aws/s3-base-storage.d.ts";
-import type { AwsLightClientConfig } from "./types.d.ts";
-/**
- * Adapter that uses aws4fetch to implement S3ApiOperations interface.
- */
-declare class AwsLightApiAdapter implements S3ApiOperations {
-    private aws;
-    private readonly bucket;
-    private readonly endpoint;
-    constructor(config: AwsLightClientConfig & {
-        bucket: string;
-    });
-    createMultipartUpload(params: {
-        ACL?: string;
-        Bucket: string;
-        ContentType?: string;
-        Key: string;
-        Metadata?: Record<string, string>;
-    }): Promise<{
-        UploadId: string;
-    }>;
-    uploadPart(params: {
-        Body: Readable | ReadableStream | Uint8Array;
-        Bucket: string;
-        ContentLength?: number;
-        ContentMD5?: string;
-        Key: string;
-        PartNumber: number;
-        UploadId: string;
-    }): Promise<{
-        ETag: string;
-    }>;
-    completeMultipartUpload(params: {
-        Bucket: string;
-        Key: string;
-        Parts: {
-            ETag: string;
-            PartNumber: number;
-        }[];
-        UploadId: string;
-    }): Promise<{
-        ETag?: string;
-        Location: string;
-    }>;
-    abortMultipartUpload(params: {
-        Bucket: string;
-        Key: string;
-        UploadId: string;
-    }): Promise<void>;
-    listParts(params: {
-        Bucket: string;
-        Key: string;
-        UploadId: string;
-    }): Promise<{
-        Parts?: Part[];
-    }>;
-    getObject(params: {
-        Bucket: string;
-        Key: string;
-    }): Promise<{
-        Body?: ReadableStream | Readable;
-        ContentLength?: number;
-        ContentType?: string;
-        ETag?: string;
-        Expires?: Date;
-        LastModified?: Date;
-        Metadata?: Record<string, string>;
-    }>;
-    headObject(params: {
-        Bucket: string;
-        Key: string;
-    }): Promise<{
-        ContentLength?: number;
-        ContentType?: string;
-        ETag?: string;
-        Expires?: Date;
-        LastModified?: Date;
-        Metadata?: Record<string, string>;
-    }>;
-    deleteObject(params: {
-        Bucket: string;
-        Key: string;
-    }): Promise<void>;
-    copyObject(params: {
-        Bucket: string;
-        CopySource: string;
-        Key: string;
-        StorageClass?: string;
-    }): Promise<void>;
-    listObjectsV2(params: {
-        Bucket: string;
-        ContinuationToken?: string;
-        MaxKeys?: number;
-    }): Promise<{
-        Contents?: {
-            Key?: string;
-            LastModified?: Date;
-        }[];
-        IsTruncated?: boolean;
-        NextContinuationToken?: string;
-    }>;
-    getPresignedUrl(params: {
-        Bucket: string;
-        expiresIn: number;
-        Key: string;
-        PartNumber: number;
-        UploadId: string;
-    }): Promise<string>;
-    putObject(params: {
-        Body?: Uint8Array | ReadableStream;
-        Bucket: string;
-        ContentLength?: number;
-        ContentType?: string;
-        Key: string;
-        Metadata?: Record<string, string>;
-    }): Promise<void>;
-    checkBucketAccess(_params: {
-        Bucket: string;
-    }): Promise<void>;
-    /**
-     * Builds S3 API URL.
-     */
-    private buildUrl;
-    /**
-     * Converts ReadableStream to Readable for Node.js compatibility.
-     */
-    private streamToReadable;
-}
-export default AwsLightApiAdapter;

package/dist/storage/aws-light/aws-light-file.d.ts

@@ -1,10 +0,0 @@
-import type { Part } from "../aws/s3-base-storage.d.ts";
-import { File } from "../utils/index.d.ts";
-declare class AwsLightFile extends File {
-    Parts?: Part[];
-    UploadId?: string;
-    uri?: string;
-    partsUrls?: string[];
-    partSize?: number;
-}
-export default AwsLightFile;

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

@@ -1,19 +0,0 @@
-import MetaStorage from "../meta-storage.d.ts";
-import type { File } from "../utils/index.d.ts";
-import type { AwsLightMetaStorageOptions } from "./types.d.ts";
-/**
- * AWS Light meta storage implementation using aws4fetch.
- * Stores metadata in S3 object metadata headers (x-amz-meta-*).
- * Optimized for worker environments (Cloudflare Workers, Web Workers, etc.).
- */
-declare class AwsLightMetaStorage<T extends File = File> extends MetaStorage<T> {
-    config: AwsLightMetaStorageOptions;
-    private readonly adapter;
-    private readonly bucket;
-    constructor(config: AwsLightMetaStorageOptions);
-    get(id: string): Promise<T>;
-    touch(id: string, file: T): Promise<T>;
-    delete(id: string): Promise<void>;
-    save(id: string, file: T): Promise<T>;
-}
-export default AwsLightMetaStorage;

package/dist/storage/aws-light/aws-light-storage.d.ts

@@ -1,66 +0,0 @@
-import { Readable } from "node:stream";
-import type { HttpError } from "../../utils/types.d.ts";
-import { S3BaseStorage } from "../aws/s3-base-storage.d.ts";
-import type { FileInit, FileQuery } from "../utils/index.d.ts";
-import AwsLightApiAdapter from "./aws-light-api-adapter.d.ts";
-import AwsLightFile from "./aws-light-file.d.ts";
-import type { AwsLightError, AwsLightStorageOptions } from "./types.d.ts";
-/**
- * AWS Light storage implementation using aws4fetch.
- * Optimized for worker environments (Cloudflare Workers, Web Workers, etc.).
- * @example
- * ```ts
- * const storage = new AwsLightStorage({
- *  bucket: <YOUR_BUCKET>,
- *  region: <YOUR_REGION>,
- *  accessKeyId: <YOUR_ACCESS_KEY_ID>,
- *  secretAccessKey: <YOUR_SECRET_ACCESS_KEY>
- * });
- * ```
- * @remarks
- * ## Worker Compatibility
- * - Uses aws4fetch for AWS request signing (works in workers)
- * - No Node.js-specific dependencies
- * - Compatible with Cloudflare Workers, Web Workers, and edge runtimes
- *
- * ## Error Handling
- * - S3 API errors are normalized with AWS-specific context
- * - Errors include S3 error codes and status codes for debugging
- *
- * ## Retry Behavior
- * - All S3 API calls are wrapped with configurable retry logic via `retryConfig` option
- * - Default retryable status codes: 408, 429, 500, 502, 503, 504
- * - Custom `shouldRetry` function can be provided for advanced retry logic
- *
- * ## Multipart Uploads
- * - Large files are automatically split into multipart uploads
- * - Maximum 10,000 parts per upload (S3 limitation)
- * - Part size is configurable (default: 16MB, minimum: 5MB)
- * - Failed multipart uploads are automatically aborted
- *
- * ## Supported Operations
- * - ✅ create, write, delete, get, getStream, list, update, copy, move
- * - ✅ Batch operations: deleteBatch, copyBatch, moveBatch (inherited from BaseStorage)
- * - ✅ exists: Implemented (checks metadata and S3 object)
- * - ⚠️ getUrl/getUploadUrl: Limited presigned URL support (uses aws4fetch signing)
- */
-declare class AwsLightStorage extends S3BaseStorage {
-    static readonly name: string;
-    private s3Api;
-    constructor(config: AwsLightStorageOptions);
-    /**
-     * Normalizes AWS S3 errors with S3-specific context.
-     */
-    normalizeError(error: AwsLightError | Error): HttpError;
-    update({ id }: FileQuery, metadata: Partial<AwsLightFile>): Promise<AwsLightFile>;
-    getStream({ id }: FileQuery): Promise<{
-        headers?: Record<string, string>;
-        size?: number;
-        stream: Readable;
-    }>;
-    protected getS3Api(): AwsLightApiAdapter;
-    protected getFileClass(): new (config: FileInit) => AwsLightFile;
-    protected getAcl(): string | undefined;
-    protected accessCheck(_maxWaitTime?: number): Promise<void>;
-}
-export default AwsLightStorage;

package/dist/storage/aws-light/types.d.ts

@@ -1,36 +0,0 @@
-import type { BaseStorageOptions, MetaStorageOptions } from "../types.d.ts";
-export interface AwsLightClientConfig {
-    accessKeyId: string;
-    endpoint?: string;
-    region: string;
-    secretAccessKey: string;
-    service?: string;
-    sessionToken?: string;
-}
-export type AwsLightMetaStorageOptions = AwsLightClientConfig & MetaStorageOptions & {
-    bucket?: string;
-};
-export type AwsLightStorageOptions = AwsLightClientConfig & BaseStorageOptions & {
-    /**
-     * S3 bucket name.
-     */
-    bucket?: string;
-    /**
-     * Force compatible client upload directly to S3 storage
-     */
-    clientDirectUpload?: boolean;
-    /**
-     * Configure metafiles storage
-     */
-    metaStorageConfig?: AwsLightMetaStorageOptions;
-    /**
-     * The parts size that the client should use for presigned multipart unloading.
-     * @default '16MB'
-     */
-    partSize?: number | string;
-};
-export interface AwsLightError extends Error {
-    code?: string;
-    requestId?: string;
-    statusCode?: number;
-}

package/dist/storage/azure/azure-file.d.ts

@@ -1,6 +0,0 @@
-import { File } from "../utils/index.d.ts";
-declare class AzureFile extends File {
-    requestId?: string;
-    uri?: string;
-}
-export default AzureFile;

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

@@ -1,15 +0,0 @@
-import MetaStorage from "../meta-storage.d.ts";
-import type { File } from "../utils/index.d.ts";
-import type { AzureMetaStorageOptions } from "./types.d.ts";
-declare class AzureMetaStorage<T extends File = File> extends MetaStorage<T> {
-    config: AzureMetaStorageOptions;
-    private client;
-    private containerClient;
-    constructor(config: AzureMetaStorageOptions);
-    get(id: string): Promise<T>;
-    touch(id: string, file: T): Promise<T>;
-    delete(id: string): Promise<void>;
-    save(id: string, file: T): Promise<T>;
-    list(): Promise<T[]>;
-}
-export default AzureMetaStorage;

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

@@ -1,69 +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 AzureFile from "./azure-file.d.ts";
-import type { AzureStorageOptions } from "./types.d.ts";
-/**
- * Azure Blob Storage implementation.
- * @remarks
- * ## Supported Operations
- * - ✅ create, write, delete, get, list, update, copy, move
- * - ✅ Batch operations: deleteBatch, copyBatch, moveBatch (inherited from BaseStorage)
- * - ✅ exists: Implemented (checks metadata and Azure blob)
- * - ❌ getStream: Not implemented (use get() for file retrieval)
- * - ❌ getUrl: Not implemented (Azure Blob URLs not supported)
- * - ❌ getUploadUrl: Not implemented (Azure Blob upload URLs handled internally)
- */
-declare class AzureStorage extends BaseStorage {
-    static readonly name: string;
-    checksumTypes: string[];
-    protected meta: MetaStorage;
-    private client;
-    private readonly containerClient;
-    private readonly root;
-    private readonly retry;
-    constructor(config: AzureStorageOptions);
-    create(config: FileInit): Promise<AzureFile>;
-    /**
-     * 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<AzureFile>;
-    /**
-     * 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<AzureFile>;
-    write(part: FilePart | FileQuery | AzureFile): Promise<AzureFile>;
-    get({ id }: FileQuery): Promise<FileReturn>;
-    /**
-     * Checks if a file exists by verifying both metadata and the actual Azure 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>;
-    /**
-     * 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<AzureFile>;
-    list(limit?: number): Promise<AzureFile[]>;
-    /**
-     * Prefixes the given filePath with the storage root location (assetFolder if configured).
-     * @param filePath Relative file path to prefix.
-     * @returns Full path with asset folder prefix if configured, otherwise returns original path.
-     */
-    private getFullPath;
-    private accessCheck;
-}
-export default AzureStorage;

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

@@ -1,61 +0,0 @@
-import type { BlobServiceClient } from "@azure/storage-blob";
-import type { LocalMetaStorageOptions } from "../local/local-meta-storage.d.ts";
-import type { BaseStorageOptions, MetaStorageOptions } from "../types.d.ts";
-interface ClientConfig {
-    /**
-     * Azure account key.
-     */
-    accountKey?: string;
-    /**
-     * Azure account name.
-     */
-    accountName?: string;
-    /**
-     * Azure container name.
-     */
-    containerName: string;
-    /**
-     * Azure endpoint.
-     */
-    endpoint?: string;
-    /**
-     * Azure root path.
-     */
-    root?: string;
-}
-interface ClientConfig {
-    connectionString?: string;
-    /**
-     * Azure container name.
-     */
-    containerName: string;
-    /**
-     * Azure root path.
-     */
-    root?: string;
-}
-export interface AzureMetaStorageOptions extends ClientConfig, MetaStorageOptions {
-    client?: BlobServiceClient;
-}
-export interface AzureStorageOptions extends BaseStorageOptions, ClientConfig {
-    /**
-     * Configure metafiles storage
-     * @example
-     * ```ts
-     * Using local metafiles
-     * const storage = new AzureStorage({
-     *   bucket: 'upload',
-     *   metaStorageConfig: { directory: '/tmp/upload-metafiles' }
-     * })
-     * ```
-     * Using a separate bucket for metafiles
-     * ```ts
-     * const storage = new AzureStorage({
-     *   bucket: 'upload',
-     *   metaStorageConfig: { bucket: 'upload-metafiles' }
-     * })
-     * ```
-     */
-    metaStorageConfig?: AzureMetaStorageOptions | LocalMetaStorageOptions;
-}
-export {};

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

@@ -1,11 +0,0 @@
-declare class FetchError extends Error {
-    code: string;
-    config: {
-        uri: string;
-    };
-    name: string;
-    constructor(message: string, code: string, config: {
-        uri: string;
-    });
-}
-export default FetchError;

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

@@ -1,2 +0,0 @@
-declare const GCSConfig: Record<string, string | string[]>;
-export default GCSConfig;

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

@@ -1,6 +0,0 @@
-import { File } from "../utils/index.d.ts";
-declare class GCSFile extends File {
-    GCSUploadURI?: string;
-    uri?: string;
-}
-export default GCSFile;

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

@@ -1,27 +0,0 @@
-import MetaStorage from "../meta-storage.d.ts";
-import type { File } from "../utils/index.d.ts";
-import type { GCSMetaStorageOptions } from "./types.d.ts";
-declare class GCSMetaStorage<T extends File = File> extends MetaStorage<T> {
-    readonly config: GCSMetaStorageOptions;
-    private authClient;
-    private readonly storageBaseURI;
-    private readonly uploadBaseURI;
-    private readonly isCustomEndpoint;
-    private readonly retryOptions;
-    private readonly useAuthWithCustomEndpoint;
-    private readonly userProject;
-    constructor(config: GCSMetaStorageOptions);
-    save(id: string, file: T): Promise<T>;
-    delete(id: string): Promise<void>;
-    get(id: string): Promise<T>;
-    touch(id: string, file: T): Promise<T>;
-    private accessCheck;
-    /**
-     * Returns metafile URL path for the given upload ID.
-     * @param id Upload ID to get metafile path for
-     * @returns Full URL path to the metafile in GCS
-     */
-    private getMetaPath;
-    private makeRequest;
-}
-export default GCSMetaStorage;