Skip to content

Push and pull assets to and from S3 the Data Graphics way.

License

Notifications You must be signed in to change notification settings

datadesk/delivery

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

@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

API

Table of Contents

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