@visulima/storage 1.0.0-alpha.8 → 1.0.0

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

@@ -1,248 +0,0 @@
-import { Readable } from "node:stream";
-import type { RetryConfig } from "../../utils/retry.d.ts";
-import { createRetryWrapper } from "../../utils/retry.d.ts";
-import type MetaStorage from "../meta-storage.d.ts";
-import { BaseStorage } from "../storage.d.ts";
-import type { File, FileInit, FilePart, FileQuery, FileReturn } from "../utils/index.d.ts";
-/**
- * Part interface for multipart uploads.
- */
-export interface Part {
-    ETag?: string;
-    PartNumber: number;
-    Size?: number;
-}
-/**
- * Base file type for S3-compatible storage.
- */
-export interface S3CompatibleFile extends File {
-    Parts?: Part[];
-    partSize?: number;
-    partsUrls?: string[];
-    UploadId?: string;
-    uri?: string;
-}
-/**
- * S3 API operations interface that must be implemented by concrete storage classes.
- */
-export interface S3ApiOperations {
-    abortMultipartUpload: (params: {
-        Bucket: string;
-        Key: string;
-        UploadId: string;
-    }) => Promise<void>;
-    checkBucketAccess: (params: {
-        Bucket: string;
-    }) => Promise<void>;
-    completeMultipartUpload: (params: {
-        Bucket: string;
-        Key: string;
-        Parts: {
-            ETag: string;
-            PartNumber: number;
-        }[];
-        UploadId: string;
-    }) => Promise<{
-        ETag?: string;
-        Location: string;
-    }>;
-    copyObject: (params: {
-        Bucket: string;
-        CopySource: string;
-        Key: string;
-        StorageClass?: string;
-    }) => Promise<void>;
-    createMultipartUpload: (params: {
-        ACL?: string;
-        Bucket: string;
-        ContentType?: string;
-        Key: string;
-        Metadata?: Record<string, string>;
-    }) => Promise<{
-        UploadId: string;
-    }>;
-    deleteObject: (params: {
-        Bucket: string;
-        Key: string;
-    }) => Promise<void>;
-    getObject: (params: {
-        Bucket: string;
-        Key: string;
-    }) => Promise<{
-        Body?: ReadableStream | Readable;
-        ContentLength?: number;
-        ContentType?: string;
-        ETag?: string;
-        Expires?: Date;
-        LastModified?: Date;
-        Metadata?: Record<string, string>;
-    }>;
-    getPresignedUrl: (params: {
-        Bucket: string;
-        expiresIn: number;
-        Key: string;
-        PartNumber: number;
-        UploadId: string;
-    }) => Promise<string>;
-    headObject: (params: {
-        Bucket: string;
-        Key: string;
-    }) => Promise<{
-        ContentLength?: number;
-        ContentType?: string;
-        ETag?: string;
-        Expires?: Date;
-        LastModified?: Date;
-        Metadata?: Record<string, string>;
-    }>;
-    listObjectsV2: (params: {
-        Bucket: string;
-        ContinuationToken?: string;
-        MaxKeys?: number;
-    }) => Promise<{
-        Contents?: {
-            Key?: string;
-            LastModified?: Date;
-        }[];
-        IsTruncated?: boolean;
-        NextContinuationToken?: string;
-    }>;
-    listParts: (params: {
-        Bucket: string;
-        Key: string;
-        UploadId: string;
-    }) => Promise<{
-        Parts?: Part[];
-    }>;
-    uploadPart: (params: {
-        Body: Readable | ReadableStream | Uint8Array;
-        Bucket: string;
-        ContentLength?: number;
-        ContentMD5?: string;
-        Key: string;
-        PartNumber: number;
-        UploadId: string;
-    }) => Promise<{
-        ETag: string;
-    }>;
-}
-/**
- * Base class for S3-compatible storage implementations.
- * Contains all shared business logic for S3 operations.
- * @template TFile The file type used by this storage backend.
- */
-export declare abstract class S3BaseStorage<TFile extends S3CompatibleFile = S3CompatibleFile> extends BaseStorage<TFile, FileReturn> {
-    checksumTypes: string[];
-    protected bucket: string;
-    protected meta: MetaStorage<TFile>;
-    /**
-     * S3 multipart upload does not allow more than 10000 parts.
-     */
-    protected readonly MAX_PARTS = 10000;
-    protected readonly partSize: number;
-    protected readonly retry: ReturnType<typeof createRetryWrapper>;
-    /**
-     * Abstract method to get S3 API operations implementation.
-     */
-    protected abstract getS3Api(): S3ApiOperations;
-    /**
-     * Abstract method to get the file class constructor.
-     */
-    protected abstract getFileClass(): new (config: FileInit) => TFile;
-    /**
-     * Abstract method to get ACL value.
-     */
-    protected abstract getAcl(): string | undefined;
-    /**
-     * Abstract method for access check.
-     */
-    protected abstract accessCheck(maxWaitTime?: number): Promise<void>;
-    constructor(config: {
-        bucket: string;
-        clientDirectUpload?: boolean;
-        expiration?: {
-            maxAge?: string;
-        };
-        filename?: (file: TFile) => string;
-        logger?: BaseStorage<TFile>["logger"];
-        metaStorage?: MetaStorage<TFile>;
-        metaStorageConfig?: unknown;
-        partSize?: number | string;
-        retryConfig?: RetryConfig;
-    });
-    /**
-     * Creates a new S3 multipart upload.
-     */
-    create(config: FileInit): Promise<TFile>;
-    /**
-     * Writes data to an S3 multipart upload.
-     */
-    write(part: FilePart | FileQuery | TFile): Promise<TFile>;
-    /**
-     * Deletes an upload and its metadata.
-     */
-    delete({ id }: FileQuery): Promise<TFile>;
-    /**
-     * Copies an upload file to a new location.
-     */
-    copy(name: string, destination: string, options?: {
-        storageClass?: string;
-    }): Promise<TFile>;
-    /**
-     * Moves an upload file to a new location.
-     */
-    move(name: string, destination: string): Promise<TFile>;
-    /**
-     * Lists files in the bucket.
-     */
-    list(limit?: number): Promise<TFile[]>;
-    /**
-     * Checks if a file exists by verifying both metadata and the actual S3 object.
-     * Returns true only if both the metadata and the S3 object exist.
-     * @param query File query containing the file ID to check.
-     * @returns Promise resolving to true if both metadata and S3 object exist, false otherwise.
-     */
-    exists({ id }: FileQuery): Promise<boolean>;
-    /**
-     * Gets an uploaded file by ID.
-     */
-    get({ id }: FileQuery): Promise<FileReturn>;
-    /**
-     * Gets file stream (abstract - must be implemented by subclasses due to stream differences).
-     */
-    abstract getStream(query: FileQuery): Promise<{
-        headers?: Record<string, string>;
-        size?: number;
-        stream: Readable;
-    }>;
-    /**
-     * Builds presigned URLs for client uploads.
-     */
-    protected buildPresigned(file: TFile): Promise<TFile>;
-    /**
-     * Gets presigned URLs for all parts.
-     */
-    protected getPartsPresignedUrls(file: TFile): Promise<string[]>;
-    /**
-     * Gets parts for a multipart upload.
-     */
-    protected getParts(file: TFile): Promise<Part[]>;
-    /**
-     * Completes a multipart upload.
-     */
-    protected completeMultipartUpload(file: TFile): Promise<{
-        ETag?: string;
-        Location: string;
-    }>;
-    /**
-     * Aborts a multipart upload.
-     */
-    protected abortMultipartUpload(file: TFile): Promise<void>;
-    /**
-     * Internal onComplete handler.
-     */
-    protected internalOnComplete: (file: TFile) => Promise<[{
-        ETag?: string;
-        Location: string;
-    }, TFile]>;
-}

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

