@csn-storage/aws-s3

A Node.js package for managing files in an AWS S3 bucket. This package provides a simple and efficient way to upload, download, list, and delete files in an S3 bucket. It also includes features for generating pre-signed URLs. Ideal for applications that require robust file management capabilities with AWS S3.

Features

Upload files to an S3 bucket.
Download files from an S3 bucket.
Delete files from an S3 bucket.
Delete directories (all files within a directory) from an S3 bucket.
Generate pre-signed URLs for secure, time-limited access to files.
Streamable URLs for inline content display (e.g., images, videos).

Installation

To install the package, use npm:

npm install @csn-storage/aws-s3

Usage

1. Import the Package

const { createClient, getPublicURL, uploadFile, deleteFile, deleteDir } = require('@csn-storage/aws-s3');

2. Create an S3 Client

Before performing any operations, you need to create an S3 client instance using your AWS credentials.

const s3Client = createClient('your-region', 'your-access-key-id', 'your-secret-access-key');

Parameters:
- region (string): AWS region (e.g., us-east-1).
- accessKeyId (string): AWS access key ID.
- secretAccessKey (string): AWS secret access key.
Returns: An instance of S3Client.

3. Upload a File

Upload a file to an S3 bucket.

The uploadFile function allows you to upload a file to an S3 bucket. You can specify the file name, including the folder name, to upload the file to a specific location in the bucket.

const imageBuffer = fs.readFileSync('path/to/image.jpg');
await uploadFile(s3Client, 'your-bucket-name', 'images/image.jpg', imageBuffer);

Parameters:
- s3Client (S3Client): An instance of S3Client.
- bucketName (string): Name of the S3 bucket.
- fileName (string): Name of the file.
- file (Buffer | Object): A Buffer or a file object with a buffer property.
Returns: A promise that resolves when the file is uploaded.

Conditions

The file parameter can be either a Buffer or a file object with a buffer property.
The fileName parameter should include the folder name if you want to upload the file to a specific folder.
The bucketName parameter should be the name of the S3 bucket where you want to upload the file.

Example: Uploading an Image

Here’s an example of uploading an image file (e.g., image.jpg) to a specific folder in the S3 bucket:

// Example: Uploading an image file
    const fs = require('fs');

    // Read the image file into a Buffer
    const imageBuffer = fs.readFileSync('path/to/image.jpg');

    // Upload the image to the S3 bucket
    await uploadFile(s3Client, 'your-bucket-name', 'images/image.jpg', imageBuffer);

Explanation:

The fs.readFileSync method reads the image file into a Buffer.
The uploadFile function uploads the image to the S3 bucket under the folder images/ with the file name image.jpg.

Example: Uploading an Image with a File Object

Here’s an example of uploading an image file (e.g., image.jpg) to a specific folder in the S3 bucket using a file object:

// Example: Uploading an image file with a file object
    const fs = require('fs');

    // Read the image file into a Buffer
    const imageBuffer = fs.readFileSync('path/to/image.jpg');

    // Create a file object with the buffer property
    const imageFile = { buffer: imageBuffer };

    // Upload the image to the S3 bucket
    await uploadFile(s3Client, 'your-bucket-name', 'images/image.jpg', imageFile);

Explanation:

The fs.readFileSync method reads the image file into a Buffer.
The file object is created with the buffer property set to the image buffer.
The uploadFile function uploads the image to the S3 bucket under the folder images/ with the file name image.jpg.

4. Generate a Pre-Signed URL

Generate a pre-signed URL for a file in the S3 bucket.

The getPublicURL function allows you to generate a pre-signed URL for a file in the S3 bucket. This URL provides secure, time-limited access to the file.

const imageUrl = await getPublicURL(s3Client, 'your-bucket-name', 'images/image.jpg', 10, true);

Parameters:
- s3Client (S3Client): An instance of S3Client.
- bucketName (string): Name of the S3 bucket.
- fileName (string): Name of the file.
- expiresInMinutes (number, optional): Time in minutes until the URL expires. Default is 10.
- isStreamable (boolean, optional): If true, the URL will be streamable (e.g., for inline content). Default is false.
Returns: A pre-signed URL (string).

Conditions

The fileName parameter should include the folder name if the file is located in a specific folder.
The expiresInMinutes parameter specifies the time (in minutes) until the URL expires. The default is 10 minutes.
The isStreamable parameter, if set to true, generates a URL that can be used to stream the file (e.g., for inline content like images or videos).

Example: Generating a Pre-Signed URL for an Image

Here’s an example of generating a pre-signed URL for an image file (e.g., image.jpg) in the S3 bucket:

// Generate a pre-signed URL for an image file
    const imageUrl = await getPublicURL(s3Client, 'your-bucket-name', 'images/image.jpg', 10, true);
    console.log(imageUrl);

Explanation:

The getPublicURL function generates a pre-signed URL for the file images/image.jpg in the S3 bucket.
The URL expires in 10 minutes (expiresInMinutes: 10).
The isStreamable: true parameter ensures the URL can be used to stream the image inline (e.g., in a web page).

5. Delete a File

Delete a file from the S3 bucket.

The deleteFile function allows you to delete a specific file from the S3 bucket.

await deleteFile(s3Client, 'your-bucket-name', 'images/image.jpg');

Parameters:
- s3Client (S3Client): An instance of S3Client.
- bucketName (string): Name of the S3 bucket.
- fileName (string): Name of the file.
Returns: A promise that resolves when the file is deleted.

Conditions

The fileName parameter should include the folder name if the file is located in a specific folder.
The bucketName parameter should be the name of the S3 bucket where the file is stored.

Example: Deleting an Image File

Here’s an example of deleting an image file (e.g., image.jpg) from the S3 bucket:

// Delete an image file from the S3 bucket
    await deleteFile(s3Client, 'your-bucket-name', 'images/image.jpg');

Explanation:

The deleteFile function deletes the file images/image.jpg from the S3 bucket.
The file is permanently removed from the bucket.

6. Delete a Directory

Delete all files within a directory in the S3 bucket.

The deleteDir function allows you to delete all files within a specific directory (folder) in the S3 bucket.

await deleteDir(s3Client, 'your-bucket-name', 'images');

Parameters:
- s3Client (S3Client): An instance of S3Client.
- bucketName (string): Name of the S3 bucket.
- dirName (string): Name of the directory to delete.
Returns: A promise that resolves when the directory and its contents are deleted.

Conditions

The bucketName parameter should be the name of the S3 bucket where the directory is located.
The function recursively deletes all files within the specified directory.

Example: Deleting a Directory

Here’s an example of deleting all files within the images/ directory in the S3 bucket:

// Delete all files within the 'images/' directory
    await deleteDir(s3Client, 'your-bucket-name', 'images/');

Explanation:

The deleteDir function deletes all files within the specified directory images/ in the S3 bucket.
This operation is recursive, meaning it will remove all files and subdirectories within the specified directory.

License

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

Package detail