Uploady NPM | npm.io

`uploady`

Utilities for the file upload process (primarily photos) as it relates to Prospector and the WHCC system.

Install

npm install --save uploady prospector-js-sdk superagent

Usage

Uploady

Uploady upload manager.

Parameters

config UploadyConfig

Examples

Using event listeners.

import Uploady, { EVENTS, HOME } from 'uploady'

const uploady = new Uploady({
  home: HOME.PROJECT,
  homeId: 'foo-project-id',
  prospectorBaseUrl: 'https://prospector-url/api/v1'
})
uploady.addEventListener(EVENTS.FILE_PROGRESS, (file, id, progress) => {
  console.log(`${file.name} (${id}) progress: ${progress}`)
})
uploady.addEventListener(EVENTS.FILE_SUCCESS, (file, id) => {
  console.log(`${file.name} (${id}) success!`)
})
uploady.addEventListener(EVENTS.FILE_ERROR, (file, id, err) => {
  console.error(`${file.name} (${id}) error: ${err}`)
})
uploady.addEventListener(EVENTS.FILE_INVALID, (file, id, err) => {
  console.error(`${file.name} (${id}) error: ${err}`)
})
uploady.addEventListener(EVENTS.PROGRESS, progress => {
  console.log(`Overall Uploady progress: ${progress}`)
})
uploady.addEventListener(EVENTS.COMPLETE, () => {
  console.log('Uploady complete!')
})

uploady.uploadPhotos(someFileList)

Using async/await.

import Uploady, { HOME } from 'uploady'

const uploady = new Uploady({
  home: HOME.EDITOR,
  homeId: 'foo-editor-id',
  prospectorBaseUrl: 'https://prospector-url/api/v1'
})

// You can still attach event listeners if you like.

// Don't need a `try`/`catch` because this `Promise` should
//  always resolve.
const results = await uploady.uploadPhotos(someFileList)

console.log('Uploady complete', results)

results.forEach(results, ({ url, error }) => {
  if (error) console.error(`Upload failed for ${url}`, error)
})

Deferred configuration

// Not everything needs to be provided upon construction.
const uploady = new Uploady({
  prospectorBaseUrl: 'https://prospector-url/api/v1'
})

// ...

// You can wait to set things until it makes sense for you.
uploady.home = HOME.EDITOR
uploady.homeId = 'foo-editor-id'
// or
uploady.configure({
  home: HOME.EDITOR,
  homeId: 'foo-editor-id',
})

// Just make sure you do it before you try to upload!
uploady.uploadPhotos(someFileList)

// You can also change things after uploading has started, but be careful:
//  changing something while an upload is in progress could have strange results!
uploady.homeId = 'different-editor'

Using upload photos config

// If you need to know the ID of the entities returned from Prospector when
//  the file is given a home, you can process your FileList into a config
//  that you can inspect before handing off to Uploady.

const uploadPhotosConfig = getUploadPhotosConfig(someFileList)

// Inspect those IDs.
for (const [file, { id }] of uploadPhotosConfig) {
  console.log(`The ID of ${file.name} is ${id}`)
}

// Then hand the config off to Uploady.
const results = await uploady.uploadPhotos(uploadPhotosConfig)
// ...

Testing the file types prior to upload

const uploadPhotosConfig = await testFileTypes(
  getUploadPhotosConfig(someFileList),
  // Optional second parameter allows you to override the defaults
  // Mime types default to png and jpeg
  [ 'image/jpeg', 'image/png', 'application/json' ]
)

for (const [file, { id, isValid }] of uploadPhotosConfig) {
  console.log(`${file.name} isValid? ${isValid}`)
}

// Uploady will ignore any files marked as isValid === false
uploady.uploadPhotos(uploadPhotosConfig)

Upload batch information

// The configuration returned from `getUploadPhotosConfig` also has some
//  useful information for sorting: `batchCreatedDate`, the Unix timestamp
//  of when that upload batch was processed; and `batchIndex`, the index of
//  that photo's place in the batch.

const uploadPhotosConfig = getUploadPhotosConfig(someFileList)

for (const [file, { batchCreatedDate, batchIndex }] of uploadPhotosConfig) {
  console.log(`${file.name} is part of batch ${batchCreatedDate} with index ${batchIndex}`)
}

