attache-upload.js
Upload files to your attache server.
Example
import {upload, presign} from 'attache-upload'
presign(presign_url)
.then((presignResponse) => {
return upload(presignResponse, fileObject)
})
.then((uploadResponse) => {
})
.catch((err) => {
})
Install
$ npm install --save attache-upload
API Documentation
presign(options)
presign_url
- required, a URL to perform a presign request.token
- optional, X-CSRF-Token
value.
On success, this request will return:
url
- the URL to the /upload
API of your attache serveuuid
- a uuid stringexpiration
- a unix timestamp of a future timehmac
- the HMAC-SHA1
of your SECRET_KEY
presign(presign_url, token)
.then((presignResponse) => {
})
upload(options)
presignResponse
- required, response object passed in from presign request.fileObject
- required.
An object containing a uid and file
property.
We use this uid
as a reference to this object's XHR request, which can then be aborted at a later stage using abortXHRRequest('uid')
{
uid: 'some_generated_uid',
file: FILE
}
onProgress
- optional, onProgress
function.
On success, this request will return:
path
- a unique path for the uploaded filecontent_type
geometry
bytes
function customProgressHandler (progressEvent, file) {
console.log('Uploading ' + file.name + ' @ ' + progressEvent.percent + '%')
}
presign(presign_url)
.then((presignResponse) => {
return upload(presignResponse, fileObject, customProgressHandler)
})
.then((uploadResponse) => {
})
getXHRRequests()
To access all existing XHR requests use getXHRRequests()
.
import {getXHRRequests} from 'attache-upload'
getXHRRequests()
abortXHRRequest(String)
To abort an existing XHR requests use destroyXHRRequest()
passing in the id of the request.
import {getXHRRequests, abortXHRRequest} from 'attache-upload'
getXHRRequests()
abortXHRRequest('some_uid')
getXHRRequests()
Error handling
Both presign
the upload
methods will return a custom error objects if either promise
is rejected.
The XHR requests for each method will return a custom responseStatus
error message if the response status is not between 200
and 300
.
This allows us to check for specific errors in our upload process.
The custom error objects look like this:
{
error: {original error object},
message: 'Not Authorised'
name: 'uploadRequest'
}
The 3 custom error names we cater for are:
presignRequest
- Rejected presignuploadRequest
- Rejected uploadresponseStatus
- A failing XHR response status
All other errors should be left to bubble up and logged to the console.
Example
import {upload, presign} from 'attache-upload'
presign(presign_url)
.then((presignResponse) => {
return upload(presignResponse, fileObject)
})
.then((uploadResponse) => {
return doSomethingWithResponse(uploadResponse)
})
.catch((err) => {
const {name} = err
if (name === 'presignRequest' || name === 'uploadRequest' || name === 'responseStatus') {
doSomethingWithErrorMessage(err)
} else {
console.error(err)
throw err
}
})
Generate a uid
for your file object
Some files may have the same name, so it would be great if we had a unique way of identifying them and their XHR request.
Creating a uid
for your file object is as simple as:
import uid from 'uid'
function generateUniqueID (name) {
return uid(10) + '_' + name
}
const myUID = generateUniqueID(file.name)
Development
Build
Compile src
scripts to lib
:
$ npm run build
Tests
To run the test suite, first install the dependencies, then run npm test
:
$ npm install
$ npm test