A simple, lightweight s3 client. Only 2 dependencies total.
Go to file
AJ ONeal ce7ec4d621 1.1.2 2020-12-17 14:04:02 -07:00
bin v1.0.3: add bin 2020-03-16 20:38:50 -06:00
.gitignore v1.0.2: improve docs and error messages 2020-03-16 19:58:31 -06:00
.jshintrc v1.0.0: a diet s3 client 2020-03-12 04:26:31 -06:00
.prettierrc v1.0.0: a diet s3 client 2020-03-12 04:26:31 -06:00
LICENSE v1.0.0: a diet s3 client 2020-03-12 04:26:31 -06:00
README.md add example values notes on terminology 2020-12-17 14:02:33 -07:00
index.js bugfix using manual host (minio) for bucket 2020-09-18 04:27:52 -06:00
package-lock.json 1.1.2 2020-12-17 14:04:02 -07:00
package.json 1.1.2 2020-12-17 14:04:02 -07:00
test.bin v1.0.0: a diet s3 client 2020-03-12 04:26:31 -06:00
test.js v1.0.2: improve docs and error messages 2020-03-16 19:58:31 -06:00

README.md

s3.js | a Root project

Minimalist S3 client
(for AWS, Minio, Digital Ocean Spaces, etc)

A lightweight alternative to the S3 SDK that uses only @root/request and aws4.

  • set()
  • get()
  • head()
  • delete()
  • sign()

Download a file from S3

s3.get({
    accessKeyId,        // 'AKIAXXXXXXXXXXXXXXXX'
    secretAccessKey,    // 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
    region,             // 'us-east-2'
    bucket,             // 'bucket-name'
    prefix,             // 'my-prefix/' (optional)
    key                 // 'data/stats.csv' (omits prefix, if any)
});

Upload a new file to S3

s3.set({
    accessKeyId,
    secretAccessKey,
    region,
    bucket,
    prefix,
    key,
    body,               // new Buffer("hello, world")
                        // or fs.createReadStream("./file.txt")

    size                // fs.stat("./file.txt").size (required for streams)
});

Return signed URL without fetching.

s3.sign({
    method: 'get',
    accessKeyId,
    secretAccessKey,
    region,
    bucket,
    prefix,
    key
});

A note on S3 terminology

bucket most similar to what most people think of as a "folder"
MUST NOT contain a slash /
key
("object key")
most similar to a "file name"
may contain "/"s as part of the name
MUST NOT BEGIN with a slash /
prefix an informal term, refers to "file path"
what the AWS console uses for created virtual folder-like views and searches
MUST END with a slash /

This library provides prefix (of key) for convenience.

s3://bucket-name/long/prefix/data/stats.csv can be represented equally well by any of the following:

(no prefix)

{
    "bucket": "bucket-name",
    "prefix": "",
    "key": "long/prefix/data/stats.csv"
}

(with long prefix)

{
    "bucket": "bucket-name",
    "prefix": "long/prefix/data/",
    "key": "stats.csv"
}

(with short prefix)

{
    "bucket": "bucket-name",
    "prefix": "long/",
    "key": "prefix/data/stats.csv"
}

Troubleshooting

If the body is a stream then size must be set to fs.statSync(filePath).size, or the request will fail:

501
<Code>NotImplemented</Code><Message>A header you provided implies functionality that is not implemented</Message>