@visulima/storage 1.0.0-alpha.8 → 1.0.0

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

@@ -1,4 +1,332 @@
-export { default as S3File } from "./s3-file.d.ts";
-export { default as S3MetaStorage } from "./s3-meta-storage.d.ts";
-export { default as S3Storage } from "./s3-storage.d.ts";
-export type { AwsError, AWSErrorV2, S3MetaStorageOptions, S3StorageOptions } from "./types.d.ts";
+import { F as File, k as MetaStorageOptions, l as BaseStorageOptions, L as LocalMetaStorageOptions, M as MetaStorage, H as HttpError, f as FileQuery, O as OperationOptions, d as FileInit } from "../../packem_shared/storage.d-CEM1upWM.js";
+import { Readable } from 'node:stream';
+import { P as Part, S as S3CallOptions, a as S3ApiOperations, b as S3BaseStorage } from "../../packem_shared/s3-base-storage.d-BQgP5B-t.js";
+import { S3ClientConfig, ObjectCannedACL, S3Client } from '@aws-sdk/client-s3';
+import { ResponseMetadata } from '@aws-sdk/types';
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+declare class S3File extends File {
+  Parts?: Part[];
+  UploadId?: string;
+  uri?: string;
+  partsUrls?: string[];
+  partSize?: number;
+}
+type S3MetaStorageOptions = MetaStorageOptions & S3ClientConfig & {
+  bucket?: string;
+  keyFile?: string;
+};
+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.
+*/
+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.
+*/
+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;
+}
+declare class S3MetaStorage<T extends File = File> extends MetaStorage<T> {
+  config: S3MetaStorageOptions;
+  private readonly bucket;
+  private readonly client;
+  constructor(config: S3MetaStorageOptions);
+  override get(id: string): Promise<T>;
+  override touch(id: string, file: T): Promise<T>;
+  override delete(id: string): Promise<void>;
+  override save(id: string, file: T): Promise<T>;
+  private accessCheck;
+}
+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>;
+  }, options?: S3CallOptions): Promise<{
+    UploadId: string;
+  }>;
+  uploadPart(params: {
+    Body: Readable | ReadableStream | Uint8Array;
+    Bucket: string;
+    ContentLength?: number;
+    ContentMD5?: string;
+    Key: string;
+    PartNumber: number;
+    UploadId: string;
+  }, options?: S3CallOptions): Promise<{
+    ETag: string;
+  }>;
+  completeMultipartUpload(params: {
+    Bucket: string;
+    Key: string;
+    Parts: {
+      ETag: string;
+      PartNumber: number;
+    }[];
+    UploadId: string;
+  }, options?: S3CallOptions): Promise<{
+    ETag?: string;
+    Location: string;
+  }>;
+  abortMultipartUpload(params: {
+    Bucket: string;
+    Key: string;
+    UploadId: string;
+  }, options?: S3CallOptions): Promise<void>;
+  listParts(params: {
+    Bucket: string;
+    Key: string;
+    UploadId: string;
+  }, options?: S3CallOptions): Promise<{
+    Parts?: Part[];
+  }>;
+  getObject(params: {
+    Bucket: string;
+    Key: string;
+    Range?: string;
+  }, options?: S3CallOptions): Promise<{
+    Body?: ReadableStream | Readable;
+    ContentLength?: number;
+    ContentType?: string;
+    ETag?: string;
+    Expires?: Date;
+    LastModified?: Date;
+    Metadata?: Record<string, string>;
+  }>;
+  headObject(params: {
+    Bucket: string;
+    Key: string;
+  }, options?: S3CallOptions): Promise<{
+    ContentLength?: number;
+    ContentType?: string;
+    ETag?: string;
+    Expires?: Date;
+    LastModified?: Date;
+  }>;
+  deleteObject(params: {
+    Bucket: string;
+    Key: string;
+  }, options?: S3CallOptions): Promise<void>;
+  copyObject(params: {
+    Bucket: string;
+    CopySource: string;
+    Key: string;
+    StorageClass?: string;
+  }, options?: S3CallOptions): Promise<void>;
+  listObjectsV2(params: {
+    Bucket: string;
+    ContinuationToken?: string;
+    Delimiter?: string;
+    MaxKeys?: number;
+    Prefix?: string;
+  }, options?: S3CallOptions): Promise<{
+    CommonPrefixes?: {
+      Prefix?: string;
+    }[];
+    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>;
+}
+/**
+* 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 override readonly name: string;
+  private s3Api;
+  private rawClient;
+  constructor(config: S3StorageOptions);
+  /**
+  * Normalizes AWS S3 errors with S3-specific context.
+  */
+  override normalizeError(error: AwsError): HttpError;
+  override update({
+    id
+  }: FileQuery, metadata: Partial<S3File>): Promise<S3File>;
+  override getStream({
+    id
+  }: FileQuery, options?: OperationOptions & {
+    range?: {
+      end?: number;
+      start: number;
+    };
+  }): Promise<{
+    headers?: Record<string, string>;
+    size?: number;
+    stream: Readable;
+  }>;
+  override get raw(): S3Client;
+  override getReadUrl(key: string, options?: {
+    expiresIn?: number;
+    responseContentDisposition?: string;
+    responseContentType?: string;
+  }): Promise<string>;
+  override getUploadUrl(key: string, options?: {
+    contentLength?: number;
+    contentType?: string;
+    expiresIn?: number;
+  }): Promise<string>;
+  protected getS3Api(): S3ClientAdapter;
+  protected getFileClass(): new (config: FileInit) => S3File;
+  protected getAcl(): string | undefined;
+  protected accessCheck(_maxWaitTime?: number): Promise<void>;
+}
+export { type AWSErrorV2, type AwsError, S3File, S3MetaStorage, type S3MetaStorageOptions, S3Storage, type S3StorageOptions };

