@d3oxy/s3-pilot

S3Pilot

S3Pilot is a TypeScript library that abstracts AWS S3 operations, making it easier to interact with S3 buckets and objects. It provides a cleaner API to manage file uploads, deletions, signed URL generation, and more.

Features

• Multi-client support with isolated configurations.
• Easily upload, delete, rename, and manage files in S3 buckets.
• Generate signed URLs for private access to objects.
• Validation for bucket access and file extensions.
• Supports custom key prefixes and folders.

Installation

# Using pnpm
pnpm install @d3oxy/s3-pilot

# Using npm
npm install @d3oxy/s3-pilot

# Using bun
bun add @d3oxy/s3-pilot

# Using yarn
yarn add @d3oxy/s3-pilot

Usage

Initialize S3Pilot

First, import the S3Pilot class into your TypeScript project:

import { S3ClientSettings, S3ClientsSetup, S3Pilot } from "@d3oxy/s3-pilot";

Configuration

Then create a new instance of S3Pilot with the desired S3 clients and their configurations:

const s3Pilot = new S3Pilot<
    S3ClientsSetup<{
        client1: S3ClientSettings<"bucket-A1" | "bucketA2">;
        client2: S3ClientSettings<"bucket-B1" | "bucketB2">;
    }>
>({
    client1: {
        region: "region",
        accessKeyId: "AWS_ACCESS_KEY_ID",
        secretAccessKey: "AWS_SECRET_ACCESS_KEY",
        buckets: ["bucket-A1", "bucketA2"],
        keyPrefix: process.env("NODE_ENV") === "development" ? "dev" : undefined,
    },
    client2: {
        region: "region",
        accessKeyId: "AWS_ACCESS_KEY_ID",
        secretAccessKey: "AWS_SECRET_ACCESS_KEY",
        buckets: ["bucket-B1", "bucketB2"],
        keyPrefix: process.env("NODE_ENV") === "development" ? "dev" : undefined,
    },
});

Upload Files

To upload files to an S3 bucket, use the upload method:

(async () => {
    const response = await s3Pilot.uploadFile("client1", "bucket-A1", {
        filename: "example.jpg",
        file: Buffer.from("Your file data"),
        contentType: "image/jpeg",
    });
    console.log("Uploaded File URL:", response.url);
})();

Delete Files

To delete files from an S3 bucket, use the delete method:

(async () => {
    await s3Pilot.deleteFile("client2", "bucket-B1", {
        key: "example.jpg",
    });
    console.log("File deleted successfully.");
})();

Generate Signed URLs

To generate signed URLs for private access to S3 objects, use the generateSignedUrl method:

(async () => {
    const signedUrl = await s3Pilot.generateSignedUrl("client1", "bucket-A1", {
        key: "example.jpg",
        expiresIn: 60, // URL valid for 60 seconds
    });
    console.log("Signed URL:", signedUrl);
})();

License

This project is licensed under the MIT License - see the LICENSE file for details.