{"id":26608092,"url":"https://github.com/aleeekoi/js-file-downloader","last_synced_at":"2025-04-07T05:07:42.664Z","repository":{"id":45879280,"uuid":"164634056","full_name":"AleeeKoi/js-file-downloader","owner":"AleeeKoi","description":"🚀 A small JS no-dependency library for a cool download experience","archived":false,"fork":false,"pushed_at":"2023-05-16T11:31:34.000Z","size":633,"stargazers_count":236,"open_issues_count":2,"forks_count":37,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-04-07T05:06:58.382Z","etag":null,"topics":["download","javascript","js","status"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/AleeeKoi.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-01-08T11:26:24.000Z","updated_at":"2025-02-13T12:58:28.000Z","dependencies_parsed_at":"2024-06-18T13:44:17.131Z","dependency_job_id":null,"html_url":"https://github.com/AleeeKoi/js-file-downloader","commit_stats":{"total_commits":111,"total_committers":14,"mean_commits":7.928571428571429,"dds":0.6216216216216216,"last_synced_commit":"e9a3bbef744d063a132f518b70931087aa2b921d"},"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AleeeKoi%2Fjs-file-downloader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AleeeKoi%2Fjs-file-downloader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AleeeKoi%2Fjs-file-downloader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/AleeeKoi%2Fjs-file-downloader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/AleeeKoi","download_url":"https://codeload.github.com/AleeeKoi/js-file-downloader/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247595334,"owners_count":20963943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["download","javascript","js","status"],"created_at":"2025-03-23T23:32:07.357Z","updated_at":"2025-04-07T05:07:42.646Z","avatar_url":"https://github.com/AleeeKoi.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://apedesign.net/\" target=\"_blank\" rel=\"noopener noreferrer\"\u003e\n    \u003cimg height=\"150\" src=\"https://cdn.apedesign.net/github/logo.png\" alt=\"APE Design\" /\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n# JS File Downloader\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://www.npmjs.com/package/js-file-downloader\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/js-file-downloader.svg\" alt=\"Version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.npmjs.com/package/js-file-downloader\"\u003e\u003cimg src=\"https://img.shields.io/npm/l/js-file-downloader.svg\" alt=\"License\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n## **🌟Please remember to star this github repo if you like it. Thank you! ❤️**\n\n## Introduction\n\nJS File Downloader is a simple no dependency library you will be able to download file from browser and show downloading status.\n\n  - [Install](#installing-with-package-manager)\n  - [Basic usage](#basic-usage)\n  - [Options](#options)\n    - [process, check download status](#process-for-checking-download-status)\n    - [onloadstart](#onloadstart-loadstart-event-listener)\n    - [headers](#headers-of-request)\n    - [filename](#filename)\n    - [timeout](#timeout)\n    - [autoStart](#autostart)\n    - [forceDesktopMode](#forcedesktopmode)\n    - [withCredentials](#withcredentials)\n    - [method, GET/POST/...](#method)\n    - [nameCallback, custom at runtime](#namecallback)\n    - [contentType](#contenttype)\n    - [nativeFallbackOnError](#nativefallbackonerror)\n    - [body, of the request](#body)\n    - [contentTypeDetermination](#contenttypedetermination)\n    - [customFileSignatures](#customfilesignatures)\n  - [abort, to stop pending downloading request](#abort)\n\n### Browser Compatibility\n\nJS File Downloader supports all browsers that are [ES5-compliant] (http://kangax.github.io/compat-table/es5/) (IE8 and below are not supported).\n\n---\n\n### Installing with package manager\n\nWith a package manager (**recommended**): \n```js\nnpm install js-file-downloader --save \n```\n\n### Basic usage\n\n```js\n\nimport JsFileDownloader from 'js-file-downloader';\n\nconst fileUrl = 'http://...';\n\nnew JsFileDownloader({ \n    url: fileUrl\n  })\n  .then(function () {\n    // Called when download ended\n  })\n  .catch(function (error) {\n    // Called when an error occurred\n  });\n  \n```\n\n---\n\n### Use without a package manager\nDownload this library from https://github.com/AleeeKoi/js-file-downloader/releases\n```js\n\u003cscript src=\"/path/to/js-file-downloader.min.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\n  // Then somewhere in your code\n  new jsFileDownloader({ url: 'https://cdn.apedesign.net/github/logo.png' })\n    .then(function () {\n      // Called when download ended\n    })\n    .catch(function (error) {\n      // Called when an error occurred\n    });\n\u003c/script\u003e\n```\n\n---\n\n### Options:\n\n#### process (for checking download status)\nA function to call every time a process event is called. Function receive an Event Object as input.\n\n```js\n\nfunction process (event) {\n  if (!event.lengthComputable) return; // guard\n  var downloadingPercentage = Math.floor(event.loaded / event.total * 100);\n  // what to do ...\n};\n\nnew JsFileDownloader({ \n  url: '...',\n  process: process\n})\n  \n```\n\n#### onloadstart ('loadstart' event listener)\nA function to call when a 'loadstart' event is triggered.\n\n```js\n\nfunction onloadstart () {\n  // what to do ...\n}\n\nnew JsFileDownloader({ \n  url: '...',\n  onloadstart\n})\n  \n```\n\n#### headers (of request)\nIf you need to customize request header data you can pass an array of objects like following example:\n\n```js\nnew JsFileDownloader({ \n  url: '...',\n  headers: [\n    { name: 'Authorization', value: 'Bearer ABC123...' }\n  ]\n})\n```\n\n#### filename\nSetting this String you can force output file name\n\n#### timeout (ms)\nInteger value (default 40000) defining how much ms attend before stop download action.\n\n#### autoStart\nBoolean 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.\n\nExample with `autoStart` set to `true`\n```js\nnew JsFileDownloader({ \n  url: '...',\n  autoStart: true\n})\n```\n\nExample with `autoStart` set to `false`\n```js\nconst download = new JsFileDownloader({ \n  url: '...',\n  autoStart: false\n});\n\ndownload.start()\n  .then(function(){\n      // success \n  })\n  .catch(function(error){\n      // handle errors\n  });\n```\n\n#### forceDesktopMode\nBoolean value (default false) to force desktop mode even on mobile devices for downloading files.\n```js\nnew JsFileDownloader({ \n  url: '...',\n  forceDesktopMode: true\n})\n```\n\n#### withCredentials\nThis 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.\n```js\nnew JsFileDownloader({ \n  url: '...',\n  withCredentials: true\n})\n```\n\n#### method\nThe HTTP request method to use, such as \"GET\", \"POST\", \"PUT\", etc. (default \"GET\")\nIgnored for non-HTTP(S) URLs.\n\n```js\nnew JsFileDownloader({ \n  url: '...',\n  method: 'POST'\n})\n```\n\n#### nameCallback\nYou could pass a callback to customize final name, the function receive as 1st argument the name automatically extracted.\n\n```js\nnew JsFileDownloader({ \n  url: '...',\n  nameCallback: function(name) {\n    return 'i-am-prefix-' + name;\n  }\n})\n```\n\n#### contentType\nSetting this property you can customize the content type in the heade request, default is 'application/x-www-form-urlencoded'\nIf you set this property as false, the library doesn't set it.\n\n```js\nnew JsFileDownloader({ \n  url: '...',\n  contentType: 'multipart/form-data; boundary=something' // or false to unset it\n})\n```\n\n--- \n\n#### nativeFallbackOnError\nBy setting this property to true (default is false) when error occours the download will fallback to the default behavior opening a new tab.\n\n```js\nnew JsFileDownloader({ \n  url: '...',\n  nativeFallbackOnError: true\n})\n```\n\n--- \n\n#### body\nBy 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.\n\n```js\nnew JsFileDownloader({ \n  url: '...',\n  body: 'The body as a string'\n})\n```\n\n#### contentTypeDetermination\nBy setting this property the downloader will determine the content type automatically depending on the value.\n\nvalue | description\n--- | ---\n`\"header\"` | Gets type from `content-type` response header.\n`\"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).\n`\"full\"` | Uses both methods from above but prefers `\"siganture\"`.\n`false` | Type is not determined and the default is added, `application/octet-stream`.\n\n```js\nnew JsFileDownloader({ \n  url: '...',\n  contentTypeDetermination: 'header'\n})\n```\n\n#### customFileSignatures\nBy 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](https://en.wikipedia.org/wiki/List_of_file_signatures)) 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\"`.\n\n```js\nnew JsFileDownloader({ \n  url: '...',\n  contentTypeDetermination: 'full', // must be set to \"full\" or \"signature\"\n  customFileSignatures: {\n    'FFFB':'audio/mpeg',\n    'FFF3':'audio/mpeg',\n    'FFF2':'audio/mpeg',\n    '494433': 'audio/mpeg'\n  }\n})\n```\n___\n### Abort:\nSetting `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.\n\n```js\nconst download = new JsFileDownloader({ \n  url: '...',\n  autoStart: false\n});\n\ndownload.start()\n  .catch(function(reason){\n      // handle errors\n  });\n\ndownload.abort(/** reason */);\n\n```\n___\n\n### License\n\n[MIT](http://opensource.org/licenses/MIT)\n\nCopyright (c) 2019-present, Alessandro Pellizzari\n\n[apedesign.net](https://apedesign.net/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faleeekoi%2Fjs-file-downloader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faleeekoi%2Fjs-file-downloader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faleeekoi%2Fjs-file-downloader/lists"}