Registry / storage / fetch-json-cache

fetch-json-cache

JSON →
library1.6.3jsnpmunverified

A Node.js library for fetching JSON from URLs with disk caching. It updates the cache only when the ETag changes, and falls back to cached data if the endpoint is unreachable. Uses write-file-atomic for safe file writes. v1.6.3 requires Node >=0.8, ships TypeScript types, and supports both callbacks and Promises. Designed for reliability in offline or flaky network scenarios.

storage
npm install fetch-json-cache
github ↗package ↗homepage ↗
INSTALL
IMPORT
SIG · FETCH-JSON-CACHE
F
fetch-json-cache
storagejavascriptv1.6.3
harness data pending
Install & Compatibility
Where this runs

No compatibility data collected yet for this library.

Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Cache
✓ const Cache = require('fetch-json-cache')
✗ import Cache from 'fetch-json-cache'
CommonJS only; no ESM default export.
Cache (default)
✓ const Cache = require('fetch-json-cache')
✗ const { Cache } = require('fetch-json-cache')
The module exports a single constructor as default; named destructuring fails.
Cache with Promises
✓ const Cache = require('fetch-json-cache'); const cache = new Cache('./cache'); const json = await cache.get('https://api.example.com/data')
✗ cache.get('url').then(json => ...) // wrong if using older Node without native await support
Promise support requires Node >= 0.12 or polyfill; async/await needs Node >= 7.6.

Demonstrates basic usage with callbacks and promises, including forced update and cache clearing.

const Cache = require('fetch-json-cache'); const cache = new Cache('/tmp/my-cache'); // Callback style cache.get('https://jsonplaceholder.typicode.com/users', (err, json) => { if (err) throw err; console.log(`Fetched ${json.length} users`); }); // Promise style with forced update cache.get('https://jsonplaceholder.typicode.com/posts', { force: true }) .then(posts => console.log(`Fetched ${posts.length} posts`)) .catch(err => console.error(err)); // Clear cache cache.clear(err => { if (!err) console.log('Cache cleared'); });
Debug
Known issues
breakingNode version requirement: only supports Node >=0.8. Many modern features (async/await, native Promises) may need polyfills or transpilation.
fix
Ensure you are using Node >=0.8 and consider polyfilling Promise/async-await for older environments.
affects: >=1.0.0
deprecatedCallback style is still supported but Promises are recommended for cleaner code.
fix
Use the promise-returning API (cache.get returns a Promise if no callback is provided).
affects: >=1.0.0
gotchaThe constructor cache path must be writable. If the directory does not exist, it will not be created automatically and operations may fail silently.
fix
Ensure the cache directory exists before creating the Cache instance: fs.mkdirSync('./cache', { recursive: true }).
affects: >=1.0.0
gotchaETag change detection only works if the server returns an ETag header. Without it, the cache uses a simpler heuristic (status code).
fix
If your API does not return ETags, cache behavior may be suboptimal; consider using force: true to bypass cache.
affects: >=1.0.0
gotchaIf you use the options object { force: true }, the callback must be the third argument; omitting the options object and using only callback is fine for normal use.
fix
When using force update, pass options as second argument: cache.get(url, { force: true }, callback).
affects: >=1.0.0
Errors
Common errors & fixes
Cannot find module 'fetch-json-cache'
npm install failed or module not installed in node_modules.
fix
Run 'npm install fetch-json-cache' and verify it appears in node_modules.
TypeError: cache.get is not a function
Using named import fetch-json-cache incorrectly (e.g., import { Cache } from 'fetch-json-cache') or forgetting to instantiate with new.
fix
Use: const Cache = require('fetch-json-cache'); const cache = new Cache('./path');
Error: ENOENT: no such file or directory, open '/path/to/cache/somefile.json'
Cache directory does not exist.
fix
Create the directory before instantiation: require('fs').mkdirSync('./cache', { recursive: true });
Upgrade
Version history
1.6.3latest on npm
Audit
Dependencies
write-file-atomicrequiredUsed for safe atomic writes to prevent cache corruption.
Agent activity
13 hits · last 30 days
node
12
Resources
githubssh://git@github.com/kmalakoff/fetch-json-cache ↗
packagefetch-json-cache ↗
homepagehttps://github.com/kmalakoff/fetch-json-cache ↗
fetch-json-cache — npm install fetch-json-cache · libregistry