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
  • progress
  • prospectorToken
  • uploadPhoto
  • uploadPhotos
  • _fileExifListener
• UploadyConfig
  • Properties
• UploadPhotosConfig
• UploadPhotoConfigObject
  • Properties
• EVENTS
  • EXIF_LOADED
  • FILE_INVALID
  • FILE_PROGRESS
  • FILE_SUCCESS
  • FILE_ERROR
  • PROGRESS
  • COMPLETE
• HOME
  • ACCOUNT
  • EDITOR
  • PROJECT
• UploadyFileExifListener
  • Parameters
• UploadyProgressListener
  • Parameters
• UploadyCompleteListener
• UploadyFileProgressListener
  • Parameters
• UploadyFileErrorListener
  • Parameters
• UploadyFileInvalidListener
  • Parameters
• UploadyFileSuccessListener
  • Parameters
• UploadyUploadPhotosResult
  • Properties
• 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',
  prospectorToken: someProspectorToken
})
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.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',
  prospectorToken: someProspectorToken
})

// 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)
})

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.
import Uploady, { getUploadPhotosConfig } from '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)
// ...

allowedMimeTypes

Type: Array<string>

home

Type: HOME

homeId

Type: string

loadExif

Type: boolean

progress

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

Type: number

prospectorToken

Sets the prospector token currently in use by Uploady.

Parameters

• token

uploadPhoto

Uploads a single photo.

Parameters

• photo File

• config UploadPhotoConfigObject

• Throws Error if no photo was provided.

Returns Promise<File>

uploadPhotos

Uploads a batch of photos.

Parameters

• photos (FileList | UploadPhotosConfig) See getUploadPhotosConfig.

• Throws Error if photos is empty or not provided.

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

_fileExifListener

Parameters

• file File
• id string
• exif Object?

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.
• prospectorToken string Token to use in communication with prospector.

UploadPhotosConfig

Type: Map<File, UploadPhotoConfigObject>

UploadPhotoConfigObject

Type: Object

Properties

• id string ID of the photo. Should be unique.

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 a 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.

Default set of valid upload types (for photos).

Type: Array<string>

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.

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.

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.

UploadyUploadPhotosResult

Type: Object

Properties

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

getUploadPhotosConfig

Associates a list of files with respective UUIDs.

Parameters

• files FileList

Returns UploadPhotosConfig