s3#

Upload, download, list, and presign objects in Amazon S3 or compatible storage.

Requirements#

An S3 bucket and credentials with access to the operations you use. Browser uploads also require bucket CORS rules permitting the application origin.

Install#

npm i @nodedk/s3

Usage#

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 PutObject response. bucket can come from factory defaults. size is the required exact byte count and 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'
})

This method requires a known size; it does not buffer or use multipart uploads to determine the length. 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())

Native client#

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