@better-media/adapter-storage-s3 0.1.0 → 0.2.0

package/README.md

@@ -4,21 +4,35 @@ Amazon S3 and S3-compatible storage adapter for the Better Media framework.
 
 ## Features
 
-- **S3 Support**: Works with AWS S3, Minio, DigitalOcean Spaces, Cloudflare R2, etc.
-- **Presigned URLs**: Securely upload from or download to the browser without exposing credentials.
-- **Streaming**: Supports high-performance streaming for large media files.
+- **S3 Support**: Works with AWS S3, MinIO, DigitalOcean Spaces, Cloudflare R2, etc.
+- **Dynamic Buckets**: Supports function-based bucket resolution dynamically per file key.
+- **Presigned URLs**: Securely upload from or download to the browser without exposing credentials using both PUT and POST policies.
+- **Bulk & Directory Operations**: Native support for bulk deletions, moving, copying, and directory enumeration.
+- **Multipart Uploads**: Deeply integrated support for chunked uploading sequences.
+- **Bucket Lifecycle & CORS**: Configure S3 buckets programmatically via the adapter.
 
 ## Usage
 
 ```ts
 import { S3StorageAdapter } from "@better-media/adapter-storage-s3";
 
-const storage = new S3StorageAdapter({
+// AWS S3 Example
+const s3Storage = new S3StorageAdapter({
   region: "us-east-1",
   bucket: "media-bucket",
   accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
   secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
 });
+
+// MinIO / Custom Endpoint Example
+const minioStorage = new S3StorageAdapter({
+  region: "us-east-1",
+  bucket: "local-bucket",
+  accessKeyId: "minio-root-user",
+  secretAccessKey: "minio-root-password",
+  endpoint: "http://localhost:9000",
+  forcePathStyle: true,
+});
 ```
 
