uploady
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
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: HOMEhomeId
Type: (string \| undefined)loadExif
Type: booleanconfigure
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
Fileconfig
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: ObjectProperties
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.
UploadPhotosConfig
Type: Map<File, UploadPhotoConfigObject>UploadPhotoConfigObject
Type: ObjectProperties
this photo.
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 ofUploady
. To listen to a particular event,
call addEventListener
.Type: string
EXIFLOADED
Dispatched when exif data is available for a file. See UploadyFileExifListenerFILEINVALID
Dispatched when an individual file is of an invalid type. See UploadyFileInvalidListenerFILEPROGRESS
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 ExifOrientation
).Parameters
file
File
Returns Promise<UploadyPhotoInfo>
UploadyPhotoInfo
Type: ObjectProperties
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: ObjectProperties
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: FunctionParameters
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: FunctionParameters
UploadyFileInvalidListener
Type: FunctionParameters
file
Fileid
string Unique ID of the entity from Prospector.
UploadyFileExifListener
Type: FunctionParameters
UploadyProgressListener
Type: FunctionParameters
progress
number 0-1 ratio.
UploadyCompleteListener
Type: FunctionUploadyFileProgressListener
Type: FunctionParameters
UploadyUploadPhotosResult
Type: ObjectProperties
file
File The respective photo'sFile
.error
Error? If the photo failed to upload, theError
is
returned here.
testFileTypes
Resolves to a newUploadPhotosConfig
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