add example values notes on terminology

This commit is contained in:
AJ ONeal 2020-12-17 13:50:30 -07:00
parent c95f188d61
commit ac1c6e6d59
1 changed files with 60 additions and 13 deletions

View File

@ -1,8 +1,9 @@
# [s3.js](https://git.rootprojects.org/root/s3.js) | a [Root](https://rootprojects.org) project # [s3.js](https://git.rootprojects.org/root/s3.js) | a [Root](https://rootprojects.org) project
> Minimalist S3 client > Minimalist S3 client \
> (for AWS, Minio, Digital Ocean Spaces, etc)
A lightweight alternative to the s3 SDK that uses only @root/request and aws4. A lightweight alternative to the S3 SDK that uses only @root/request and aws4.
- set() - set()
- get() - get()
@ -10,20 +11,20 @@ A lightweight alternative to the s3 SDK that uses only @root/request and aws4.
- delete() - delete()
- sign() - sign()
Download a file from S3 ### Download a file from S3
```js ```js
s3.get({ s3.get({
accessKeyId, accessKeyId, // 'AKIAXXXXXXXXXXXXXXXX'
secretAccessKey, secretAccessKey, // 'xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'
region, region, // 'us-east-2'
bucket, bucket, // 'bucket-name'
prefix, prefix, // 'my-prefix/' (optional)
key key // 'data/stats.csv' (omits prefix, if any)
}); });
``` ```
Upload a new file to S3 ### Upload a new file to S3
```js ```js
s3.set({ s3.set({
@ -33,12 +34,14 @@ s3.set({
bucket, bucket,
prefix, prefix,
key, key,
body, body, // new Buffer("hello, world")
size // or fs.createReadStream("./file.txt")
size // fs.stat("./file.txt").size (required for streams)
}); });
``` ```
Return signed URL without fetching. ### Return signed URL without fetching.
```js ```js
s3.sign({ s3.sign({
@ -52,6 +55,50 @@ s3.sign({
}); });
``` ```
### A note on S3 terminology
| | |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `bucket` | most similar to what most people think of as a "**folder**"<br>**MUST NOT** contain a slash `/` |
| `key`<br>("object key") | most similar to a "**file name**"<br>may contain "**/**"s as part of the name<br>**MUST NOT BEGIN** with a slash `/` |
| `prefix` | an informal term, refers to "**file path**"<br>what the AWS console uses for created virtual folder-like views and searches<br>**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)
```json
{
"bucket": "bucket-name",
"prefix": "",
"key": "long/prefix/data/stats.csv"
}
```
(with long prefix)
```json
{
"bucket": "bucket-name",
"prefix": "long/prefix/data/",
"key": "stats.csv"
}
```
(with short prefix)
```json
{
"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: If the body is a stream then `size` must be set to `fs.statSync(filePath).size`, or the request will fail:
``` ```