Registry / http-networking / node-fetch-cache

node-fetch-cache

library5.1.0jsnpmunverified

node-fetch-cache is a robust wrapper around the popular `node-fetch` library, providing an integrated caching layer for HTTP responses. It automatically caches responses from HTTP requests, serving subsequent identical requests directly from the cache without making a network call. The current stable version is 5.1.0, and the project appears to have an active release cadence with regular updates and maintenance, as indicated by recent releases adding new features like cache clearing. Key differentiators include its seamless integration with the standard `node-fetch` API, support for multiple cache backends (in-memory, file system, Redis via an adapter), and flexible control over caching behavior through `shouldCacheResponse` options. It's designed for Node.js environments, requiring Node.js 18.19.0 or higher, and ships with TypeScript types for improved developer experience.

http-networking serialization

npm install node-fetch-cache

github ↗package ↗

INSTALL

IMPORT

SIG · NODE-FETCH-CACHE

node-fetch-cache

http-networkingjavascriptv5.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

fetch

✓ import fetch from 'node-fetch-cache';

✗ const fetch = require('node-fetch-cache');

The primary way to use node-fetch-cache, mimicking `node-fetch`'s default import. Node.js >=18.19.0 supports ESM natively, so CJS `require` is generally incorrect or requires bundler setup.

NodeFetchCache

✓ import NodeFetchCache from 'node-fetch-cache';

Used for creating custom fetch instances with specific caching configurations, e.g., `NodeFetchCache.create({ cache: new FileSystemCache() })`.

FileSystemCache

✓ import { FileSystemCache } from 'node-fetch-cache';

✗ import NodeFetchCache, { FileSystemCache } from 'node-fetch-cache';

Correctly imported as a named export. Incorrectly using it as a default export or incorrectly assuming it's part of the default export `NodeFetchCache` is a common mistake.

MemoryCache

✓ import { MemoryCache } from 'node-fetch-cache';

Used for explicit in-memory caching with TTL configuration. Note that the default cache is also `MemoryCache` but without a TTL.

This quickstart demonstrates how to use `node-fetch-cache` with a file system cache, including setting a TTL, filtering responses to cache, and programmatically clearing the cache directory.

import fetch from 'node-fetch-cache'; import { FileSystemCache } from 'node-fetch-cache'; import * as path from 'path'; async function fetchData() { // Create a custom fetch instance that caches to disk with a 1-hour TTL const diskCacheFetch = NodeFetchCache.create({ cache: new FileSystemCache({ cacheDirectory: path.join(process.cwd(), '.node-fetch-cache'), ttl: 3600000 // 1 hour in milliseconds }), shouldCacheResponse: (response) => response.ok // Only cache successful responses }); console.log('Fetching Google homepage (first time - network request)...'); const firstResponse = await diskCacheFetch('http://google.com'); console.log('Status:', firstResponse.status); console.log('Cached:', firstResponse.headers.get('x-nf-cache-status')); // Should be 'MISS' console.log('\nFetching Google homepage (second time - from cache)...'); const secondResponse = await diskCacheFetch('http://google.com'); console.log('Status:', secondResponse.status); console.log('Cached:', secondResponse.headers.get('x-nf-cache-status')); // Should be 'HIT' // Demonstrate clearing the cache const fileCache = new FileSystemCache({ cacheDirectory: path.join(process.cwd(), '.node-fetch-cache') }); console.log('\nClearing file system cache...'); await fileCache.clear(); console.log('Cache cleared. Subsequent fetch will be a MISS again.'); const thirdResponse = await diskCacheFetch('http://google.com'); console.log('Status:', thirdResponse.status); console.log('Cached:', thirdResponse.headers.get('x-nf-cache-status')); // Should be 'MISS' again } fetchData().catch(console.error);

Debug

Known issues

gotchaBy default, `node-fetch-cache` uses an in-memory cache with no Time-To-Live (TTL). This means cached responses will persist indefinitely within the process's lifetime, potentially leading to stale data or excessive memory consumption if not explicitly configured with a `MemoryCache` instance and a `ttl`.

fix

For in-memory caching with expiration, create a custom fetch instance: `NodeFetchCache.create({ cache: new MemoryCache({ ttl: 60000 }) })`. For persistent caching, consider `FileSystemCache` or `@node-fetch-cache/redis`.

affects: >=1.0.0

gotchaWhen using `FileSystemCache` with a `ttl`, expired cache entries are not automatically deleted from disk. This can lead to significant disk bloat over time as invalid files accumulate in the cache directory.

fix

Implement a periodic cleanup mechanism by calling the `.clear()` method on your `FileSystemCache` instance, which will delete the entire cache directory. For example, `new FileSystemCache(options).clear()` in a cron job or scheduled task.

affects: >=1.0.0

breaking`node-fetch-cache` is a wrapper around `node-fetch`. Any breaking changes introduced in major versions of `node-fetch` (e.g., changes to its API or underlying mechanisms) will inherently affect `node-fetch-cache` users. Always review `node-fetch`'s release notes when upgrading.

fix

Consult the `node-fetch` documentation and release notes for relevant breaking changes when upgrading the underlying `node-fetch` version or `node-fetch-cache` itself.

affects: >=1.0.0

gotchaWhen configuring caching behavior, options passed directly to the `fetch()` call take precedence over options configured via `NodeFetchCache.create()`. This merging behavior might lead to unexpected caching if not understood.

fix

Be explicit about where you define your caching options. If an option is present in both `create()` and `fetch()`, the `fetch()`-level option will override the `create()`-level option for that specific request.

affects: >=1.0.0

Errors

Common errors & fixes

TypeError: fetch is not a function

Attempting to use `require()` to import `node-fetch-cache` in an environment configured for ESM or when `type: module` is set in `package.json`.

fix

Use ESM `import fetch from 'node-fetch-cache';` instead of `const fetch = require('node-fetch-cache');`.

ENOENT: no such file or directory, scandir '/path/to/.node-fetch-cache'

The specified `cacheDirectory` for `FileSystemCache` does not exist and the process lacks permissions to create it, or an incorrect path was provided.

fix

Ensure the `cacheDirectory` path is valid and accessible by the Node.js process. The library should create the directory if it doesn't exist, but permission issues or invalid root paths can prevent this. Check permissions and path correctness.

Upgrade

Version history

5.1.0latest on npm

Audit

Dependencies

node-fetchrequiredCore dependency; this package wraps node-fetch to add caching functionality. Its API is a superset of node-fetch's.

@node-fetch-cache/redisoptionalOptional dependency for using Redis as a cache backend.

Agent activity

7 hits · last 30 days

node

Amazon

Resources

githubhttps://github.com/mistval/node-fetch-cache ↗

packagehttps://www.npmjs.com/package/node-fetch-cache ↗