Koadz - AWS S3 Bucket

⚡ Features

This package provides methods for interacting with AWS S3 Bucket. The key functionalities include:

• Create Bucket.
• Single File upload.
• Folder upload.

📦 Installation

To use the CLI tool, you need to have Node.js installed on your system. Once you have Node.js installed, you can install the CLI tool by running the following command:

# Set the APM registry to local (one-time process)
npm config set @koadz:registry <registry_url>

npm install -g @koadz/s3@latest
Copy

AWS Configuration

Before using this package, ensure that you have the AWS CLI configured locally, and the logged-in user has the necessary permissions for AWS S3.

Environment Variables

The following environment variables are required to use this package:

Key	Values	Default Value
KOADZ_ENV	development or production	development
KOADZ_DEBUG	true or false	false
KOADZ_AWS_S3_MAX_CONCURRENT_UPLOADS	number	8
KOADZ_AWS_S3_MAX_RETRIES	number	2

🚀 Usage

Here's how to use this package:

import { AWSS3 } from "@koadz/s3";

// Create an instance
const client = new AWSS3({
  region: "<region>", // required
  maxConcurrentUploads: 10, // default 8
  maxRetries: 5, // default 2
  logger: true, // default false
});

// Single file upload test case
await client.uploadFile({
  bucketName: "bucket-name",
  s3FolderPath: "destination/path", // this represents where the file or folder to be placed in AWS S3 Bucket (defaults to root of the bucket)
  filePath: "path/to/file",
});

// Folder content upload test case
await client.uploadFolder({
  bucketName: "bucket-name",
  localFolderPath: "folder/path",
  s3FolderPath: "destination/path", // this represents where the file or folder to be placed in AWS S3 Bucket (defaults to root of the bucket)
});

// Delete a file
await client.deleteFile({
  bucketName: "bucket-name",
  s3FolderPath: "path/to/file",
});

// Delete a folder
await client.deleteFolder({
  bucketName: "bucket-name",
  s3FolderPath: "path/to/folder",
});

// Create Bucket
const bucketName = "your-bucket-name";
const bucketOptions = {
  bucketName: bucketName,
  policies: {
    Version: "2012-10-17",
    Statement: [
      {
        Sid: "PublicReadGetObject",
        Effect: "Allow",
        Principal: "*",
        Action: "s3:GetObject",
        Resource: `arn:aws:s3:::${bucketName}/*`,
      },
    ],
  },
  bucketConfig: {
    // optional bucket configuration
  },
  policyConfig: {
    // optional policy configuration
  },
  publicAccessBlock: {
    // optional public access block configuration
    PublicAccessBlockConfiguration: {
      IgnorePublicAcls: false,
    },
  },
};

const { bucket, policy, publicAccess } = await client.createBucket(bucketOptions);

// Delete Bucket
await client.deleteBucket(bucketName);

// Manage versioning
await client.manageVersioning({
  bucketName: "bucket-name",
  status: "Enabled" | "Suspended",
});
Copy

Key	Valid	Invalid
s3FolderPath	"" or "some/file/or/folder/path"	"/" or "/some/path" or "/some/path/" or "/some\file\/path"

Customizing

You can customize the AWS S3 instance by passing options. Refer to the AWS Official Documentation for available configuration options:

import { AWSS3 } from "@koadz/s3";

const options = {
  S3ClientConfig: {
    // Accepts all AWS S3 options.
  },
  // ...
};

// Create an instance with custom options
const aws_s3 = new AWSS3(options);

export { aws_s3 };
Copy