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

package/dist/packem_shared/types.d-D-mlfmef.d.ts

@@ -0,0 +1,49 @@
+import { EventEmitter } from 'node:events';
+import { IncomingMessage } from 'node:http';
+import { Readable } from 'node:stream';
+import { PaginationResult } from '@visulima/pagination';
+import { U as UploadFile, B as BaseStorage, f as UploadError, g as UploadEventType } from "./storage.d-BOMUJD96.js";
+import { M as MediaTransformer } from "./media-transformer.d-DeHZkBVx.js";
+type WebRequest = globalThis.Request;
+type WebResponse = globalThis.Response;
+interface BaseResponse {
+  headers: Record<string, number | string>;
+  statusCode: number;
+}
+interface StreamingResponse extends BaseResponse {
+  /** Total size of the stream (for Content-Length header) */
+  size?: number;
+  /** Stream of data to send */
+  stream: Readable;
+}
+interface RequestEvent {
+  request: Pick<IncomingMessage, "headers" | "method" | "url">;
+}
+type AsyncHandler<Request, Response> = (request: Request, response: Response) => Promise<void | ResponseFile<UploadFile> | ResponseList<UploadFile> | StreamingResponse>;
+type Handlers = "delete" | "download" | "get" | "head" | "options" | "patch" | "post" | "put";
+type MethodHandler<Request, Response> = { [h in Handlers]?: AsyncHandler<Request, Response> };
+type UploadEvent<TFile extends UploadFile> = RequestEvent & TFile;
+type UploadErrorEvent = RequestEvent & UploadError;
+type ResponseFile<TFile extends UploadFile> = BaseResponse & TFile & {
+  /** Optional stream for streaming responses instead of content buffer */
+  stream?: Readable;
+};
+type ResponseList<TFile extends UploadFile> = BaseResponse & {
+  data: PaginationResult<TFile> | TFile[];
+};
+interface BaseHandler<TFile extends UploadFile> extends EventEmitter {
+  emit: ((event: "error", error: UploadErrorEvent) => boolean) & ((event: UploadEventType, payload: UploadEvent<TFile>) => boolean);
+  fetch: (request: WebRequest) => Promise<WebResponse>;
+  off: ((event: "error", listener: (error: UploadErrorEvent) => void) => this) & ((event: UploadEventType, listener: (payload: UploadEvent<TFile>) => void) => this);
+  on: ((event: "error", listener: (error: UploadErrorEvent) => void) => this) & ((event: UploadEventType, listener: (payload: UploadEvent<TFile>) => void) => this);
+}
+interface UploadOptions<TFile extends UploadFile> {
+  disableTerminationForFinishedUploads?: boolean;
+  /** Maximum file size for multipart parser (default: min(storage.maxUploadSize, 1GB)) */
+  maxFileSize?: number;
+  /** Maximum header size for multipart parser (default: 64KB) */
+  maxHeaderSize?: number;
+  mediaTransformer?: MediaTransformer;
+  storage: BaseStorage<TFile>;
+}
+export { AsyncHandler as A, BaseHandler as B, Handlers as H, MethodHandler as M, ResponseFile as R, UploadOptions as U, ResponseList as a, RequestEvent as b, UploadErrorEvent as c, UploadEvent as d };

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

