{"id":20494319,"url":"https://github.com/voltra/fetchjson","last_synced_at":"2026-04-17T22:03:19.482Z","repository":{"id":57151178,"uuid":"96460364","full_name":"Voltra/fetchJSON","owner":"Voltra","description":"A Javascript library that allows to abstract all boilerplate from retrieving JSON data using the native ES6 fetch API","archived":false,"fork":false,"pushed_at":"2019-08-20T12:42:11.000Z","size":11,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-02T01:34:39.353Z","etag":null,"topics":["fetch-api","fetchjson","javascript-library","promise"],"latest_commit_sha":null,"homepage":null,"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/Voltra.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":"2017-07-06T18:28:01.000Z","updated_at":"2019-08-20T12:09:07.000Z","dependencies_parsed_at":"2022-08-24T07:10:54.672Z","dependency_job_id":null,"html_url":"https://github.com/Voltra/fetchJSON","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2FfetchJSON","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2FfetchJSON/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2FfetchJSON/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Voltra%2FfetchJSON/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Voltra","download_url":"https://codeload.github.com/Voltra/fetchJSON/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242075965,"owners_count":20068231,"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":["fetch-api","fetchjson","javascript-library","promise"],"created_at":"2024-11-15T17:39:06.126Z","updated_at":"2025-12-05T22:02:22.021Z","avatar_url":"https://github.com/Voltra.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fetchJSON #\nA Javascript library that allows to abstract all boilerplate from retrieving JSON data using the native ES6 fetch API.\n\n----------\n\n\n\nSimple and easy to use, it only abstracts away all the boilerplate required for fetching json data.\nNo other javascript library is required to use this library.\n\n----------\n## Installation/Use ##\nJust like every library should, I tried to make fetchJSON compatible with quite everything I am aware of.\n\nfetchJSON currently supports regular use (via HTML script tag), npm and require (and commonJS), AMD (and probably ES6 modules ?).\n\nTherefore, here are two ways to install this library:\n***Without NPM***\n```html\n\u003chtml\u003e\n\t\u003c!-- [...] --\u003e\n\t\u003chead\u003e\n\t\t\u003c!-- [...] --\u003e\n\t\t\u003cscript src=\"path/to/fetchJSON.js\"\u003e\u003c/script\u003e\n\t\t\u003c!-- [...] --\u003e\n\t\u003c/head\u003e\n\t\u003c!-- [...] --\u003e\n\u003c/html\u003e\n```\n\n***With NPM***\n```\nnpm install fetch_json\n```\n```javascript\nconst fetchJSON = require(\"fetch_json\");\n```\n\n\n\n***With NPM and Babel***\n\n`npm install fetch_json`\n\n`import fetchJSON from \"fetch_json\"`\n\n## Simple use case ##\n\nSometimes, you just have that json file which's sole purpose is configuration.\nWith fetchJSON, getting the data from this file is very easy:\n\n```javascript\n//With fetchJSON\nlet config_data;\nfetchJSON(\"../../someFolder/someFile.json\").then(data=\u003econfig_data=data);\n\n//Without fetchJSON\nlet config_data;\nfetch(\"../../someFolder/someFile.json\").then(response=\u003e{\n\t/*gather headers*/\n\tif(/*there's json in there*/)\n\t\treturn response.json().then(data=\u003e{\n\t\t\t/*some manipulation*/\n\t\t\tconfig_data = data;\n\t\t\t//finally !\n\t\t});\n\telse\n\t\t/*handle error*/\n});\n\n```\n\nOnce loaded, the data can be used like this: \n```javascript\nfetchJSON(\"../../someFolder/someFile.json\").then(config_data=\u003e{\n\t/* use data to configure your application*/\n});\n```\n\n## Error Handling ##\nOne of the most important part of retrieving data asynchronously is error handling.\nSometimes you have server issues, sometimes you used an incorrect path and this can be a pain in the ass with regular fetch.\n\nVersion 1.0.5 (NPM, it's 1.05 on github) brings a whole new layer of abstracted boilerplate for error handling. Here's a simple example with, and without, fetchJSON.\n\n```javascript\n//with fetchJSON\nfetchJSON(\"../../someFolder/someFile.json\")\n.then(/*some manipulations*/)\n.then(/*some manipulations*/)\n.catch(errorMsg=\u003e{\n  /*handle errors here*/\n});\n\n//without fetchJSON\nnew Promise((resolve, reject)=\u003e{\n  fetch(\"../../someFolder/someFile.json\").then(response=\u003e{\n        /*gather headers*/\n        if(/*there's json in there*/)\n        \treturn response.json().then(data=\u003e{\n        \t\t/*some manipulation*/\n        \t\t//finally !\n        \t\tresolve(data);//important\n        \t});\n        else\n        \treject(/*handle error*/)\n    });\n})\n.then(/*some manipulations*/)\n.then(/*some manipulations*/)\n.catch(errorMsg=\u003e{\n  /*handle errors here*/\n});\n```\nFrom version 1.0.5, fetchJSON is completely thenable and catchable just like any other good Promise-based library \\o/ !\n\n## Motivations ##\nAs you can see, fetchJSON really focuses on what's important : using the data. Whereas the regular fetch approach is mostly boilerplate and takes up a lot of space in your code, and most of that space is here solely to get the data not using it.\n\nJSON is a precious resource, it would be a shame to spend more time on getting its data than using it.\n\n## Questions/Suggestions ##\nPlease fill free to ask for help or post suggestions on my github repository, I'll be more than glad to take care of your problems/concerns.\n\n#Hot updates\n\n### A bit more Promise style\n\nSince v1.10 you can use full Promise style to fetch your data :\n\n```javascript\nlet data = null;\nfetchJSON(\"/path/to/file/dot.json\")\n.then(json =\u003e data=json);\n\n//Is strictly equivalent to\n\nlet data = null;\nfetchJSON(\"/path/to/file/dot.json\", json =\u003e data=json);\n```\n\n\n\n## Complete 180°\n\nSince v2.0.0 the second argument, which was a callback function (same behavior as a simple `then`), has been changed to an object of data :\n\nThis object of data must be:\n\n* Not provided (defaulted to `{}`)\n* an empty object\n* an object of numbers and/or strings\n* an object of numbers and/or strings and/or arrays (that only contains numbers and/or strings)\n\n\n\nThis allows you to construct the query string easily :\n\n```javascript\nfetchJSON(\"/api/user\", {\n    id: 42,\n    item: \"player_profile\"\n    props: [\n        \"rank\",\n        \"ratio\"\n    ]\n}); //Will conduct a GET request to /api/user?id=42\u0026item=player_profile\u0026props=rank\u0026props=ratio\n\n///OR\n\nfetchJSON(\"/api/user?\", {\n    id: 42,\n    item: \"player_profile\"\n    props: [\n        \"rank\",\n        \"ratio\"\n    ]\n}); //Will conduct a GET request to /api/user?id=42\u0026item=player_profile\u0026props=rank\u0026props=ratio\n\n///OR\n\nfetchJSON(\"/api/user?test=1\", {\n    id: 42,\n    item: \"player_profile\"\n    props: [\n        \"rank\",\n        \"ratio\"\n    ]\n}); //Will conduct a GET request to /api/user?test=1\u0026id=42\u0026item=player_profile\u0026props=rank\u0026props=ratio\n\n///OR\n\nfetchJSON(\"/api/user?test=1\u0026\", {\n    id: 42,\n    item: \"player_profile\"\n    props: [\n        \"rank\",\n        \"ratio\"\n    ]\n}); //Will conduct a GET request to /api/user?test=1\u0026id=42\u0026item=player_profile\u0026props=rank\u0026props=ratio\n```\n\n## Changes\n### v2.2.0\nIn an effort to make the library as usable as possible, I refactored the options/query string/headers merging algorithm to use deep merging instead of shallow merging.\n\n### v2.1.0\n\nIn an effort to provide more customization, `fetchJSON` now exposes a third argument : `options`. This is an object following the same interface as `fetch`'s `init` [argument](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch#Parameters), with the only enforcement being that headers come as an object and not an object or an array.\n\n\n\nIt also exposes `fetchJSON.defaults` with three properties : `qs`, `options` and `headers` :\n\n* `qs` is merged w/ the `data` argument of `fetchJSON`\n* `headers` is merged w/ the `headers` property of the `options` argument of `fetchJSON`\n* `options` is merged w/ the `options` argument of `fetchJSON`","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoltra%2Ffetchjson","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvoltra%2Ffetchjson","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvoltra%2Ffetchjson/lists"}