@d3oxy/s3-pilot NPM

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);
})();