This repository has been archived on 2023-10-27. You can view files and clone it, but cannot push or open issues or pull requests.
node-fetch-cache/README.md

99 lines
4.2 KiB
Markdown
Raw Normal View History

2020-04-17 20:56:05 +00:00
# node-fetch-cache
node-fetch with caching to a directory on disk.
2020-04-17 21:09:24 +00:00
The first usage with any given arguments will result in an HTTP request and any subsequent usage with the same arguments and body function (text, json, buffer, or textConverted) will read the response body from the cache on disk.
2020-04-17 20:56:05 +00:00
## Usage
2020-04-17 21:09:24 +00:00
Require it with a directory path to cache in, and then use it the same way you would use fetch.
2020-04-17 20:56:05 +00:00
```js
const fetch = require('node-fetch-cache')('./path/to/cache/dir');
fetch('http://google.com')
.then(response => response.text())
.then(text => console.log(text));
```
## API
2021-06-10 16:07:19 +00:00
This module aims to expose the same API as `node-fetch` does for the most common use cases, but may not support some of the less common use cases.
2020-04-17 20:56:05 +00:00
### async fetch(resource [, init])
2021-06-10 16:10:10 +00:00
Same arguments as [node-fetch](https://www.npmjs.com/package/node-fetch).
2020-04-17 20:56:05 +00:00
Returns a **CachedResponse**.
### async CachedResponse.text()
2021-06-10 16:10:10 +00:00
Returns the body as a string, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2020-04-17 20:56:05 +00:00
### async CachedResponse.json()
2021-06-10 16:10:10 +00:00
Returns the body as a JavaScript object, parsed from JSON, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2020-04-17 20:56:05 +00:00
### async CachedResponse.buffer()
2021-06-10 16:10:10 +00:00
Returns the body as a Buffer, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2020-04-17 20:56:05 +00:00
2021-06-10 16:07:19 +00:00
### CachedResponse.status
2020-04-17 20:56:05 +00:00
2021-06-10 16:10:10 +00:00
Returns the HTTP status code of the response, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2020-04-17 20:56:05 +00:00
2021-06-10 16:07:19 +00:00
### CachedResponse.statusText
2021-06-10 16:10:10 +00:00
Returns a text represention of the response status, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2021-06-10 16:07:19 +00:00
### CachedResponse.ok
2021-06-10 16:10:10 +00:00
Returns true if the request returned a successful response status, false otherwise, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2021-06-10 16:07:19 +00:00
### CachedResponse.redirected
2021-06-10 16:10:10 +00:00
Returns true if the request was redirected, false otherwise, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2021-06-10 16:07:19 +00:00
### CachedResponse.headers
2021-06-10 16:10:10 +00:00
Returns a **ResponseHeaders** object representing the headers of the response, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2021-06-10 16:07:19 +00:00
### ResponseHeaders.entries()
2021-06-10 16:10:10 +00:00
Returns the raw headers as an array of `[key, value]` pairs, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2021-06-10 16:07:19 +00:00
2021-06-10 16:08:44 +00:00
### ResponseHeaders.keys()
2021-06-10 16:07:19 +00:00
2021-06-10 16:10:10 +00:00
Returns an array of all header keys, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2021-06-10 16:07:19 +00:00
2021-06-10 16:08:44 +00:00
### ResponseHeaders.values()
2021-06-10 16:07:19 +00:00
2021-06-10 16:10:10 +00:00
Returns an array of all header values, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2021-06-10 16:07:19 +00:00
2021-06-10 16:08:44 +00:00
### ResponseHeaders.get(key)
2021-06-10 16:07:19 +00:00
2021-06-10 16:10:10 +00:00
Returns the value of the header with the given key, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2021-06-10 16:07:19 +00:00
2021-06-10 16:08:44 +00:00
### ResponseHeaders.has(key)
2021-06-10 16:07:19 +00:00
2021-06-10 16:10:10 +00:00
Returns true if the headers has a value for the given key, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2021-06-10 16:07:19 +00:00
2021-06-10 16:08:44 +00:00
### ResponseHeaders.raw
2021-06-10 16:07:19 +00:00
2021-06-10 16:10:10 +00:00
Returns the headers as an object of `{ "key": "value" }` pairs, same as [node-fetch](https://www.npmjs.com/package/node-fetch).
2021-06-10 16:07:19 +00:00
## Streaming
2021-06-10 16:10:10 +00:00
This module supports streams like [node-fetch](https://www.npmjs.com/package/node-fetch) does, but with a couple of caveats you should be aware of if you want to use streams.
2021-06-10 16:07:19 +00:00
1. Response bodies are always read into memory even if you stream them to disk. That means if you need to stream large responses that don't fit into RAM, this module may be unsuitable.
2. When streaming a request body with fs.ReadStream, the cache key is generated based only on the path of the stream, not its content. That means if you stream `image.png` twice, you will get a cached response the second time, **even if the content of image.png has changed**. This module may be unsuitable if you need to stream files in requests and the content of those files can change.
## Bugs / Help / Feature Requests / Contributing
For feature requests or help, please visit [the discussions page on GitHub](https://github.com/mistval/node-fetch-cache/discussions).
For bug reports, please file an issue on [the issues page on GitHub](https://github.com/mistval/node-fetch-cache/issues).
Contributions welcome! Please open a [pull request on GitHub](https://github.com/mistval/node-fetch-cache/pulls) with your changes. You can run them by me first on [the discussions page](https://github.com/mistval/node-fetch-cache/discussions) if you'd like.