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
- Uploady
- UploadyConfig
- UploadPhotosConfig
- UploadPhotoConfigObject
- EVENTS
- HOME
- ALLOWED_MIME_TYPES
- getPhotoInfo
- UploadyPhotoInfo
- isExifRotated90
- PhotoUploadMetadata
- UploadyFileSuccessListener
- UploadyFileErrorListener
- UploadyFileInvalidListener
- UploadyFileExifListener
- UploadyProgressListener
- UploadyCompleteListener
- UploadyFileProgressListener
- UploadyUploadPhotosResult
- testFileTypes
- getUploadPhotosConfig
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
home
Type: HOME
homeId
loadExif
Type: boolean
configure
Parameters
config
UploadyConfigThrows 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
Fileconfig
UploadPhotoConfigObjectThrows 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 ifprospector-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
booleantrue
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
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 fromExifMap.getAll()
inblueimp-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 tobatchCreatedDate
.
UploadyFileSuccessListener
Type: Function
Parameters
file
Fileid
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
UploadyFileInvalidListener
Type: Function
Parameters
file
Fileid
string Unique ID of the entity from Prospector.
UploadyFileExifListener
Type: Function
Parameters
UploadyProgressListener
Type: Function
Parameters
progress
number 0-1 ratio.
UploadyCompleteListener
Type: Function
UploadyFileProgressListener
Type: Function
Parameters
UploadyUploadPhotosResult
Type: Object
Properties
file
File The respective photo'sFile
.error
Error? If the photo failed to upload, theError
is returned here.
testFileTypes
Resolves to a new UploadPhotosConfig
with isValid
and fileType
set on
each config object.
Parameters
uploadPhotosConfig
UploadPhotosConfigallowedMimeTypes
Array<string> (optional, defaultALLOWED_MIME_TYPES
)
Returns Promise<UploadPhotosConfig>
getUploadPhotosConfig
Associates a list of files with various metadata that is useful for processing.
Parameters
files
FileList
Returns UploadPhotosConfig