What is tus-js-client?
The tus-js-client is a JavaScript client for the tus resumable upload protocol. It allows you to upload large files to a server in a reliable and resumable manner, meaning that if the upload is interrupted, it can be resumed from where it left off.
What are tus-js-client's main functionalities?
Resumable File Upload
This feature allows you to upload a file to a server in a resumable manner. The upload can be paused and resumed, and it will automatically retry if it fails.
const tus = require('tus-js-client');
const file = document.querySelector('input[type="file"]').files[0];
const upload = new tus.Upload(file, {
endpoint: 'https://tusd.tusdemo.net/files/',
retryDelays: [0, 1000, 3000, 5000],
metadata: {
filename: file.name,
filetype: file.type
},
onError: function(error) {
console.log('Failed because: ' + error);
},
onProgress: function(bytesUploaded, bytesTotal) {
const percentage = (bytesUploaded / bytesTotal * 100).toFixed(2);
console.log(bytesUploaded, bytesTotal, percentage + '%');
},
onSuccess: function() {
console.log('Download %s from %s', upload.file.name, upload.url);
}
});
upload.start();
Custom Headers
This feature allows you to add custom headers to the upload request, such as an Authorization header for authentication purposes.
const tus = require('tus-js-client');
const file = document.querySelector('input[type="file"]').files[0];
const upload = new tus.Upload(file, {
endpoint: 'https://tusd.tusdemo.net/files/',
headers: {
'Authorization': 'Bearer YOUR_ACCESS_TOKEN'
},
onError: function(error) {
console.log('Failed because: ' + error);
},
onSuccess: function() {
console.log('Download %s from %s', upload.file.name, upload.url);
}
});
upload.start();
Chunked Uploads
This feature allows you to upload files in chunks, which can be useful for large files. You can specify the chunk size, and the upload will be split into multiple smaller requests.
const tus = require('tus-js-client');
const file = document.querySelector('input[type="file"]').files[0];
const upload = new tus.Upload(file, {
endpoint: 'https://tusd.tusdemo.net/files/',
chunkSize: 5242880, // 5MB
onError: function(error) {
console.log('Failed because: ' + error);
},
onSuccess: function() {
console.log('Download %s from %s', upload.file.name, upload.url);
}
});
upload.start();
Other packages similar to tus-js-client
uppy
Uppy is a sleek, modular file uploader that integrates well with various backends. It supports resumable uploads using the tus protocol, just like tus-js-client, but also offers additional features like drag-and-drop, webcam support, and more.
fine-uploader
Fine Uploader is a dependency-free JavaScript library for file uploading. It supports chunked and resumable uploads, similar to tus-js-client, but also provides a wide range of customization options and a comprehensive set of features for handling file uploads.
resumablejs
Resumable.js is a JavaScript library providing multiple simultaneous, stable, and resumable uploads via the HTML5 File API. It is similar to tus-js-client in that it supports resumable uploads, but it uses a different protocol and has a different set of features.
tus-js-client
A pure JavaScript client for the tus resumable upload protocol.
Example
input.addEventListener("change", function(e) {
var file = e.target.files[0]
var upload = new tus.Upload(file, {
endpoint: "http://localhost:1080/files/",
onError: function(error) {
console.log("Failed because: " + error)
},
onProgress: function(bytesUploaded, bytesTotal) {
var percentage = (bytesUploaded / bytesTotal * 100).toFixed(2)
console.log(bytesUploaded, bytesTotal, percentage + "%")
},
onSuccess: function() {
console.log("Download %s from %s", upload.file.name, upload.url)
}
})
upload.start()
})
Installation
The sources are compiled into a UMD
(dist/tus.js
) which can be loaded using different approaches:
- Embed using a script tag:
<script src="dist/tus.js"></script>
and access
the tus methods using the tus
property in window
- Install from NPM:
npm install tus-js-client
and load using browserify:
var tus = require("tus-js-client")
- Define using AMD:
define("alpha", ["dist/tus.js"], function(tus) {})
Browser support
We use localStorage, XMLHttpRequest2, the File API and Blob API. About 85% of
today's users should be able to use this software, calculated using
iwanttouse.com.
Internals
Once a new file should be uploaded the client will create a new upload resource
on the server using a POST
request. A successful response will contain a
Location
header pointing to the upload URL. This URL will be used to transfer
the file to the server using one or multiple PATCH
requests.
In addition tus-js-client will generate a unique fingerprint for every file and
store it and the upload URL using the Web Storage API. If the upload is
interrupted or aborted manually, the client is able to resume the upload by
retrieving the upload URL using the fingerprint. The client is even able to
resume after you close your browser or shut down your device. Now the client can
continue to send PATCH
requests to the server until the upload is finished.
Documentation
tus.isSupported
A boolean indicating whether the current browser has the features necessary to
use tus-js-client. This can be used to test support and warn the user.
tus.defaultOptions
A object containing the default options used when creating a new upload:
endpoint = ""
: a URL which will be used to create new uploadsfingerprint
: a function used to generate a unique string from a
corresponding File object. This used to store the URL for an upload to resume.
This option is only used if the resume
flag is set to true.resume = true
: a boolean indicating whether the client should attempt to
resume the upload if the upload has been started in the past. This includes
storing the file's fingerprint. Use false
to force an entire reupload.onProgress = null
: a function that will be called each time progress
information is available. The arguments will be bytesSent
and bytesTotal
.onChunkComplete = null
: a function that will be called each time a chunk
has been successfully uploaded. The arguments will be chunkSize
,
bytesAccepted
, bytesTotal
.onSuccess = null
: a function called when the upload finished successfully.onError = null
: a function called once an error appears. The arguments will
be an Error instance.headers = {}
: an object with custom header values used in all requests.withCredentials = false
: a boolean which is be used as the value for
withCredentials
in all XMLHttpRequests to use Cookies in requests. The
remote server must accept CORS and credentials.chunkSize = Infinity
: a number indicating the maximum size of a chunk
uploaded in a single requestmetadata = {}
: an object with string values used as additional meta data
which will be passed along to the server when (and only when) creating a new
upload. Can be used for filenames, file types etc.
new tus.Upload(file, options)
Create a new tus.Upload object. The upload will not be started automatically,
use start
to do so.
The file
argument should be an instance of File
or Blob
. The options
argument will be merged deeply with tus.defaultOptions
.
tus.Upload#options
The options
argument used in the constructor merged deeply with
tus.defaultOptions
.
tus.Upload#file
The file
argument used in the constructor.
tus.Upload#url
The URL used to upload the file. Leave it set to null
and the client will
create a new upload and set this property to the new upload URL.
You may supply your own URL using this property and the client will try to
resume using this URL.
tus.Upload#start()
Start or resume the upload using the specified file. If no file
property is
available the error handler will be called. If you supplied your own URL using
the url
property the client will try to resume using this URL.
If not, the client will look up if the file has been (fully or partially)
uploaded and tries to resume.
If no upload can be resume it will create a new upload using the supplied
endpoint
option.
tus.Upload#abort()
Abort the currently running upload request and don't continue. You can resume
the upload by calling the start
method again.
Difference between onProgress and onChunkComplete
When configuring a new uploader, the onProgress
and onChunkComplete
callbacks are available. While they may seem to be equal based on their
naming and the arguments, they provide different information in reality.
Progress events are emitted using the onProgress
option and provide numbers
about how must data has been sent to the server. However, this data may not
have been received or accepted by the endpoint. Imagine a network outage where
the browser reports to have successfully sent 100 bytes, but none of them ever
reach the backend. In order to provide reliable information about whether the
chunks have been accepted by the server, onChunkComplete
is only invoked if
we have evidence that the remote endpoint has received and accepted the
uploaded bytes. When consuming this functionality, the chunkSize
option is
from high importance since the callback will and invoked if an entire chunk
has been uploaded.
Building
npm install
npm run build
npm run dist
npm run watch
Testing
Tests are implemented using Jasmine and can be found in the test/
directory.
In order to run the tests, open test/SpecRunner.html
in a browser and you
should see a visual representation of the test results. No web server is
required, you can open SpecRunner.html
using the file:///
protocol.
In addition, if do not want to download the repository, you can run the latest
tests online by visiting https://rawgit.com/tus/tus-js-client/master/test/SpecRunner.html.
Tests can also be run on SauceLabs' cloud infrastructure using npm test
.
Before using this command, you have to set up your SauceLabs account by filling
the SAUCE_USERNAME
and SAUCE_ACCESS_KEY
variables else the command will fail.
License
MIT