{"id":16845698,"url":"https://github.com/othree/fetcher","last_synced_at":"2025-08-03T14:10:49.472Z","repository":{"id":30539527,"uuid":"34094192","full_name":"othree/fetcher","owner":"othree","description":"WHATWG fetch helper, inspired by jQuery.ajax","archived":false,"fork":false,"pushed_at":"2015-07-03T09:33:28.000Z","size":384,"stargazers_count":11,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-05-11T06:39:17.549Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://www.npmjs.com/package/fetch-er","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/othree.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}},"created_at":"2015-04-17T03:21:33.000Z","updated_at":"2015-12-01T09:12:17.000Z","dependencies_parsed_at":"2022-09-11T07:01:24.223Z","dependency_job_id":null,"html_url":"https://github.com/othree/fetcher","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/othree/fetcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/othree%2Ffetcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/othree%2Ffetcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/othree%2Ffetcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/othree%2Ffetcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/othree","download_url":"https://codeload.github.com/othree/fetcher/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/othree%2Ffetcher/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263597908,"owners_count":23486470,"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":[],"created_at":"2024-10-13T12:59:42.162Z","updated_at":"2025-07-04T18:38:13.115Z","avatar_url":"https://github.com/othree.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"fetch-er\n========\n\n[![Build Status](https://travis-ci.org/othree/fetcher.svg?branch=master)](https://travis-ci.org/othree/fetcher)\n\nA WHATWG [fetch][] helper. WHATWG's fetch is very modern. Simple name, uses Promise, options object. \nBut it designed as a low level API. Developers have to deal with some detail. ex: Post parameter \nserialize, transform response JSON to JavaScript object. So here is the fetch-er to help you deal \nwith these stuff. Inspired by jQuery.ajax.\n\n\n[fetch]:http://updates.html5rocks.com/2015/03/introduction-to-fetch\n\nExample\n-------\n\n```javascript\nfetcher.get('/api/users', null, {dataType: 'json'}).then( ([value, res]) =\u003e {\n  //...\n} )\n\nfetcher.getJSON('/api/users').then( ... )\n\nfetcher.post('/api/users', {name: 'John'}).then( ... )\n\nfetcher.put('/api/users',  {name: 'Wick'}).then( ... )\n\nfetcher.delete('/api/users/23').then( ... )\n```\n\nfetch-er is Not\n---------------\n\nfetch-er is not designed for every case. If you belongs to one of following situation. You should not use fetch-er:\n\n* Feeling good to use fetch API. Since it's not hard to use fetch without helper.\n* Every byte count, you need to keep your script as small as possible. Every byte matters.\n\nDoc\n---\n\nfetch-er provide a new global object for browser environment, called `fetcher`. `fetcher` is an instance\nof private `Fetcher` class. In other module systems like: CommonJS, AMD, NodeJS. You will get the same \ninstance of Fetcher when you include this module.\n\n```javascript\nvar fetcher = require('fetch-er')\n```\n\nTo install, you can use `npm` or `bower` or just download `dist/fetcher.js`.\n\n```shell\nnpm i fetch-er\nbower i fetch-er\n```\n\n\nThe Fetcher class have the following basic methods: `delete`, `get`, `getJSON`, `head`, `options`, `post`\nand `put`. Mapping the method name to HTTP method for the method will use. All methods receives three \narguments:\n\n* `url`: The url location of the request\n* `data`: Optional data for the request\n* `options`: Optional options object send to fetch\n\nThe options object will send to `fetch` and fetcher provides several new options:\n\n* `contentType`: The data type of request body you are going to send. Will overwrite the one in headers.\n* `dataType`: The data type you expect to receive from server. Supports mime type and following shorcut\n  `json`, `text` and `xml`.\n* `mimeType`: Will overwrite response mimeType before parse to data.\n* `timeout`: Will reject returned promise when time limit reach, but no actual abort now(current fetch don't have abort).\n\n\nWhat fetcher will do when you do a request through it:\n\n1. If method is `GET` or `HEAD`, parse data to form-urlencoded form. Append to request url.\n2. Auto generate request body if necessary. (json, form-urlencoded)\n  * JSON, if a request contains headers have `Content-Type: application/json` or `options.contentType` with the same value.\n    The data will parsed by `JSON.stringify` and write to body.\n  * FormData or ArrayBuffer will send to fetch directly.\n  * Default request body is `form-urlencoded`, use [jquery-param](https://www.npmjs.com/package/jquery-param).\n3. Set mode to `cors` if request to a different hostname.\n4. Auto parse response data. Fetcher will try to figure out what to do based on response content type and `options.dataType`.\n  * JSON string will parsed by `JSON.parse`.\n  * HTML will be plain text. If you want DOM node as response. You can set `options.dataType` to `xml`.\n  * XML will be parse by `DOMParser`.\n  * ArrayBuffer or FormData will only available if user set `options.dataType`.\n  * Otherwise, response will be plain text.\n\nFetcher methods will return a Promise just like fetch. But it will be fulfilled with different value, an \narray(`[value, status, response]`). First element is the response value. Second element is text response status. Possible status:\n\n* `nocontent` for 200 or HEAD request.\n* `notmodified` for 304 not modified.\n* `success` for other success request.\n\nThird element is consumed response object. The reason to use array is easier to use ES6 destructuring assign. Ex:\n\n```javascript\nfetcher.get('/api').then( ([value, status, response]) =\u003e {\n  // blah...\n})\n```\n\nPS. Plan to return not consumed response. But current polyfill don't support clone.\n\n#### request(method, url, data, options)\n\nThere is one more method called `request`. Is the base of all other methods. Receive four arguments: `method`,\n`url`, `data` and `options`. The method is in string format. All uppercase characters. Which will pass to \nfetch directly. And fetch will check is method valid.\n\nIf an error happened on fetcher reqeust. The returned promise will reject just like a normal fetch request.\nThis only happens when response status is not normal (100 to 599) or network error. By design fetch will fulfill\nreturned Promise when server have response. And developers can use `response.ok` to check is this request success.\nOnly when status code between 200 to 299 will set `ok` to true. But jQuery also accept `304` not modified.\nAnd jQuery will reject all other status code. The behavior is very different. And fetcher still not decide which \nto follow. \n\nThe rejected promise will use an array to reject(`[error, response]`). Some error will not get response.\nEx: timeout or network error.\n\n#### setup(options)\n\nThere is a method called `setup` used for setup default option. The default option will be used on every request.\nBut possible to overwrite when make the request. Current supported options are `method`, `contentType`, `dataType`, \n`mimeType`, `timeout` and `converters`. Default global options are:\n\n```javascript\n{\n  method: 'get',\n  converters: {\n    'text json': JSON.parse,\n    'text xml':  parseXML\n  }\n}\n```\n\n\n### Compare to jQuery.ajax\n\nStat: `y`: support, `p`: partial, `n`: not support, `n/a`: not possible, `todo`: in plan.\n\n| Feature         | Stat              |\n|-----------------|-------------------|\n| accepts         | y                 |\n| ajaxPrefilter() | n                 |\n| ajaxSetup()     | p, use setup()    |\n| ajaxTransport() | n/a               |\n| async           | n/a               |\n| beforeSend      | n                 |\n| cache           | n                 |\n| complete        | use promise chain |\n| contents        | n/a               |\n| contentType     | y                 |\n| context         | n/a               |\n| converters      | y, 2 level only   |\n| crossDomain     | auto              |\n| data            | y                 |\n| dataFilter      | n                 |\n| dataType        | y                 |\n| error           | use promise chain |\n| global          | n/a               |\n| headers         | y                 |\n| ifModified      | n                 |\n| isLocal         | n                 |\n| jsonp           | n                 |\n| jsonpCallback   | n                 |\n| method          | y                 |\n| mimeType        | y                 |\n| password        | n/a               |\n| processData     | todo              |\n| scriptCharset   | n                 |\n| statusCode      | n                 |\n| success         | use promise chain |\n| timeout         | y                 |\n| traditional     | n/a, based on dep |\n| type            | y                 |\n| url             | y                 |\n| username        | n/a               |\n| xhr             | n/a               |\n| xhrFields       | n/a               |\n\n\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fothree%2Ffetcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fothree%2Ffetcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fothree%2Ffetcher/lists"}