-See [better-media.dev/docs/adapters/storage-s3](https://better-media.dev/docs/adapters/storage-s3) for more details.
+See [better-media-platform.vercel.app/docs/adapters/storage-s3](https://better-media-platform.vercel.app/docs/adapters/storage-s3) for more details.

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-import { StorageAdapter, GetUrlOptions, PresignedUploadOptions, PresignedUploadResult } from '@better-media/core';
+import { Buffer } from 'node:buffer';
+import { StorageAdapter, ListOptions, ListResult, GetUrlOptions, PresignedUploadOptions, PresignedUploadResult } from '@better-media/core';
 
 interface S3StorageConfig {
     /** AWS region (e.g. "us-east-1") */
@@ -21,6 +22,76 @@ interface S3StorageConfig {
     forcePathStyle?: boolean;
 }
 
+declare enum EnumS3Accessibility {
+    public = "public",
+    private = "private"
+}
+interface S3Object {
+    bucket: string;
+    key: string;
+    cdnUrl?: string;
+    completedUrl: string;
+    mime: string;
+    extension: string;
+    access?: EnumS3Accessibility;
+    size: number;
+    data?: unknown;
+}
+interface S3MultipartPart {
+    size: number;
+    eTag: string;
+    partNumber: number;
+}
+interface S3Multipart {
+    bucket: string;
+    key: string;
+    uploadId: string;
+    lastPartNumber: number;
+    maxPartNumber: number;
+    parts: S3MultipartPart[];
+}
+interface S3Presign {
+    key: string;
+    mime: string;
+    extension: string;
+    presignUrl: string;
+    expiredIn: number;
+}
+interface S3PresignPart extends S3Presign {
+    size: number;
+    partNumber: number;
+}
+interface S3Options {
+    access?: EnumS3Accessibility;
+}
+interface S3PutItemOptions extends S3Options {
+    forceUpdate?: boolean;
+}
+interface S3GetItemsOptions extends S3Options {
+    continuationToken?: string;
+}
+type S3DeleteDirOptions = S3GetItemsOptions;
+interface S3PresignGetItemOptions extends S3Options {
+    expired?: number;
+}
+interface S3PresignPutItemOptions extends S3PutItemOptions {
+    expired?: number;
+}
+interface S3PresignPutItemPartOptions extends S3Options {
+    expired?: number;
+}
+interface S3MoveItemOptions {
+    accessFrom?: EnumS3Accessibility;
+    accessTo?: EnumS3Accessibility;
+}
+interface S3CreateMultiplePart {
+    key: string;
+    size?: number;
+}
+interface S3PutItem extends S3CreateMultiplePart {
+    file: Buffer;
+}
+
 /**
  * S3 storage adapter for production deployments.
  * Supports AWS S3 and S3-compatible object storage (MinIO, etc.).
@@ -28,16 +99,50 @@ interface S3StorageConfig {
 declare class S3StorageAdapter implements StorageAdapter {
     private readonly client;
     private readonly bucketResolver;
+    private readonly region;
+    private readonly endpoint?;
+    private readonly forcePathStyle;
     constructor(config: S3StorageConfig);
     private isNotFoundError;
     private getBucket;
+    private getPublicUrl;
     get(key: string): Promise<Buffer | null>;
     put(key: string, value: Buffer): Promise<void>;
     delete(key: string): Promise<void>;
     exists(key: string): Promise<boolean>;
+    checkConnection(): Promise<boolean>;
+    checkBucket(_options?: S3Options): Promise<boolean>;
+    checkItem(key: string, _options?: S3Options): Promise<S3Object>;
+    getItem(key: string, _options?: S3Options): Promise<S3Object>;
+    putItem(file: S3PutItem, _options?: S3PutItemOptions): Promise<S3Object>;
     getSize(key: string): Promise<number | null>;
     getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
+    list(prefix: string, options?: ListOptions): Promise<ListResult>;
+    getItems(path: string, options?: S3GetItemsOptions): Promise<S3Object[]>;
+    deleteMany(keys: string[]): Promise<void>;
+    deleteItems(keys: string[], _options?: S3Options): Promise<void>;
+    deleteDir(path: string, options?: S3DeleteDirOptions): Promise<void>;
+    copy(source: string, destination: string): Promise<void>;
+    move(source: string, destination: string): Promise<void>;
+    moveItem(source: S3Object, destinationKey: string, _options?: S3MoveItemOptions): Promise<S3Object>;
+    moveItems(sources: S3Object[], destinationPrefix: string, _options?: S3Options): Promise<S3Object[]>;
+    createMultiPart(file: S3CreateMultiplePart, maxPartNumber: number, _options?: S3Options): Promise<S3Multipart>;
+    putItemMultiPart(multipart: S3Multipart, partNumber: number, file: Buffer, _options?: S3Options): Promise<S3Multipart>;
+    completeMultipart(key: string, uploadId: string, parts: S3MultipartPart[], _options?: S3Options): Promise<void>;
+    abortMultipart(key: string, uploadId: string, _options?: S3Options): Promise<void>;
     getUrl(key: string, options?: GetUrlOptions): Promise<string>;
+    presignGetItem(key: string, options?: S3PresignGetItemOptions): Promise<S3Presign>;
+    presignPutItem(file: S3CreateMultiplePart, options?: S3PresignPutItemOptions): Promise<S3Presign>;
+    presignPutItemPart(file: S3CreateMultiplePart & {
+        uploadId: string;
+        partNumber: number;
+    }, options?: S3PresignPutItemPartOptions): Promise<S3PresignPart>;
+    settingBucketPolicy(_options?: S3Options): Promise<void>;
+    settingCorsConfiguration(_options?: S3Options): Promise<void>;
+    settingBucketExpiredObjectLifecycle(_options: S3Options): Promise<void>;
+    settingDisableAclConfiguration(_options?: S3Options): Promise<void>;
+    settingBlockPublicAccessConfiguration(_options?: S3Options): Promise<void>;
+    mapPresign(file: S3CreateMultiplePart, _options?: S3Options): S3Object;
     /**
      * Create a presigned upload for direct-to-storage upload.
      *
@@ -54,4 +159,4 @@ declare class S3StorageAdapter implements StorageAdapter {
     private _createPresignedPut;
 }
 
-export { S3StorageAdapter, type S3StorageConfig };
+export { EnumS3Accessibility, type S3CreateMultiplePart, type S3DeleteDirOptions, type S3GetItemsOptions, type S3MoveItemOptions, type S3Multipart, type S3MultipartPart, type S3Object, type S3Options, type S3Presign, type S3PresignGetItemOptions, type S3PresignPart, type S3PresignPutItemOptions, type S3PresignPutItemPartOptions, type S3PutItem, type S3PutItemOptions, S3StorageAdapter, type S3StorageConfig };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import { StorageAdapter, GetUrlOptions, PresignedUploadOptions, PresignedUploadResult } from '@better-media/core';
+import { Buffer } from 'node:buffer';
+import { StorageAdapter, ListOptions, ListResult, GetUrlOptions, PresignedUploadOptions, PresignedUploadResult } from '@better-media/core';
 
 interface S3StorageConfig {
     /** AWS region (e.g. "us-east-1") */
@@ -21,6 +22,76 @@ interface S3StorageConfig {
     forcePathStyle?: boolean;
 }
 
+declare enum EnumS3Accessibility {
+    public = "public",
+    private = "private"
+}
+interface S3Object {
+    bucket: string;
+    key: string;
+    cdnUrl?: string;
+    completedUrl: string;
+    mime: string;
+    extension: string;
+    access?: EnumS3Accessibility;
+    size: number;
+    data?: unknown;
+}
+interface S3MultipartPart {
+    size: number;
+    eTag: string;
+    partNumber: number;
+}
+interface S3Multipart {
+    bucket: string;
+    key: string;
+    uploadId: string;
+    lastPartNumber: number;
+    maxPartNumber: number;
+    parts: S3MultipartPart[];
+}
+interface S3Presign {
+    key: string;
+    mime: string;
+    extension: string;
+    presignUrl: string;
+    expiredIn: number;
+}
+interface S3PresignPart extends S3Presign {
+    size: number;
+    partNumber: number;
+}
+interface S3Options {
+    access?: EnumS3Accessibility;
+}
+interface S3PutItemOptions extends S3Options {
+    forceUpdate?: boolean;
+}
+interface S3GetItemsOptions extends S3Options {
+    continuationToken?: string;
+}
+type S3DeleteDirOptions = S3GetItemsOptions;
+interface S3PresignGetItemOptions extends S3Options {
+    expired?: number;
+}
+interface S3PresignPutItemOptions extends S3PutItemOptions {
+    expired?: number;
+}
+interface S3PresignPutItemPartOptions extends S3Options {
+    expired?: number;
+}
+interface S3MoveItemOptions {
+    accessFrom?: EnumS3Accessibility;
+    accessTo?: EnumS3Accessibility;
+}
+interface S3CreateMultiplePart {
+    key: string;
+    size?: number;
+}
+interface S3PutItem extends S3CreateMultiplePart {
+    file: Buffer;
+}
+
 /**
  * S3 storage adapter for production deployments.
  * Supports AWS S3 and S3-compatible object storage (MinIO, etc.).
@@ -28,16 +99,50 @@ interface S3StorageConfig {
 declare class S3StorageAdapter implements StorageAdapter {
     private readonly client;
     private readonly bucketResolver;
+    private readonly region;
+    private readonly endpoint?;
+    private readonly forcePathStyle;
     constructor(config: S3StorageConfig);
     private isNotFoundError;
     private getBucket;
+    private getPublicUrl;
     get(key: string): Promise<Buffer | null>;
     put(key: string, value: Buffer): Promise<void>;
     delete(key: string): Promise<void>;
     exists(key: string): Promise<boolean>;
+    checkConnection(): Promise<boolean>;
+    checkBucket(_options?: S3Options): Promise<boolean>;
+    checkItem(key: string, _options?: S3Options): Promise<S3Object>;
+    getItem(key: string, _options?: S3Options): Promise<S3Object>;
+    putItem(file: S3PutItem, _options?: S3PutItemOptions): Promise<S3Object>;
     getSize(key: string): Promise<number | null>;
     getStream(key: string): Promise<ReadableStream<Uint8Array> | null>;
+    list(prefix: string, options?: ListOptions): Promise<ListResult>;
+    getItems(path: string, options?: S3GetItemsOptions): Promise<S3Object[]>;
+    deleteMany(keys: string[]): Promise<void>;
+    deleteItems(keys: string[], _options?: S3Options): Promise<void>;
+    deleteDir(path: string, options?: S3DeleteDirOptions): Promise<void>;
+    copy(source: string, destination: string): Promise<void>;
+    move(source: string, destination: string): Promise<void>;
+    moveItem(source: S3Object, destinationKey: string, _options?: S3MoveItemOptions): Promise<S3Object>;
+    moveItems(sources: S3Object[], destinationPrefix: string, _options?: S3Options): Promise<S3Object[]>;
+    createMultiPart(file: S3CreateMultiplePart, maxPartNumber: number, _options?: S3Options): Promise<S3Multipart>;
+    putItemMultiPart(multipart: S3Multipart, partNumber: number, file: Buffer, _options?: S3Options): Promise<S3Multipart>;
+    completeMultipart(key: string, uploadId: string, parts: S3MultipartPart[], _options?: S3Options): Promise<void>;
+    abortMultipart(key: string, uploadId: string, _options?: S3Options): Promise<void>;
     getUrl(key: string, options?: GetUrlOptions): Promise<string>;
+    presignGetItem(key: string, options?: S3PresignGetItemOptions): Promise<S3Presign>;
+    presignPutItem(file: S3CreateMultiplePart, options?: S3PresignPutItemOptions): Promise<S3Presign>;
+    presignPutItemPart(file: S3CreateMultiplePart & {
+        uploadId: string;
+        partNumber: number;
+    }, options?: S3PresignPutItemPartOptions): Promise<S3PresignPart>;
+    settingBucketPolicy(_options?: S3Options): Promise<void>;
+    settingCorsConfiguration(_options?: S3Options): Promise<void>;
+    settingBucketExpiredObjectLifecycle(_options: S3Options): Promise<void>;
+    settingDisableAclConfiguration(_options?: S3Options): Promise<void>;
+    settingBlockPublicAccessConfiguration(_options?: S3Options): Promise<void>;
+    mapPresign(file: S3CreateMultiplePart, _options?: S3Options): S3Object;
     /**
      * Create a presigned upload for direct-to-storage upload.
      *
@@ -54,4 +159,4 @@ declare class S3StorageAdapter implements StorageAdapter {
     private _createPresignedPut;
 }
 
-export { S3StorageAdapter, type S3StorageConfig };
+export { EnumS3Accessibility, type S3CreateMultiplePart, type S3DeleteDirOptions, type S3GetItemsOptions, type S3MoveItemOptions, type S3Multipart, type S3MultipartPart, type S3Object, type S3Options, type S3Presign, type S3PresignGetItemOptions, type S3PresignPart, type S3PresignPutItemOptions, type S3PresignPutItemPartOptions, type S3PutItem, type S3PutItemOptions, S3StorageAdapter, type S3StorageConfig };