uploady

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

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
uploady
0.6.62 years ago5 years agoMinified + gzip package size for uploady in KB

Readme

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

-   [Parameters](#parameters)
-   [Examples](#examples)
-   [allowedMimeTypes](#allowedmimetypes)
-   [home](#home)
-   [homeId](#homeid)
-   [loadExif](#loadexif)
-   [configure](#configure)
-   [progress](#progress)
-   [uploadPhoto](#uploadphoto)
-   [uploadPhotos](#uploadphotos)
-   [Properties](#properties)
-   [Properties](#properties-1)
-   [EXIF_LOADED](#exif_loaded)
-   [FILE_INVALID](#file_invalid)
-   [FILE_PROGRESS](#file_progress)
-   [FILE_SUCCESS](#file_success)
-   [FILE_ERROR](#file_error)
-   [PROGRESS](#progress-1)
-   [COMPLETE](#complete)
-   [ACCOUNT](#account)
-   [EDITOR](#editor)
-   [PROJECT](#project)
-   [Parameters](#parameters-1)
-   [Properties](#properties-2)
-   [Parameters](#parameters-2)
-   [Properties](#properties-3)
-   [Parameters](#parameters-3)
-   [Parameters](#parameters-4)
-   [Parameters](#parameters-5)
-   [Parameters](#parameters-6)
-   [Parameters](#parameters-7)
-   [Parameters](#parameters-8)
-   [Properties](#properties-4)
-   [Parameters](#parameters-9)
-   [Parameters](#parameters-10)

Uploady

Uploady upload manager.

Parameters

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

  • 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

  • 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

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

EVENTS

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

EXIFLOADED

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

FILEINVALID

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

FILEPROGRESS

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

FILESUCCESS

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

FILEERROR

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.

ALLOWEDMIMETYPES

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

isExifRotated90

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

Parameters

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

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


Returns Promise<UploadPhotosConfig>

getUploadPhotosConfig

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

Parameters

  • files FileList

Returns
UploadPhotosConfig