@datagraphics/delivery

@datagraphics/delivery

@datagraphics/delivery is a way to push and pull assets to and from S3 the Data Graphics way!

Installation

@datagraphics/delivery is available via npm.

npm install -D @datagraphics/delivery

Usage

TK TK

API

Table of Contents

• Delivery
  • Parameters
  • Examples
  • uploadFile
    • Parameters
    • Examples
  • uploadFiles
    • Parameters
    • Examples
  • downloadFile
    • Parameters
    • Examples
  • downloadFiles
    • Parameters
    • Examples
• How outputs are structured
• DownloadOutput
  • Key
  • isIdentical
• UploadOutput
  • ETag
  • Key
  • isIdentical
  • isPublic
  • size
• Delivery#upload

Delivery

Extends EventEmitter

The base class for @datagraphics/delivery. Create an instance of Delivery to set an interface with S3.

Parameters

• options {bucket: string, basePath: string?, useAccelerateEndpoint: boolean?, shouldBeCached: function (path: string): boolean?}
  • options.bucket The bucket on S3 to interact with
  • options.basePath A pre-defined base path for all interactions with S3. Useful for establishing the slug or prefix of an upload. (optional, default '')
  • options.useAccelerateEndpoint If true, use the Accelerate endpoint (optional, default false)
  • options.shouldBeCached A function used to determine whether a file should receive long-lived cache headers. (optional, default defaultShouldBeCached)

Examples

const delivery = new Delivery({
 bucket: 'apps.thebignews.com',
 basePath: 'our-great-project',
});

uploadFile

Uploads a single file to S3.

Parameters

• file string The path to the file to upload
• path string Where to upload the file relative to the base path
• options {isPublic: boolean?, shouldCache: boolean?, cacheControlOverride: string?} (optional, default {})
  • options.isPublic Whether a file should be made public or not on upload (optional, default false)
  • options.shouldCache Whether a file should have cache headers applied (optional, default false)
  • options.cacheControlOverride A custom Cache-Control value that will override the built-in lookup if shouldCache is true

Examples

const result = await delivery.uploadFile(
  './data/counties.json', // path to the file on local drive
  'counties.json', // the key to give the file in S3, combined with `basePath`
  {
    isPublic: true,
  }
);

Returns Promise<UploadOutput>

uploadFiles

Upload a directory of files to S3.

Parameters

• dir string The directory to upload to S3
• options {prefix: string?, isPublic: boolean?, shouldCache: boolean?, cacheControlOverride: string?} (optional, default {})
  • options.prefix The prefix to add to the uploaded file's path (optional, default '')
  • options.isPublic Whether all files uploaded should be made public (optional, default false)
  • options.shouldCache Whether all files uploaded should get cache headers (optional, default false)
  • options.cacheControlOverride A custom Cache-Control value that will override the built-in lookup if shouldCache is true

Examples

const result = await delivery.uploadFiles(
  './dist/', // path to the directory on local drive to upload
  {
    isPublic: true,
    prefix: 'output', // the key prefix to combine with `basePath`
  }
);

downloadFile

Downloads a file from S3 to the local disk.

Parameters

• path string The path to the file to download
• dest string Where to put the file on the local disk
• options {s3ETag: string?} (optional, default {})
  • options.s3ETag If the ETag from S3 is already known, it can be provided here

Examples

const result = await delivery.downloadFile(
  'output/data.json', // key of file on S3 to download
  './downloaded/data.json', // where to download the file to the local drive
);

downloadFiles

Downloads multiple files from a prefix on S3.

Parameters

• prefix string The prefix to the directory on S3 to download from
• dir string Where to put all the files on the local disk

Examples

const result = await delivery.downloadFiles(
  'production', // the key of the directory on S3 to download from
  './downloaded/', // where to download the files to the local drive
);

How outputs are structured

These represent the output objects from Delivery's commands.

DownloadOutput

What downloadFile and downloadFiles returns.

Key

The file's path on S3.

Type: string

isIdentical

Whether the file was identical on S3 or locally and was skipped.

Type: boolean

UploadOutput

What uploadFile and uploadFiles returns.

ETag

The file's ETag.

Type: string

Key

The file's path on S3.

Type: string

isIdentical

Whether the file was identical on S3 or locally and was skipped.

Type: boolean

isPublic

This file was made public on upload.

Type: boolean

size

The size of the uploaded file in bytes.

Type: number

Delivery#upload

Type: UploadOutput

License

MIT

Changelog

[0.6.0] - 2020-06-18

Added

• Delivery can now be passed a shouldBeCached function to customize the logic that selects files to receive long-lived cache headers. This function is passed a single parameter — the input file path — and should return true or false.
• .topojson files will now get the content header of application/json thanks to a custom type addition to mime.

Changed

• Delivery now uses mime instead of mime-types. It's smaller and makes it easy to add custom types.
• Delivery now does MD5 hashing in-house — no patience for hasha's breaking changes in a minor release.
• maxAgeOverride is now cacheControlOverride and expects you to provide the full string, not just the seconds for max-age=.
• The logic for what gets a long-lived cache header is no longer entirely based on content type and instead decided by whether a file shows signs of being hashed. By default this is a regular expression check looking for an eight-character hexadecimal hash in the filename. Filenames that pass this test will receive a public, max-age=31536000, immutable value. Files that match the text/html content type will instead get an explicit no-cache header. Files that do not pass either test get nothing and are at the mercy of upstream decisions.