---

JS File Downloader

🌟Please remember to star this github repo if you like it. Thank you! ❤️

Introduction

JS File Downloader is a simple no dependency library you will be able to download file from browser and show downloading status.

• Install
• Basic usage
• Options
  • process, check download status
  • onloadstart
  • headers
  • filename
  • timeout
  • autoStart
  • forceDesktopMode
  • withCredentials
  • method, GET/POST/...
  • nameCallback, custom at runtime
  • contentType
  • nativeFallbackOnError
  • body, of the request
  • contentTypeDetermination
  • customFileSignatures
• abort, to stop pending downloading request

Browser Compatibility

JS File Downloader supports all browsers that are [ES5-compliant] (http://kangax.github.io/compat-table/es5/) (IE8 and below are not supported).

---

Installing with package manager

With a package manager (recommended):

1npm install js-file-downloader --save 

Basic usage

1
2import JsFileDownloader from 'js-file-downloader';
3
4const fileUrl = 'http://...';
5
6new JsFileDownloader({ 
7    url: fileUrl
8  })
9  .then(function () {
10    // Called when download ended
11  })
12  .catch(function (error) {
13    // Called when an error occurred
14  });
15  

---

Use without a package manager

Download this library from https://github.com/AleeeKoi/js-file-downloader/releases

1<script src="/path/to/js-file-downloader.min.js"></script>
2<script>
3  // Then somewhere in your code
4  new jsFileDownloader({ url: 'https://cdn.apedesign.net/github/logo.png' })
5    .then(function () {
6      // Called when download ended
7    })
8    .catch(function (error) {
9      // Called when an error occurred
10    });
11</script>

---

Options:

process (for checking download status)

A function to call every time a process event is called. Function receive an Event Object as input.

1
2function process (event) {
3  if (!event.lengthComputable) return; // guard
4  var downloadingPercentage = Math.floor(event.loaded / event.total * 100);
5  // what to do ...
6};
7
8new JsFileDownloader({ 
9  url: '...',
10  process: process
11})
12  

onloadstart ('loadstart' event listener)

A function to call when a 'loadstart' event is triggered.

1
2function onloadstart () {
3  // what to do ...
4}
5
6new JsFileDownloader({ 
7  url: '...',
8  onloadstart
9})
10  

headers (of request)

If you need to customize request header data you can pass an array of objects like following example:

1new JsFileDownloader({ 
2  url: '...',
3  headers: [
4    { name: 'Authorization', value: 'Bearer ABC123...' }
5  ]
6})

filename

Setting this String you can force output file name

timeout (ms)

Integer value (default 40000) defining how much ms attend before stop download action.

autoStart

Boolean value (default true) to enable/disable automatically starting the download. When the value is true the constructor returns a Promise, however when it's set to false, the constructor doesn't return anything and the download can be started by calling the start() method on the object.

Example with autoStart set to true

1new JsFileDownloader({ 
2  url: '...',
3  autoStart: true
4})

Example with autoStart set to false

1const download = new JsFileDownloader({ 
2  url: '...',
3  autoStart: false
4});
5
6download.start()
7  .then(function(){
8      // success 
9  })
10  .catch(function(error){
11      // handle errors
12  });

forceDesktopMode

Boolean value (default false) to force desktop mode even on mobile devices for downloading files.

1new JsFileDownloader({ 
2  url: '...',
3  forceDesktopMode: true
4})

withCredentials

This is a Boolean that indicates whether or not cross-site Access-Control requests should be made using credentials such as cookies, authorization headers or TLS client certificates. Setting withCredentials has no effect on same-site requests.

1new JsFileDownloader({ 
2  url: '...',
3  withCredentials: true
4})

method

The HTTP request method to use, such as "GET", "POST", "PUT", etc. (default "GET") Ignored for non-HTTP(S) URLs.

1new JsFileDownloader({ 
2  url: '...',
3  method: 'POST'
4})

nameCallback

You could pass a callback to customize final name, the function receive as 1st argument the name automatically extracted.

1new JsFileDownloader({ 
2  url: '...',
3  nameCallback: function(name) {
4    return 'i-am-prefix-' + name;
5  }
6})

contentType

Setting this property you can customize the content type in the heade request, default is 'application/x-www-form-urlencoded' If you set this property as false, the library doesn't set it.

1new JsFileDownloader({ 
2  url: '...',
3  contentType: 'multipart/form-data; boundary=something' // or false to unset it
4})

---

nativeFallbackOnError

By setting this property to true (default is false) when error occours the download will fallback to the default behavior opening a new tab.

1new JsFileDownloader({ 
2  url: '...',
3  nativeFallbackOnError: true
4})

---

body

By setting this property you can customize the body content sent with the request. Default value is null (nothing is sent), Document or BodyInit value can be set.

1new JsFileDownloader({ 
2  url: '...',
3  body: 'The body as a string'
4})

contentTypeDetermination

By setting this property the downloader will determine the content type automatically depending on the value.

value	description
"header"	Gets type from content-type response header.
"signature"	Analyzes the first 4 bytes of the returned file and will check if that signature exists in the predetermined dict (You can override/merge this dict with the customFileSigantures property).
"full"	Uses both methods from above but prefers "siganture".
false	Type is not determined and the default is added, application/octet-stream.

1new JsFileDownloader({ 
2  url: '...',
3  contentTypeDetermination: 'header'
4})

customFileSignatures

By setting this value you can override/merge the predefined signature dict (src/signatures.js). The key represents the hex code of a file (for more information here) and the value should be in the format of a content type (e.g. application/pdf). Setting this value has only an affect when contentTypeDetermination is set to "full" or "signature".

1new JsFileDownloader({ 
2  url: '...',
3  contentTypeDetermination: 'full', // must be set to "full" or "signature"
4  customFileSignatures: {
5    'FFFB':'audio/mpeg',
6    'FFF3':'audio/mpeg',
7    'FFF2':'audio/mpeg',
8    '494433': 'audio/mpeg'
9  }
10})

---

Abort:

Setting autoStart option to false the process can be aborted calling the related method abort. The download promise is rejected, the reason can be customized passing is as the 1st param of the abort function.

1const download = new JsFileDownloader({ 
2  url: '...',
3  autoStart: false
4});
5
6download.start()
7  .catch(function(reason){
8      // handle errors
9  });
10
11download.abort(/** reason */);
12

---

License

MIT

Copyright (c) 2019-present, Alessandro Pellizzari

apedesign.net