@sprdv/scube v0.1.2

Scube

Scube provides an expressive, fluent interface to Amazon's simple storage service (S3).

Installation

Scube can be installed using npm or yarn.

npm install @sprdv/scube

Usage

Each Scube represents an AWS.S3 instance:

import { Scube } from '@sprdv/scube';

const scube = new Scube({
    accessKey: process.env.AWS_ACCESS_KEY,
    secretKey: process.env.AWS_SECRET_KEY
});

A Scube is the base class in this library: operations like creating a bucket or uploading a file are always associated to it.

If you want to perform actions which are not available in this library, you can get the S3 instance the following way:

const s3 = scube.s3();

Documentation

Bucket

To upload your data (photos, videos, documents, etc.) to Amazon S3, you must first create an S3 bucket in one of the AWS Regions. You can then upload any number of objects to the bucket.

Creating buckets

When you create a bucket, you provide a name and the AWS Region where you want to create the bucket:

const bucket = await scube.newBucket('my-cool-bucket', 'eu-central-1').create();

For information about naming buckets, see Rules for Bucket Naming.

Access control lists

Specify the canned ACL to apply to the bucket:

const bucket = await scube.newBucket('my-cool-bucket', 'eu-central-1')
    .acl('public-read')
    .create();

Custom location

If you're using a specific URL to access your files (such as https://xyz.cloudfront.net when using CloudFront), you can assign it to the bucket:

const bucket = await scube.newBucket('my-cool-bucket', 'eu-central-1')
    .location('https://xyz.cloudfront.net')
    .create();

Checking bucket status

Check if a bucket exists:

const exists = await bucket.exists();

Listing buckets

const buckets = await scube.buckets();

Deleting buckets

Delete a bucket by instance:

await bucket.delete();

Delete a bucket by name:

await scube.bucket('my-cool-bucket').delete();

Note that you should empty the bucket before deleting it.

File

Amazon S3 enables you to store, retrieve, and delete files.

Creating files

When you create a file, you provide an unique key and your file's body (buffer):

import { promises as fs } from 'fs';

const body = await fs.readFile('./my/files/dog.jpg');

const file = await bucket.newFile('path/to/folder/dog.jpg')
    .body(body)
    .create();

You can then retrieve your file's location and store it for later use:

const location = file.location();

Access control lists

Specify the canned ACL to apply to the file:

const file = await bucket.newFile('path/to/folder/dog.jpg')
    .acl('public-read')
    .create();

Content-Type

Specify a standard MIME type describing the format of the contents:

const file = await bucket.newFile('path/to/folder/dog.jpg')
    .type('image/jpeg')
    .create();

Cache-Control

Specify caching behavior along the request/reply chain:

const file = await bucket.newFile('path/to/folder/dog.jpg')
    .cache('max-age=60')
    .create();

Metadata

Specify a map of metadata to store with the object in S3:

const file = await bucket.newFile('path/to/folder/dog.jpg')
    .metadata({ hello: 'world' })
    .create();

Checking file status

Check if a file exists:

const exists = await file.exists();

Get a file's metadata:

const metadata = await file.head();

Listing files

const files = await bucket.files();

Deleting files

Delete a file by instance:

await file.delete();

Delete a file by key:

await bucket.file('my-cool-file.txt').delete();

Or even:

await scube.bucket('my-cool-bucket').file('my-cool-file.txt').delete();

Getting S3 Objects

You can get the underlying S3 Object of any file:

const object = await file.asObject();