Upload, download, list, and presign objects in Amazon S3 or compatible storage.
An S3 bucket and credentials with access to the operations you use. Browser uploads also require bucket CORS rules permitting the application origin.
npm i @nodedk/s3
var s3 = require('@nodedk/s3')
var storage = s3({ region: 'eu-north-1' }, { bucket: 'example-bucket' })
async function main() {
await storage.put({ key: 'images/photo.jpg', source: './photo.jpg' })
await storage.get({ key: 'images/photo.jpg', target: './download.jpg' })
console.log(await storage.list({ prefix: 'images/' }))
await storage.remove({ key: 'images/photo.jpg' })
}
main().catch(console.error)
s3(config = {}, defaults = {})#
config is passed to the AWS S3 client. Common options are region,
endpoint, forcePathStyle, and credentials: { accessKeyId, secretAccessKey }.
Omitted region and credentials use the SDK’s provider chain. The wrapper
sets requestChecksumCalculation to 'when_required' when unset.
defaults applies to every operation. Per-call options override it. Each
operation accepts an options object, defaulting to {}, and returns a Promise.
bucket is required, either in defaults or per call.
put(options)#
Uploads a local file. Returns the AWS PutObject response.
bucket, key: destination bucket and object key.source: local file path. Content type is inferred from its extension.progress({ count, total, event }): optional callback. Counts are bytes;
event contains { loaded, total }.progressSize: optional stream buffer size in bytes when using progress.await storage.put({
key: 'images/photo.jpg',
source: './photo.jpg',
progressSize: 64 * 1024,
progress({ count, total }) {
console.log(count, total)
}
})
stream({ bucket, key, body, size, type })#
Uploads a readable stream and returns the AWS upload response.
bucket can come from factory defaults. size is an optional exact byte count
and, when supplied, must be a non-negative safe integer. type defaults to
application/octet-stream. The caller owns stream cleanup on failure.
await storage.stream({
key: 'uploads/document.pdf',
body: stream,
size: 12345,
type: 'application/pdf'
})
With size, this uses a single PutObject request. Omit size for streams
of unknown length; the AWS managed uploader buffers chunks and uses multipart
uploads when needed. Existing put({ source }) uploads are unchanged.
get(options)#
Downloads to a local file, overwriting an existing file, and resolves without
a value. Accepts bucket, key, target (local path), and the same progress
and progressSize options as put. The target’s parent directory must exist.
list({ bucket, prefix = '' })#
Returns an array of object key strings, fetching every result page.
remove({ bucket, key })#
Deletes an object and returns the AWS DeleteObject response.
presign(options)#
Creates a browser upload signature.
bucket, key: upload destination.method: 'post' (default) or 'put', case-insensitively. Other values throw.expires: validity in seconds; defaults to 60.type: optional required content type.size: optional exact byte count for POST uploads. Not used for PUT.POST returns { url, fields }; PUT returns { method: 'PUT', url, location, headers }. Both work with window.upload() from
browser.
// NodeDK action handler; storage is exposed as state.plugins.s3
module.exports = async function (state) {
var { name, type, size } = state.req.body.params
var signature = await state.plugins.s3.presign({
key: 'uploads/' + name,
method: 'put',
expires: 60,
type,
size
})
return state.jarpc({ ok: true, data: signature })
}
// Browser, after loading browser.js
var input = document.querySelector('input[type="file"]')
var file = input.files[0]
var result = await window.client('/upload', {
params: { name: file.name, type: file.type, size: file.size }
})
if (result.ok) {
var uploaded = await window.upload(result.data, file)
console.log(uploaded.url)
}
getCors({ bucket }) and putCors({ bucket, rules })#
getCors() returns the bucket’s CORS rules, or [] if none exist.
putCors() replaces them with an array of AWS CORS rule objects and returns
the AWS response. Expose Location for the browser’s POST upload helper.
await storage.putCors({
rules: [
{
AllowedOrigins: ['https://example.com'],
AllowedMethods: ['GET', 'HEAD', 'PUT', 'POST'],
AllowedHeaders: ['*'],
ExposeHeaders: ['Location']
}
]
})
console.log(await storage.getCors())
storage.client is the AWS S3 client. Its s3 property exposes the SDK’s
command constructors for operations outside the wrapper.
var command = new storage.client.s3.HeadObjectCommand({
Bucket: 'example-bucket',
Key: 'images/photo.jpg'
})
var response = await storage.client.send(command)
Created by Vidar Eldøy