{"id":26709405,"url":"https://github.com/js-bits/loader","last_synced_at":"2025-04-13T17:32:48.331Z","repository":{"id":57122333,"uuid":"380568575","full_name":"js-bits/loader","owner":"js-bits","description":"HTTP resource loader","archived":false,"fork":false,"pushed_at":"2023-07-19T03:04:20.000Z","size":1722,"stargazers_count":3,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-27T08:16:45.028Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/js-bits.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-06-26T18:13:38.000Z","updated_at":"2023-07-03T17:58:13.000Z","dependencies_parsed_at":"2022-08-24T14:59:26.849Z","dependency_job_id":null,"html_url":"https://github.com/js-bits/loader","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/js-bits%2Floader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/js-bits%2Floader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/js-bits%2Floader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/js-bits%2Floader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/js-bits","download_url":"https://codeload.github.com/js-bits/loader/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248752376,"owners_count":21156080,"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":"2025-03-27T08:16:47.676Z","updated_at":"2025-04-13T17:32:48.312Z","avatar_url":"https://github.com/js-bits.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HTTP resource Loader\n\nAn implementation of [Executor](https://www.npmjs.com/package/@js-bits/executor) aimed to be used to load resources over HTTP. Built with [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) under the hood. Key features: automatic response type conversion; built-in timeout and abort capability; execution timings.\n\n## Installation\n\nInstall with npm:\n\n```\nnpm install @js-bits/loader\n```\n\nInstall with yarn:\n\n```\nyarn add @js-bits/loader\n```\n\nImport where you need it:\n\n```javascript\nimport Loader from '@js-bits/loader';\n```\n\nor require for CommonJS:\n\n```javascript\nconst Loader = require('@js-bits/loader');\n```\n\n## How to use\n\nSimple example\n\n```javascript\nconst swCharacter = new Loader('https://swapi.dev/api/people/1/');\n\n(async () =\u003e {\n  swCharacter.load(); // just a contextualized alias of Executor#execute();\n  const result = await swCharacter;\n  console.log(result.name); // Luke Skywalker\n})();\n```\n\nContent type is automatically detected and the result type is based on that information. It can be one of the following:\n\n- [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) - for `'application/json'` content\n- [String](https://developer.mozilla.org/en-US/docs/Glossary/String) - for `'text/plain'` content\n- [HTMLDocument](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument) - for `'text/html'` content\n- [XMLDocument](https://developer.mozilla.org/en-US/docs/Web/API/XMLDocument) - for XML based content (like `'text/xml'`, and `'image/svg+xml'`)\n- Raw [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object when content type is not recognized\n\nYou can also explicitly specify expected content type using optional `mimeType` parameter.\n\n```javascript\nconst xml = new Loader('https://api.nbp.pl/api/exchangerates/tables/a/last/1/?format=xml', {\n  mimeType: 'text/plain',\n});\n\n(async () =\u003e {\n  xml.load();\n  const result = await xml;\n  console.log(result.slice(0, 38)); // \u003c?xml version=\"1.0\" encoding=\"utf-8\"?\u003e\n})();\n```\n\nSince `Loader` is built with [Fetch API](https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API) you can pass [fetch parameters](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/fetch) the same way, using second argument.\n\n```javascript\nconst xml = new Loader(url, {\n  method: 'POST',\n  headers: {...}\n  body: '...',\n});\n```\n\n## Additional features\n\nThere are `Loader#send()` and `Loader#load()` aliases of `Executor#execute()` method available for convenience. Also, unlike `fetch()`, `Loader` has built-in `.abort()` method.\n\nFeatures of [Executor](https://www.npmjs.com/package/@js-bits/executor), like [execution timings](https://www.npmjs.com/package/@js-bits/executor#execution-timings) and [hard/soft timeout](https://www.npmjs.com/package/@js-bits/executor#timeout) are also available here.\n\n```javascript\nconst url = 'https://www.bankofcanada.ca/valet/observations/group/FX_RATES_DAILY/xml?start_date=2021-05-30';\nconst content = new Loader(url, {\n  timeout: 1000,\n});\nconst { EXECUTED, RESOLVED } = Loader.STATES;\n\n(async () =\u003e {\n  content.load();\n\n  try {\n    const result = await content;\n    const { timings } = content;\n    console.log(result); // \u003cdata\u003e...\u003c/data\u003e\n    console.log(`Load time: ${timings[RESOLVED] - timings[EXECUTED]} ms`); // Load time: 538 ms\n  } catch (reason) {\n    if (reason.name === Loader.TimeoutExceededError \u0026\u0026 reason.requestURL === url) {\n      console.log('LoaderTimeoutError', reason.requestURL);\n    }\n  }\n})();\n```\n\n## Error handling\n\n```javascript\nconst content = new Loader('...');\n\n(async () =\u003e {\n  content.load();\n\n  try {\n    const result = await content;\n    // ...\n  } catch (reason) {\n    switch (reason.name) {\n      case Loader.RequestAbortError:\n        // request has been aborted\n        // ...\n        break;\n      case Loader.TimeoutExceededError:\n        // request has exceeded specified timeout\n        // ...\n        break;\n      case Loader.ResponseParsingError:\n        // response was successfully received but something went wrong during parsing\n        // you can use reason.response to get access to raw Response object\n        // ...\n        break;\n      case Loader.RequestError:\n        // error status code has received (4xx, 5xx)\n        // ...\n        break;\n    }\n  }\n})();\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjs-bits%2Floader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjs-bits%2Floader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjs-bits%2Floader/lists"}