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

Table of Contents

• Uploady
  • Parameters
  • Examples
  • allowedMimeTypes
  • home
  • homeId
  • loadExif
  • configure
  • progress
  • uploadPhoto
  • uploadPhotos
• UploadyConfig
  • Properties
• UploadPhotosConfig
• UploadPhotoConfigObject
  • Properties
• EVENTS
  • EXIF_LOADED
  • FILE_INVALID
  • FILE_PROGRESS
  • FILE_SUCCESS
  • FILE_ERROR
  • PROGRESS
  • COMPLETE
• HOME
  • ACCOUNT
  • EDITOR
  • PROJECT
• ALLOWED_MIME_TYPES
• getPhotoInfo
  • Parameters
• UploadyPhotoInfo
  • Properties
• isExifRotated90
  • Parameters
• PhotoUploadMetadata
  • Properties
• UploadyFileSuccessListener
  • Parameters
• UploadyFileErrorListener
  • Parameters
• UploadyFileInvalidListener
  • Parameters
• UploadyFileExifListener
  • Parameters
• UploadyProgressListener
  • Parameters
• UploadyCompleteListener
• UploadyFileProgressListener
  • Parameters
• UploadyUploadPhotosResult
  • Properties
• testFileTypes
  • Parameters
• getUploadPhotosConfig
  • Parameters

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.

UploadyFileErrorListener

Type: Function

Parameters

• file File
• id string Unique ID of the entity from Prospector.
• error Error

UploadyFileInvalidListener

Type: Function

Parameters

• file File
• id string Unique ID of the entity from Prospector.

UploadyFileExifListener

Type: Function

Parameters

• file File
• id string Unique ID of the entity from Prospector.
• exif Object? Exif data from the image

UploadyProgressListener

Type: Function

Parameters

• progress number 0-1 ratio.

UploadyCompleteListener

Type: Function

UploadyFileProgressListener

Type: Function

Parameters

• file File
• id string Unique ID of the entity from Prospector.
• progress number 0-1 ratio.

UploadyUploadPhotosResult

Type: Object

Properties

• file File The respective photo's File.
• error Error? If the photo failed to upload, the Error is returned here.

testFileTypes

Resolves to a new UploadPhotosConfig with isValid and fileType set on each config object.

Parameters

• uploadPhotosConfig UploadPhotosConfig
• allowedMimeTypes Array<string> (optional, default ALLOWED_MIME_TYPES)

Returns Promise<UploadPhotosConfig>

getUploadPhotosConfig

Associates a list of files with various metadata that is useful for processing.

Parameters

• files FileList

Returns UploadPhotosConfig