JavaScript File Downloader With Promise Support

Preview:

Description:

A JavaScript file downloader library that provides a user-friendly file download experience on the web.

The downloader returns a promise indicating whether a download is ended that then can be used for further processing.

How to use it:

1. Install & download the package.

# NPM
$ npm install js-file-downloader --save

2. Import the file downloader as a module.

import Downloader from 'js-file-downloader';

3. Or load the js-file-downloader.min.js from the dist folder.

<script src="./dist/js-file-downloader.min.js"></script>

4. Create a new downloader instance the specify the path to the file to be downloaded.

new jsFileDownloader({ 
    url: '1.jpg' 
})

5. Do something when the download is ended.

new jsFileDownloader({ 
    url: '1.jpg' 
})
.then(function () {
  alert('File downloaded');
});

6. Do something when an error occurred.

new jsFileDownloader({ 
    url: '1.jpg' 
})
.catch(function (error) {
  // do something
});

7. Determine the maximum time to wait before stopping downloading. Default: ‘40000’.

new jsFileDownloader({ 
    url: '1.jpg',
    timeout: 50000
});

8. Determine whether to disable download on mobile devices. Default: true.

new jsFileDownloader({ 
    url: '1.jpg',
    mobileDisabled: false
})

9. Determine whether to auto start downloading on page load. Default: true.

new jsFileDownloader({ 
    url: '1.jpg',
    autoStart: false
});

10. Determine whether to force desktop mode even on mobile devices for downloading files. Default: false.

new jsFileDownloader({ 
    url: '1.jpg',
    forceDesktopMode: true
});

11. Customize the request header data.

new jsFileDownloader({ 
    url: '1.jpg',
    headers: [
      { name: 'Authorization', value: 'Value...' }
    ]
});

12. Customize the file name.

new jsFileDownloader({ 
    url: '1.jpg',
    filename: 'cssscript.jpg'
});

13. Check download status using the process function.

new jsFileDownloader({ 
    url: '1.jpg',
    process: process
});
function process (event) {
  if (!event.lengthComputable) return;
  var downloadingPercentage = Math.floor(event.loaded / event.total * 100);
  // what to do ...
};

14. Determine the method for the HTTP request.

new Downloader({ 
    url: '...',
    method: 'POST' // "GET", "POST", "PUT"
})

15. Customize the final file name with the nameCallback.

new Downloader({ 
    nameCallback: function(name) {
      return 'i-am-prefix-' + name;
    }
})

16. Determine the content type.

new Downloader({ 
    contentType: 'application/x-www-form-urlencoded'
})

17. customize the body content sent with the request. Default value is null (nothing is sent), Document or BodyInit value can be set.

new Downloader({ 
    body: null
})

18. Determine whether to enable the native fallback when error occurs. Default: false.

new Downloader({ 
    nativeFallbackOnError: true
})

19. Determine the content type automatically depending on the value: “header”, “signature”, “full”, or false.

new Downloader({ 
    contentTypeDetermination: 'header'
})

20. API methods.

const download = new JsFileDownloader({ 
      // ...
});
download.start()
  .catch(function(reason){
      // handle errors
  });
download.abort(/** reason */);

21. Callback.

function onloadstart () {
  // do something
}
new JsFileDownloader({ 
  url: '...',
  onloadstart
})

Changelog:

v1.1.25 (05/16/2023)

• added abort method, by calling it the pending download process can be cancelled;

v1.1.24 (12/07/2021)

• added contentTypeDetermination, by setting this property the downloader will determine the content type automatically depending on the value;

v1.1.23 (11/24/2021)

• added onloadstart callback
• various fixes

v1.1.21 (08/18/2021)

• added option 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.
• added 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.

v1.1.20 (06/05/2021)

• added contentType as a configurable option

v1.1.19 (04/10/2021)

• always reject the download promise with a DownloadException
• deprecated old exception name downloadException (it will be removed in next releases)
• updated dependencies

v1.1.18 (03/25/2021)

• fix webpack library export

v1.1.17 (03/24/2021)

• removed deprecated props + refactoring

v1.1.16 (03/09/2021)

• dependency update

v1.1.14 (10/22/2020)

• old parameter includeCredentials is deprecated in favor of withCredentials

v1.1.13 (10/15/2020)

• Fixed wrong type definition in index.d.ts

v1.1.12 (10/15/2020)

• added index.d.ts file
• fix the Exception named downloadException
• added param ‘request’ to the downloadExceptionobject

v1.1.11 (09/01/2020)

• shutting down dependencies warning
• removed unnecessary attribute

v1.1.9 (07/09/2020)

• Added support for customizing the final filename

v1.1.8 (05/25/2020)

• Added new “method” option to customize HTTP request method

v1.1.7 (04/24/2020)

• Added support for XMLHttpRequest.withCredentials