@@ -1,6 +1,166 @@
-export { default as backblaze } from "./backblaze.d.ts";
-export { default as cloudflare } from "./cloudflare.d.ts";
-export { default as digitalOcean } from "./digital-ocean.d.ts";
-export { default as minio } from "./minio.d.ts";
-export { default as tigris } from "./tigris.d.ts";
-export { default as wasabi } from "./wasabi.d.ts";
+import { S as S3ClientConfig } from "../../../packem_shared/S3Client.d-CZ62Jztg.js";
+import '@aws-sdk/middleware-flexible-checksums';
+import '@aws-sdk/middleware-host-header';
+import '@aws-sdk/middleware-sdk-s3';
+import '@aws-sdk/middleware-user-agent';
+import '@smithy/types';
+import '@smithy/config-resolver';
+import '@smithy/eventstream-serde-config-resolver';
+import '@smithy/middleware-endpoint';
+import '@smithy/middleware-retry';
+import '@smithy/protocol-http';
+import '@smithy/smithy-client';
+import 'node:stream';
+import '@aws-sdk/core/httpAuthSchemes';
+type CreateCloudflareClientParameters = {
+  /**
+  * Cloudflare R2 access key ID.
+  */
+  accessKeyId: string;
+  /**
+  * Cloudflare account ID.
+  */
+  accountId: string;
+  /**
+  * The jurisdiction where the data is stored.
+  *
+  * Only use this if you created your R2 bucket using a jurisdiction.
+  */
+  jurisdiction?: "eu" | "fedramp";
+  /**
+  * Cloudflare R2 secret access key.
+  */
+  secretAccessKey: string;
+};
+type CreateMinioClientParameters = {
+  /**
+  * Minio access key ID.
+  */
+  accessKeyId: string;
+  /**
+  * Minio endpoint.
+  */
+  endpoint: string;
+  /**
+  * Minio region.
+  */
+  region: string;
+  /**
+  * Minio secret access key.
+  */
+  secretAccessKey: string;
+};
+type CreateBackblazeClientParameters = {
+  /**
+  * Backblaze B2 application key.
+  */
+  applicationKey: string;
+  /**
+  * Backblaze B2 application key ID.
+  */
+  applicationKeyId: string;
+  /**
+  * Backblaze B2 region.
+  */
+  region: string;
+};
+type CreateWasabiClientParameters = {
+  /**
+  * Wasabi access key ID.
+  */
+  accessKeyId: string;
+  /**
+  * Wasabi region.
+  */
+  region: string;
+  /**
+  * Wasabi secret access key.
+  */
+  secretAccessKey: string;
+};
+type CreateDigitalOceanClientParameters = {
+  /**
+  * DigitalOcean Spaces key.
+  */
+  key: string;
+  /**
+  * DigitalOcean Spaces region.
+  */
+  region: string;
+  /**
+  * DigitalOcean Spaces secret.
+  */
+  secret: string;
+};
+type CreateTigrisClientParameters = {
+  /**
+  * Tigris access key ID.
+  */
+  accessKeyId: string;
+  /**
+  * Tigris endpoint.
+  * @default `https://t3.storage.dev`
+  */
+  endpoint?: string;
+  /**
+  * Tigris secret access key.
+  */
+  secretAccessKey: string;
+};
+/**
+* Create a Backblaze B2 client, compatible with the S3 API.
+*
+* Optionally, you can omit the parameters and use the following environment variables:
+* - `B2_REGION`
+* - `B2_APP_KEY_ID`
+* - `B2_APP_KEY`
+*/
+declare const backblaze: (parameters?: CreateBackblazeClientParameters) => S3ClientConfig;
+/**
+* Create a Cloudflare R2 client, compatible with the S3 API.
+*
+* Optionally, you can omit the parameters and use the following environment variables:
+* - `CLOUDFLARE_ACCOUNT_ID`
+* - `AWS_ACCESS_KEY_ID`
+* - `AWS_SECRET_ACCESS_KEY`
+* - `CLOUDFLARE_JURISDICTION`
+*/
+declare const cloudflare: (parameters?: CreateCloudflareClientParameters) => S3ClientConfig;
+/**
+* Create a DigitalOcean Spaces client, compatible with the S3 API.
+*
+* Optionally, you can omit the parameters and use the following environment variables:
+* - `SPACES_REGION`
+* - `SPACES_KEY`
+* - `SPACES_SECRET`
+*/
+declare const digitalOcean: (parameters?: CreateDigitalOceanClientParameters) => S3ClientConfig;
+/**
+* Create a Minio client, compatible with the S3 API.
+*
+* Optionally, you can omit the parameters and use the following environment variables:
+* - `AWS_REGION`
+* - `AWS_ACCESS_KEY_ID`
+* - `AWS_SECRET_ACCESS_KEY`
+* - `MINIO_ENDPOINT`
+*/
+declare const minio: (parameters?: CreateMinioClientParameters) => S3ClientConfig;
+/**
+* Create a Tigris client, compatible with the S3 API.
+*
+* Optionally, you can omit the parameters and use the following environment variables:
+* - `AWS_ACCESS_KEY_ID`
+* - `AWS_SECRET_ACCESS_KEY`
+* - `TIGRIS_ENDPOINT`
+*/
+declare const tigris: (parameters?: CreateTigrisClientParameters) => S3ClientConfig;
+/**
+* Create a Wasabi client, compatible with the S3 API.
+*
+* Optionally, you can omit the parameters and use the following environment variables:
+* - `WASABI_REGION`
+* - `AWS_ACCESS_KEY_ID`
+* - `AWS_SECRET_ACCESS_KEY`
+*/
+declare const wasabi: (parameters?: CreateWasabiClientParameters) => S3ClientConfig;
+export { backblaze, cloudflare, digitalOcean, minio, tigris, wasabi };

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

@@ -1,4 +1,320 @@
-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, m as MetaStorageOptions, k as BaseStorageOptions, L as LocalMetaStorageOptions, M as MetaStorage, H as HttpError, e as FileQuery, b as FileInit } from "../../packem_shared/storage.d-BOMUJD96.js";
+import { Readable } from 'node:stream';
+import { P as Part, S as S3ApiOperations, a as S3BaseStorage } from "../../packem_shared/s3-base-storage.d-CczjSe98.js";
+import { S as S3ClientConfig, O as ObjectCannedACL, a as S3Client } from "../../packem_shared/S3Client.d-CZ62Jztg.js";
+import { ResponseMetadata } from '@smithy/types';
+import 'node:crypto';
+import 'node:http';
+import 'lru-cache';
+import '@aws-sdk/middleware-flexible-checksums';
+import '@aws-sdk/middleware-host-header';
+import '@aws-sdk/middleware-sdk-s3';
+import '@aws-sdk/middleware-user-agent';
+import '@smithy/config-resolver';
+import '@smithy/eventstream-serde-config-resolver';
+import '@smithy/middleware-endpoint';
+import '@smithy/middleware-retry';
+import '@smithy/protocol-http';
+import '@smithy/smithy-client';
+import '@aws-sdk/core/httpAuthSchemes';
+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>;
+  }): 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>;
+}
+/**
+* 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;
+  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): 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 { type AWSErrorV2, type AwsError, S3File, S3MetaStorage, type S3MetaStorageOptions, S3Storage, type S3StorageOptions };