README.md

Btime AWS S3 Package

AWS-S3

This package is an abstraction of the AWS S3 actions throught AWS SDK and S3-URL-Exists package.

The actions available are:

• Object:

  • upload
  • select
  • deleteObject

• Bucket:

  • createBucket
  • deleteBucket

Table of Contents

1. Install with NPM
2. Usage
   1. Actions
      1. Upload
      2. Select
      3. DeleteObject
      4. CreateBucket
      5. DeleteBucket
3. Testing
   1. Setup
   2. Running

Install with npm

npm install @btime/aws-s3 --save

Usage

When requiring aws-s3 package, you must have your aws s3 credentials to use as parameter like example below:

const options = {
  S3_REGION: 's3-region-here',
  S3_KEY_SECRET: 's3-key-secret-here',
  S3_KEY_ID: 's3-key-id-here',
  S3_BUCKET: 's3-bucket-here'
}
const S3 = require('@btime/aws-s3')(options)

Note: this is an example, we recomend you get options using dotenv to set env variables, an example can be find in our Testing section.

Aws-s3 package returns an AWS.S3() instance along with upload, select, deleteObject functions that are Promisses, you can freely use AWS.S3 instance like you want, but our overwriten functions should be used like:

Actions

Upload

S3.upload(payload)
  .then(response => {
    /* HANDLE RESPONSE */
  })
  .catch(err => {
    /* HANDLE ERROR */
  })

Payload example:

const payload = {
  key: 'optionalKey',
  file: 'requiredBuffer',
  fileExtension: 'optionalExetension',
  contentType: 'optionalMimeType'
}

Response example:

{
  ETag: '"123x321XX"',
  Location: 'https://s3-sa-east-1.amazonaws.com/bucket-test/keyExample',
  Key: 'keyExample',
  Bucket: 'bucket-test'
}

Select

const payload = defineSelectPayload(params)
S3.select(payload)
  .then(response => {
    /* HANDLE RESPONSE */
  })
  .catch(err => {
    /* HANDLE ERROR */
  })

Payload example:

const payload = {
  key: 'requiredKey'
}

Response example:

{ status: true, url: 'https://s3-sa-east-1.amazonaws.com/bucket-test/keyExample' }

DeleteObject

const payload = defineDeleteObjectPayload(params)
S3.deleteObject(payload)
  .then(response => {
    /* HANDLE RESPONSE */
  })
  .catch(err => {
    /* HANDLE ERROR */
  })

Payload example:

const payload = {
  key: 'requiredKey'
}

Response example:

{ Key: 'keyExample' }

CreateBucket

S3.createBucket(payload)
  .then(response => {
    /* HANDLE RESPONSE */
  })
  .catch(err => {
    /* HANDLE ERROR */
  })

Payload example:

const payload = {
  name: 'bucket-name-here'
}

Response example:

{
  Location: 'bucket-name-here.s3.amazonaws.com/'
}

DeleteBucket

S3.deleteBucket(payload)
  .then(response => {
    /* HANDLE RESPONSE */
  })
  .catch(err => {
    /* HANDLE ERROR */
  })

Payload example:

const payload = {
  name: 'bucket-name-here'
}

Response example:

{}

Testing

Tests are coverage by Mocha and Chai, also, all inputs are validate by Joi.

Setup

1. Creating environment file

cp .env.dist .env

2. Edit environment file with your s3 credentials

Running

3. Running with npm

npm test

Optional: Running test with coverage report using Istanbul:

npm run coverage