https://github.com/js-bits/loader
HTTP resource loader
https://github.com/js-bits/loader
Last synced: about 1 year ago
JSON representation
HTTP resource loader
- Host: GitHub
- URL: https://github.com/js-bits/loader
- Owner: js-bits
- Created: 2021-06-26T18:13:38.000Z (almost 5 years ago)
- Default Branch: main
- Last Pushed: 2023-07-19T03:04:20.000Z (almost 3 years ago)
- Last Synced: 2025-03-27T08:16:45.028Z (about 1 year ago)
- Language: JavaScript
- Size: 1.64 MB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# HTTP resource Loader
An 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.
## Installation
Install with npm:
```
npm install @js-bits/loader
```
Install with yarn:
```
yarn add @js-bits/loader
```
Import where you need it:
```javascript
import Loader from '@js-bits/loader';
```
or require for CommonJS:
```javascript
const Loader = require('@js-bits/loader');
```
## How to use
Simple example
```javascript
const swCharacter = new Loader('https://swapi.dev/api/people/1/');
(async () => {
swCharacter.load(); // just a contextualized alias of Executor#execute();
const result = await swCharacter;
console.log(result.name); // Luke Skywalker
})();
```
Content type is automatically detected and the result type is based on that information. It can be one of the following:
- [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object) - for `'application/json'` content
- [String](https://developer.mozilla.org/en-US/docs/Glossary/String) - for `'text/plain'` content
- [HTMLDocument](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDocument) - for `'text/html'` content
- [XMLDocument](https://developer.mozilla.org/en-US/docs/Web/API/XMLDocument) - for XML based content (like `'text/xml'`, and `'image/svg+xml'`)
- Raw [Response](https://developer.mozilla.org/en-US/docs/Web/API/Response) object when content type is not recognized
You can also explicitly specify expected content type using optional `mimeType` parameter.
```javascript
const xml = new Loader('https://api.nbp.pl/api/exchangerates/tables/a/last/1/?format=xml', {
mimeType: 'text/plain',
});
(async () => {
xml.load();
const result = await xml;
console.log(result.slice(0, 38)); //
})();
```
Since `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.
```javascript
const xml = new Loader(url, {
method: 'POST',
headers: {...}
body: '...',
});
```
## Additional features
There are `Loader#send()` and `Loader#load()` aliases of `Executor#execute()` method available for convenience. Also, unlike `fetch()`, `Loader` has built-in `.abort()` method.
Features 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.
```javascript
const url = 'https://www.bankofcanada.ca/valet/observations/group/FX_RATES_DAILY/xml?start_date=2021-05-30';
const content = new Loader(url, {
timeout: 1000,
});
const { EXECUTED, RESOLVED } = Loader.STATES;
(async () => {
content.load();
try {
const result = await content;
const { timings } = content;
console.log(result); // ...
console.log(`Load time: ${timings[RESOLVED] - timings[EXECUTED]} ms`); // Load time: 538 ms
} catch (reason) {
if (reason.name === Loader.TimeoutExceededError && reason.requestURL === url) {
console.log('LoaderTimeoutError', reason.requestURL);
}
}
})();
```
## Error handling
```javascript
const content = new Loader('...');
(async () => {
content.load();
try {
const result = await content;
// ...
} catch (reason) {
switch (reason.name) {
case Loader.RequestAbortError:
// request has been aborted
// ...
break;
case Loader.TimeoutExceededError:
// request has exceeded specified timeout
// ...
break;
case Loader.ResponseParsingError:
// response was successfully received but something went wrong during parsing
// you can use reason.response to get access to raw Response object
// ...
break;
case Loader.RequestError:
// error status code has received (4xx, 5xx)
// ...
break;
}
}
})();
```