s3-file-explorer v1.0.0

@vergetech/s3-file-explorer

Helper functions for exploring and updating the s3 file system.

const VergeEncryption = require('@vergetech/s3-file-explorer');
const {
  list,
  upload,
  removeFile,
  renameFile,
  createDirectory,
  removeDirectory,
  renameDirectory,
} = new VergeEncryption({
  // Required: name of the bucket to be connected to
  bucketName: 'verge-testing',

  // Any S3 SDK configuration can be passed in here
  // See: AWS.config.update (aws-sdk)
  update: {
    // These configuration inputs are required
    accessKeyId: 'xxxxxxxxxxxxxxxxxxxx',
    secretAccessKey: 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
    region: 'eu-central-1',
  },

  // (Optional) Keys containing these keywords will be filtered out e.g. when listing a directory, if 'DB_BACKUPS' is the folder name (or file name), the folder and all files within it will be filtered out before returning the result
  ignoreList: ['DB_BACKUPS'],
});

Installation

npm install --save @vergetech/s3-file-explorer

Testing

See test cases under /test/app.js.

AWS_KEY="xxxxxxxxxxxxxxxxxxxx" AWS_SECRET="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" npm run ci-test

S3 Policy

List bucket is required for removing directories, since all items within the directory will be removed first.

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Action": "s3:*",
            "Resource": "arn:aws:s3:::verge-testing/*"
        },
        {
            "Effect": "Allow",
            "Action": "s3:ListBucket",
            "Resource": "arn:aws:s3:::verge-testing"
        }
    ]
}

Examples

Listing

If the contents size is zero then the contents in question is a directory and not a file.

(async () => {
  const resFolder = await list('my_folder/');
  console.log(resFolder);

  // All items in the bucket
  const resAll = await list('');
  console.log(resAll);
})();

Files

Upload

(async () => {
  const fileToUpload = fs.readFileSync('./test/data/my_file_to_upload.png');
  const uploadBufferRes = await upload({
    // Required
    Body: fileToUpload, // Buffer object to be uploaded
    Key: 'my_folder/example_file.png', // Bucket Key

    // Example Optionals
    ACL: 'public-read',
    CacheControl: 'public, max-age=50',
    ContentType: 'image/png',
    // Any other config required, see AWS.S3.upload
  });
  console.log(uploadBufferRes);

  const data = 'data:image/png;base64,iVBORw0KGgo... some base 64 string';
  const uploadBase64Res = await upload({
    // Required
    Body: Buffer.from(data.replace(/^data:\w+\/\w+;base64,/, ''), 'base64'), // Base64 data to be uploaded
    Key: 'my_folder/example_file.png',

    // Example Optionals
    ACL: 'public-read',
    CacheControl: 'public, max-age=50',

    // Optionals for uploading a base64 string instead of a buffer object
    ContentEncoding: 'base64',
    ContentType: 'image/png',
    // Any other config required, see AWS.S3.upload
  });
  console.log(uploadBase64Res);
})();

Rename

(async () => {
  const res = await renameFile(
    'my_folder/example_file_buffer.png',
    'my_folder/example_file_buffer_renamed.png',
    'public-read',
  );
  console.log(res);
})();

Remove

(async () => {
  const res = await removeFile('my_folder/example_file_base64.png');
  console.log(res);
})();

Directories

Creation

(async () => {
  const res = await createDirectory(
    // Directory to be created on bucket
    'my_folder/my_public_folder/',
    // Optional ACL to associate with the directory
    'public-read',
  );
  console.log(res);
})();

Renaming

(async () => {
  const res = await renameDirectory(
    'my_folder/',
    'my_folder_renamed/',
    'public-read',
  );
  console.log(res);
})();

Removal

(async () => {
  const res = await removeDirectory('my_folder/');
  console.log(res);
})();

Who do I talk to?

• henco@verge.co.za

Contribution guidelines

• follow the AirBnB coding standards and linter

License

Copyright Verge Technologies