Btime AWS S3 Package

AWS-S3

This package is an abstraction of the AWS S3 upload, select and deleteObject actions.

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, 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:

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' }

Testing

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

Running

1. Creating environment file

cp .env.dist .env

2. Edit environment file with your s3 credentials

3. Running with npm

npm test

Optional: Running test with coverage report using Istanbul:

npm run coverage