@@ -1,110 +0,0 @@
-import { Readable } from "node:stream";
-import type { S3Client } from "@aws-sdk/client-s3";
-import type { Part, S3ApiOperations } from "./s3-base-storage.d.ts";
-type ReadableStream = globalThis.ReadableStream;
-/**
- * Adapter that wraps AWS SDK S3Client to implement S3ApiOperations interface.
- */
-declare class S3ClientAdapter implements S3ApiOperations {
-    private readonly client;
-    constructor(client: S3Client, _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;
-    }>;
-    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>;
-    checkBucketAccess(params: {
-        Bucket: string;
-    }): Promise<void>;
-}
-export default S3ClientAdapter;

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

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

package/dist/storage/aws/s3-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 { S3MetaStorageOptions } from "./types.d.ts";
-declare class S3MetaStorage<T extends File = File> extends MetaStorage<T> {
-    config: S3MetaStorageOptions;
-    private readonly bucket;
-    private readonly client;
-    constructor(config: S3MetaStorageOptions);
-    get(id: string): Promise<T>;
-    touch(id: string, file: T): Promise<T>;
-    delete(id: string): Promise<void>;
-    save(id: string, file: T): Promise<T>;
-    private accessCheck;
-}
-export default S3MetaStorage;

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<S3File> {
-    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,119 +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";
-import type S3File from "./s3-file.d.ts";
-export type S3MetaStorageOptions = MetaStorageOptions & S3ClientConfig & {
-    bucket?: string;
-    /**
-     * @internal
-     */
-    client?: S3Client;
-    keyFile?: string;
-};
-export type S3StorageOptions = BaseStorageOptions<S3File> & 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;