package/dist/storage/aws/index.js

@@ -1,3 +1 @@
-export { default as S3File } from '../../packem_shared/S3File-DZiyk9Qt.js';
-export { default as S3MetaStorage } from '../../packem_shared/S3MetaStorage-Dz9aDabA.js';
-export { default as S3Storage } from '../../packem_shared/S3Storage-DHmTk-hU.js';
+import{default as t}from"../../packem_shared/S3File-CpZrubaV.js";import{default as r}from"../../packem_shared/S3MetaStorage-CMonflzp.js";import{default as S}from"../../packem_shared/S3Storage-wslqssvr.js";export{t as S3File,r as S3MetaStorage,S as S3Storage};

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

@@ -1,4 +1,259 @@
-export { default as AwsLightFile } from "./aws-light-file.d.ts";
-export { default as AwsLightMetaStorage } from "./aws-light-meta-storage.d.ts";
-export { default as AwsLightStorage } from "./aws-light-storage.d.ts";
-export type { AwsLightClientConfig, AwsLightError, AwsLightMetaStorageOptions, AwsLightStorageOptions } from "./types.d.ts";
+import { P as Part, S as S3CallOptions, a as S3ApiOperations, b as S3BaseStorage } from "../../packem_shared/s3-base-storage.d-BQgP5B-t.js";
+import { F as File, k as MetaStorageOptions, l as BaseStorageOptions, M as MetaStorage, H as HttpError, f as FileQuery, O as OperationOptions, d as FileInit } from "../../packem_shared/storage.d-CEM1upWM.js";
+import { Readable } from 'node:stream';
+import { AwsClient } from 'aws4fetch';
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+declare class AwsLightFile extends File {
+  Parts?: Part[];
+  UploadId?: string;
+  uri?: string;
+  partsUrls?: string[];
+  partSize?: number;
+}
+interface AwsLightClientConfig {
+  accessKeyId: string;
+  endpoint?: string;
+  region: string;
+  secretAccessKey: string;
+  service?: string;
+  sessionToken?: string;
+}
+type AwsLightMetaStorageOptions = AwsLightClientConfig & MetaStorageOptions & {
+  bucket?: string;
+};
+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;
+};
+interface AwsLightError extends Error {
+  code?: string;
+  requestId?: string;
+  statusCode?: number;
+}
+/**
+* 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);
+  override get(id: string): Promise<T>;
+  override touch(id: string, file: T): Promise<T>;
+  override delete(id: string): Promise<void>;
+  override save(id: string, file: T): Promise<T>;
+}
+/**
+* Adapter that uses aws4fetch to implement S3ApiOperations interface.
+*/
+declare class AwsLightApiAdapter implements S3ApiOperations {
+  aws: AwsClient;
+  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>;
+  }, options?: S3CallOptions): Promise<{
+    UploadId: string;
+  }>;
+  uploadPart(params: {
+    Body: Readable | ReadableStream | Uint8Array;
+    Bucket: string;
+    ContentLength?: number;
+    ContentMD5?: string;
+    Key: string;
+    PartNumber: number;
+    UploadId: string;
+  }, options?: S3CallOptions): Promise<{
+    ETag: string;
+  }>;
+  completeMultipartUpload(params: {
+    Bucket: string;
+    Key: string;
+    Parts: {
+      ETag: string;
+      PartNumber: number;
+    }[];
+    UploadId: string;
+  }, options?: S3CallOptions): Promise<{
+    ETag?: string;
+    Location: string;
+  }>;
+  abortMultipartUpload(params: {
+    Bucket: string;
+    Key: string;
+    UploadId: string;
+  }, options?: S3CallOptions): Promise<void>;
+  listParts(params: {
+    Bucket: string;
+    Key: string;
+    UploadId: string;
+  }, options?: S3CallOptions): Promise<{
+    Parts?: Part[];
+  }>;
+  getObject(params: {
+    Bucket: string;
+    Key: string;
+  }, options?: S3CallOptions): Promise<{
+    Body?: ReadableStream | Readable;
+    ContentLength?: number;
+    ContentType?: string;
+    ETag?: string;
+    Expires?: Date;
+    LastModified?: Date;
+    Metadata?: Record<string, string>;
+  }>;
+  headObject(params: {
+    Bucket: string;
+    Key: string;
+  }, options?: S3CallOptions): Promise<{
+    ContentLength?: number;
+    ContentType?: string;
+    ETag?: string;
+    Expires?: Date;
+    LastModified?: Date;
+    Metadata?: Record<string, string>;
+  }>;
+  deleteObject(params: {
+    Bucket: string;
+    Key: string;
+  }, options?: S3CallOptions): Promise<void>;
+  copyObject(params: {
+    Bucket: string;
+    CopySource: string;
+    Key: string;
+    StorageClass?: string;
+  }, options?: S3CallOptions): Promise<void>;
+  listObjectsV2(params: {
+    Bucket: string;
+    ContinuationToken?: string;
+    Delimiter?: string;
+    MaxKeys?: number;
+    Prefix?: string;
+  }, options?: S3CallOptions): Promise<{
+    CommonPrefixes?: {
+      Prefix?: string;
+    }[];
+    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;
+}
+/**
+* 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 override readonly name: string;
+  private s3Api;
+  constructor(config: AwsLightStorageOptions);
+  /**
+  * Normalizes AWS S3 errors with S3-specific context.
+  */
+  override normalizeError(error: AwsLightError | Error): HttpError;
+  override update({
+    id
+  }: FileQuery, metadata: Partial<AwsLightFile>): Promise<AwsLightFile>;
+  override getStream({
+    id
+  }: FileQuery, options?: OperationOptions): Promise<{
+    headers?: Record<string, string>;
+    size?: number;
+    stream: Readable;
+  }>;
+  override get raw(): AwsClient;
+  protected getS3Api(): AwsLightApiAdapter;
+  protected getFileClass(): new (config: FileInit) => AwsLightFile;
+  protected getAcl(): string | undefined;
+  protected accessCheck(_maxWaitTime?: number): Promise<void>;
+}
+export { type AwsLightClientConfig, type AwsLightError, AwsLightFile, AwsLightMetaStorage, type AwsLightMetaStorageOptions, AwsLightStorage, type AwsLightStorageOptions };

package/dist/storage/aws-light/index.js

@@ -1,3 +1 @@
-export { default as AwsLightFile } from '../../packem_shared/AwsLightFile-tTneXZgG.js';
-export { A as AwsLightMetaStorage } from '../../packem_shared/aws-light-meta-storage-DKJBgbR6.js';
-export { default as AwsLightStorage } from '../../packem_shared/AwsLightStorage-Blv-GP4v.js';
+import{default as a}from"../../packem_shared/AwsLightFile-CpZrubaV.js";import{p as r}from"../../packem_shared/aws-light-meta-storage-DGrn72VJ.js";import{default as f}from"../../packem_shared/AwsLightStorage-DTBVxHXO.js";export{a as AwsLightFile,r as AwsLightMetaStorage,f as AwsLightStorage};