Node Fetch Cache

Common errors

• TypeError: fetch is not a function

  cause 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'

  cause 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.

Warnings

• gotcha By 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`.
• gotcha When 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.
• 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.
• gotcha When 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.

Install

• npm install node-fetch-cache npm
• yarn add node-fetch-cache yarn
• pnpm add node-fetch-cache pnpm

Imports

• fetch
  wrong:

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

  correct:

  import fetch from '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
  wrong:

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

  correct:

  import { 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.

Quickstart

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);