hackworks-aws

Provides functionality for managing an s3 bucket by providing an action and a payload. Also included is an async function for buffering a file to be included in the s3 payload.

Usage

Install it:

npm install @hackworks/aws

An .env.local file containing AWS/s3 authorization credentials must be present in the root of the project directory:

BUCKET_NAME=YOUR_S3_BUCKET_NAME
REGION=YOUR_AWS_REGION
ACCESS_KEY_ID=YOUR_S3_ACCESS_KEY
SECRET_ACCESS_KEY=YOUR_SECRET_S3_ACCESS_KEY

For NextJS, a next.config.js file must be present in the root of the project directory:

module.exports = {
  env: {
    BUCKET_NAME: process.env.BUCKET_NAME,
    REGION: process.env.REGION,
    ACCESS_KEY_ID: process.env.ACCESS_KEY_ID,
    SECRET_ACCESS_KEY: process.env.SECRET_ACCESS_KEY,
  },
};

Import it:

import { manageS3 } from '@hackworks/aws';

Use it:

manageS3(action, payload);

Dependencies

manageS3 has a dependency on aws-sdk in order to facilitate communication with the s3 API.

https://aws.amazon.com/sdk-for-javascript/

Details

Allows the uploading, deletion, and listing of items for the AWS s3 bucket using a specified action and payload object.

Actions:

• "upload" - Will upload the provided payload object to s3 bucket using a "name" and "file" property. Upload supports the following data formats:

  • Buffer
  • Typed Array
  • Blob
  • String
  • ReadableStream

• "delete" - Deletes an existing file in the s3 bucket by referencing the "name" property of a provided payload object.

• "list" - Lists the objects in the bucket that start with the specified prefix (i.e. retrieving folder contents)

• "listAll" - Lists all objects in the bucket.

Payload:

The payload object consists of a name and a file property for uploads:

const payload = {
  name: "myfile.txt",
  file: bufferedFile
}

Delete requires only a name, list a prefix, and listAll has no dependency on additional parameters to be passed.

Response

The response from AWS is a promise that resolves to an object.

For an upload action, the promise resolves to a "ManagedUpload" object, which will be of the following format:

{Bucket: 'string', ETag: 'string', Key: 'string', Location: 'string'}

Location is the URL of the item uploaded to s3.

For a delete action, the promise resolves to an object containing an HTTP 204 response.

For lists, this will be a data object containing a "Contents" array that lists all file objects.

Additional Features

The included fileBuffer function will buffer a provided file as an Array Buffer in preparation of uploading the file to s3.

fileBuffer is an async function and the return (the buffered file) can easily be obtained by appending await to a variable declaration.

import { fileBuffer } from '@hackworks/aws'

async someAsyncFunction() {
  const bufferedFile = await fileBuffer(file);
  return bufferedFile
}