// Uploady will ignore any files marked as isValid === false
const results = uploady.uploadPhotos(uploadPhotosConfig)
// ...

allowedMimeTypes

Type: Array<string>

home

Type: HOME

homeId

Type: (string | undefined)

loadExif

Type: boolean

configure

Parameters

config UploadyConfig

Throws AssertionError if config is not provided

progress

A ratio 0-1 of the overall progress of the current batch of uploads.

Type: number

uploadPhoto

Uploads a single photo.

Parameters

photo File
config UploadPhotoConfigObject

Throws AssertionError if no photo was provided.
Throws AssertionError if Uploady is not properly configured.

Returns Promise<File>

uploadPhotos

Uploads a batch of photos.

Parameters

photos (FileList | UploadPhotosConfig) See getUploadPhotosConfig.

Throws AssertionError if Uploady is not properly configured.

Returns Promise<Array<UploadyUploadPhotosResult>> Resolves when all photos are done being processed – regardless of whether or not they succeeded. This Promise does not reject.

UploadyConfig

Type: Object

Properties

home HOME? Default value: HOME.PROJECT.
homeId string? ID of the resource that the files will call home – project, editor, account, etc.
loadExif boolean? Default value: true.
prospectorBaseUrl string? Required if prospector-js-sdk is not already configured.
allowedMimeTypes Array<string>? List of valid mime types.

UploadPhotosConfig

Type: Map<File, UploadPhotoConfigObject>

UploadPhotoConfigObject

Type: Object

Properties

allowedMimeTypes Array<string>? Mime types which are valid for this photo.
fileType {ext: string, mime: string}?? Detected MIME type and extension.
id string ID of the photo. Should be unique.
isValid boolean true if the photo's file type is valid; false if not; undefined if it has not been checked.
uploadMetadata PhotoUploadMetadata

EVENTS

Events dispatched to instances of Uploady. To listen to a particular event, call addEventListener.

Type: string

EXIF_LOADED

Dispatched when exif data is available for a file. See UploadyFileExifListener

FILE_INVALID

Dispatched when an individual file is of an invalid type. See UploadyFileInvalidListener

FILE_PROGRESS

Dispatched for progress events for individual files being processed. See UploadyFileProgressListener for the listener contract.

FILE_SUCCESS

Dispatched when an individual file has been successfully processed. See UploadyFileSuccessListener for the listener contract.

FILE_ERROR

Dispatched when an individual file encounters an error during processing. See UploadyFileErrorListener for the listener contract.

PROGRESS

Dispatched whenever an individual file finishes processing – regardless of whether or not that processing was successful. See UploadyProgressListener for the listener contract.

COMPLETE

Dispatched when processing of all files is complete – regardless of whether or not they were successful. See UploadyCompleteListener for the listener contract.

HOME

Enum to represent the types of "homes" in which photos will be added.

Type: string

ACCOUNT

(NOT YET SUPPORTED) The resource will be added to an account.

EDITOR

The resource will be added to an editor.

PROJECT

The resource will be added to a project.

ALLOWED_MIME_TYPES

Default set of valid upload types (for photos).

Type: ["image/png", "image/jpeg"]

getPhotoInfo

Loads the file to get its Exif data and dimensions (relative to Exif Orientation).

Parameters

file File

Returns Promise<UploadyPhotoInfo>

UploadyPhotoInfo

Type: Object

Properties

exif Object<string>?
height number
width number

isExifRotated90

Determines whether or not the provided Exif data indicates that the file must be rotated 90 degrees.

Parameters

exif Object<(string | number)> Exif data, either in raw form or mapped to string values from ExifMap.getAll() in blueimp-load-image.

Returns boolean

PhotoUploadMetadata

Type: Object

Properties

batchCreatedDate number Unix timestamp of when the photo's batch began uploading.
batchIndex number Index of the photo in its batch.
updatedDate number? Unix timestamp of when the photo was re-uploaded. NOTE: this is currently identical to batchCreatedDate.

UploadyFileSuccessListener

Type: Function

Parameters

file File
id string Unique ID of the entity from Prospector.
entity Object Object returned from Prospector when the file is added to its home.