chore(deps): add renovate.json

Bumps [@babel/traverse](https://github.com/babel/babel/tree/HEAD/packages/babel-traverse) from 7.14.5 to 7.23.2.
- [Release notes](https://github.com/babel/babel/releases)
- [Changelog](https://github.com/babel/babel/blob/main/CHANGELOG.md)
- [Commits](https://github.com/babel/babel/commits/v7.23.2/packages/babel-traverse)

---
updated-dependencies:
- dependency-name: "@babel/traverse"
  dependency-type: indirect
...

Signed-off-by: dependabot[bot] <support@github.com>

.gitea/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI Pipeline
+
+on: [push, pull_request]
+
+jobs:
+  build:
+    runs-on: ubuntu-22.04
+
+    strategy:
+      matrix:
+        node-version: [20.x]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: ${{ matrix.node-version }}
+          registry-url: "https://registry.npmjs.org"
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

.github/workflows/ci.yml

@@ -1,17 +0,0 @@
-name: CI Pipeline
-
-on: [push, pull_request]
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v2
-    - name: Use Node.js 14.x
-      uses: actions/setup-node@v1
-      with:
-        node-version: 14.x
-    - run: npm ci
-    - run: npm run lint
-    - run: npm run coverage

README.md

@@ -1,5 +1,7 @@
 # node-fetch-cache
 
+Forked from: <https://github.com/mistval/node-fetch-cache>
+
 node-fetch with caching of responses.
 
 The first fetch with any given arguments will result in an HTTP request and any subsequent fetch with the same arguments will read the response from the cache.
@@ -11,11 +13,11 @@ By default responses are cached in memory, but you can also cache to files on di
 Require it and use it the same way you would use node-fetch:
 
 ```js
-const fetch = require('node-fetch-cache');
+import fetch from "node-fetch-cache";
 
-fetch('http://google.com')
+fetch("http://google.com")
-  .then(response => response.text())
+  .then((response) => response.text())
-  .then(text => console.log(text));
+  .then((text) => console.log(text));
 ```
 
 The next time you `fetch('http://google.com')`, the response will be returned from the cache. No HTTP request will be made.
@@ -33,25 +35,20 @@ This function can be used to eject the response from the cache, so that the next
 This module caches ALL responses, even those with 4xx and 5xx response statuses. You can use this function to uncache such responses if desired. For example:
 
 ```js
-const fetch = require('node-fetch-cache');
+import fetch from "node-fetch-cache";
 
-fetch('http://google.com')
+fetch("http://google.com")
-  .then(async response => {
+  .then(async (response) => {
     if (!response.ok) {
       await response.ejectFromCache();
-      throw new Error('Non-okay response from google.com');
+      throw new Error("Non-okay response from google.com");
     } else {
       return response.text();
     }
-  }).then(text => console.log(text));
+  })
+  .then((text) => console.log(text));
 ```
 
-## Streaming
-
-This module does not support Stream request bodies, except for fs.ReadStream. And when using fs.ReadStream, the cache key is generated based only on the path of the stream, not its content. That means if you stream `/my/desktop/image.png` twice, you will get a cached response the second time, **even if the content of image.png has changed**.
-
-Streams don't quite play nice with the concept of caching based on request characteristics, because we would have to read the stream to the end to find out what's in it and hash it into a proper cache key.
-
 ## Cache Customization
 
 By default responses are cached in memory, but you can also cache to files on disk, or implement your own cache.
@@ -63,7 +60,7 @@ This is the default cache delegate. It caches responses in-process in a POJO.
 Usage:
 
 ```js
-const { fetchBuilder, MemoryCache } = require('node-fetch-cache');
+import { fetchBuilder, MemoryCache } from "node-fetch-cache";
 const fetch = fetchBuilder.withCache(new MemoryCache(options));
 ```
 
@@ -75,7 +72,7 @@ Options:
 }
 ```
 
-Note that by default (if you don't use `withCache()`) a **shared** MemoryCache will be used (you can import this module in multiple files and they will all share the same cache). If you instantiate and provide a `new MemoryCache()` as shown above however, the cache is *NOT* shared unless you explicitly pass it around and pass it into `withCache()` in each of your source files.
+Note that by default (if you don't use `withCache()`) a **shared** MemoryCache will be used (you can import this module in multiple files and they will all share the same cache). If you instantiate and provide a `new MemoryCache()` as shown above however, the cache is _NOT_ shared unless you explicitly pass it around and pass it into `withCache()` in each of your source files.
 
 ### FileSystemCache
 
@@ -84,7 +81,7 @@ Cache to a directory on disk. This allows the cache to survive the process exiti
 Usage:
 
 ```js
-const  { fetchBuilder, FileSystemCache } = require('node-fetch-cache');
+import { fetchBuilder, FileSystemCache } from "node-fetch-cache";
 const fetch = fetchBuilder.withCache(new FileSystemCache(options));
 ```
 
@@ -111,6 +108,61 @@ The remove function should accept a key and remove the cached value associated w
 
 All three functions may be async.
 
+## Misc Tips
+
+### Streaming
+
+This module does not support Stream request bodies, except for fs.ReadStream. And when using fs.ReadStream, the cache key is generated based only on the path of the stream, not its content. That means if you stream `/my/desktop/image.png` twice, you will get a cached response the second time, **even if the content of image.png has changed**.
+
+Streams don't quite play nice with the concept of caching based on request characteristics, because we would have to read the stream to the end to find out what's in it and hash it into a proper cache key.
+
+### Request Concurrency
+
+Requests with the same cache key are queued. For example, you might wonder if making the same request 100 times simultaneously would result in 100 HTTP requests:
+
+```js
+import fetch from "node-fetch-cache";
+
+await Promise.all(
+  Array(100)
+    .fill()
+    .map(() => fetch("https://google.com"))
+);
+```
+
+The answer is no. Only one request would be made, and 99 of the `fetch()`s will read the response from the cache.
+
+### Cache-Control: only-if-cached Requests
+
+The HTTP standard describes a [Cache-Control request header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control#request_directives) to control certain aspects of cache behavior. Node-fetch ignores these, but node-fetch-cache respects the `Cache-Control: only-if-cached` directive. When `only-if-cached` is specified, node-fetch-cache will return `undefined` if there is no cached response. No HTTP request will be made. For example:
+
+```js
+import fetch from "node-fetch-cache";
+
+const response = await fetch("https://google.com", {
+  headers: { "Cache-Control": "only-if-cached" },
+});
+
+if (response === undefined) {
+  // No response was found in the cache
+}
+```
+
+Note that this is slightly different from browser fetch, which returns a `504 Gateway Timeout` response if no cached response is available.
+
+### Calculating the Cache Key
+
+This module exports a `getCacheKey()` function to calculate a cache key string from request parameters, which may be useful for enabling some advanced use cases (especially if you want to call cache functions directly). Call `getCacheKey()` exactly like you would call `fetch()`.
+
+```js
+import { fetchBuilder, MemoryCache, getCacheKey } from "node-fetch-cache";
+
+const cache = new MemoryCache();
+const fetch = fetchBuilder.withCache(cache);
+
+const rawCacheData = await cache.get(getCacheKey("https://google.com"));
+```
+
 ## 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).

package.json

@@ -1,24 +1,28 @@
 {
-  "name": "node-fetch-cache",
+  "name": "@fascinated/node-fetch-cache",
-  "version": "3.0.0",
+  "version": "3.1.3",
-  "description": "node-fetch with a persistent cache.",
+  "description": "node-fetch with caching.",
   "main": "src/index.js",
   "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
   "exports": {
     "import": "./src/index.js",
     "require": "./commonjs/wrapper.cjs"
   },
   "scripts": {
     "buildcjs": "rollup src/index.js --file commonjs/index.cjs --format cjs",
-    "test": "npm run buildcjs && mocha --timeout 10000 --exit",
+    "test": "npm run lintfix && npm run buildcjs && mocha --timeout 10000 --exit",
     "coverage": "nyc --reporter=lcov --reporter=text npm test",
-    "lint": "./node_modules/.bin/eslint .",
+    "lint": "eslint .",
-    "lintfix": "./node_modules/.bin/eslint . --fix",
+    "lintfix": "eslint . --fix",
     "prepublishOnly": "npm test"
   },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mistval/node-fetch-cache.git"
+    "url": "git+https://git.fascinated.cc/Fascinated/node-fetch-cache.git"
   },
   "keywords": [
     "node",
@@ -30,24 +34,24 @@
   "author": "mistval",
   "license": "MIT",
   "bugs": {
-    "url": "https://github.com/mistval/node-fetch-cache/issues"
+    "url": "https://git.fascinated.cc/Fascinated/node-fetch-cache/issues"
   },
-  "homepage": "https://github.com/mistval/node-fetch-cache#readme",
+  "homepage": "https://git.fascinated.cc/Fascinated/node-fetch-cache#readme",
   "devDependencies": {
-    "eslint": "^6.8.0",
+    "eslint": "^8.9.0",
-    "eslint-config-airbnb-base": "^14.1.0",
+    "eslint-config-airbnb-base": "^15.0.0",
-    "eslint-plugin-import": "^2.20.2",
+    "eslint-plugin-import": "^2.25.4",
     "form-data": "^3.0.0",
-    "husky": "^4.3.0",
+    "husky": "^8.0.3",
-    "mocha": "^8.2.1",
+    "mocha": "^9.2.1",
     "nyc": "^15.1.0",
     "rimraf": "^3.0.2",
     "rollup": "^2.53.0"
   },
   "dependencies": {
     "cacache": "^15.2.0",
-    "locko": "0.0.3",
+    "locko": "^1.0.0",
-    "node-fetch": "2.6.1"
+    "node-fetch": "2.6.11"
   },
   "husky": {
     "hooks": {

renovate.json

@@ -0,0 +1,6 @@
+{
+  "$schema": "https://docs.renovatebot.com/renovate-schema.json",
+  "extends": [
+    "local>Fascinated/renovate-config"
+  ]
+}

src/classes/caching/file_system_cache.js

@@ -1,6 +1,5 @@
 import cacache from 'cacache';
 import { Readable } from 'stream';
-import { KeyTimeout } from './key_timeout.js';
 
 function getBodyAndMetaKeys(key) {
   return [`${key}body`, `${key}meta`];
@@ -9,7 +8,6 @@ function getBodyAndMetaKeys(key) {
 export class FileSystemCache {
   constructor(options = {}) {
     this.ttl = options.ttl;
-    this.keyTimeout = new KeyTimeout();
     this.cacheDirectory = options.cacheDirectory || '.cache';
   }
 
@@ -24,9 +22,15 @@ export class FileSystemCache {
 
     const metaBuffer = await cacache.get.byDigest(this.cacheDirectory, metaInfo.integrity);
     const metaData = JSON.parse(metaBuffer);
-    const { bodyStreamIntegrity, empty } = metaData;
+    const { bodyStreamIntegrity, empty, expiration } = metaData;
+
     delete metaData.bodyStreamIntegrity;
     delete metaData.empty;
+    delete metaData.expiration;
+
+    if (expiration && expiration < Date.now()) {
+      return undefined;
+    }
 
     const bodyStream = empty
       ? Readable.from(Buffer.alloc(0))
@@ -41,8 +45,6 @@ export class FileSystemCache {
   remove(key) {
     const [bodyKey, metaKey] = getBodyAndMetaKeys(key);
 
-    this.keyTimeout.clearTimeout(key);
-
     return Promise.all([
       cacache.rm.entry(this.cacheDirectory, bodyKey),
       cacache.rm.entry(this.cacheDirectory, metaKey),
@@ -53,7 +55,9 @@ export class FileSystemCache {
     const [bodyKey, metaKey] = getBodyAndMetaKeys(key);
     const metaCopy = { ...metaData };
 
-    this.keyTimeout.clearTimeout(key);
+    if (typeof this.ttl === 'number') {
+      metaCopy.expiration = Date.now() + this.ttl;
+    }
 
     try {
       metaCopy.bodyStreamIntegrity = await new Promise((fulfill, reject) => {
@@ -75,10 +79,6 @@ export class FileSystemCache {
     await cacache.put(this.cacheDirectory, metaKey, metaBuffer);
     const cachedData = await this.get(key);
 
-    if (typeof this.ttl === 'number') {
-      this.keyTimeout.updateTimeout(key, this.ttl, () => this.remove(key));
-    }
-
     return cachedData;
   }
 }

src/index.js

@@ -1,12 +1,11 @@
 import fetch, { Request } from 'node-fetch';
 import fs from 'fs';
-import { URLSearchParams } from 'url';
 import crypto from 'crypto';
 import locko from 'locko';
 import { NFCResponse } from './classes/response.js';
 import { MemoryCache } from './classes/caching/memory_cache.js';
 
-const CACHE_VERSION = 3;
+const CACHE_VERSION = 4;
 
 function md5(str) {
   return crypto.createHash('md5').update(str).digest('hex');
@@ -36,6 +35,14 @@ function getFormDataCacheKey(formData) {
   return cacheKey;
 }
 
+function getHeadersCacheKeyJson(headersObj) {
+  return Object.fromEntries(
+    Object.entries(headersObj)
+      .map(([key, value]) => [key.toLowerCase(), value])
+      .filter(([key, value]) => key !== 'cache-control' || value !== 'only-if-cached'),
+  );
+}
+
 function getBodyCacheKeyJson(body) {
   if (!body) {
     return body;
@@ -55,11 +62,13 @@ function getBodyCacheKeyJson(body) {
 }
 
 function getRequestCacheKey(req) {
+  const headersPojo = Object.fromEntries([...req.headers.entries()]);
+
   return {
     cache: req.cache,
     credentials: req.credentials,
     destination: req.destination,
-    headers: req.headers,
+    headers: getHeadersCacheKeyJson(headersPojo),
     integrity: req.integrity,
     method: req.method,
     redirect: req.redirect,
@@ -70,15 +79,15 @@ function getRequestCacheKey(req) {
   };
 }
 
-function getCacheKey(requestArguments) {
+export function getCacheKey(resource, init = {}) {
-  const resource = requestArguments[0];
-  const init = requestArguments[1] || {};
-
   const resourceCacheKeyJson = resource instanceof Request
     ? getRequestCacheKey(resource)
     : { url: resource };
 
-  const initCacheKeyJson = { ...init };
+  const initCacheKeyJson = {
+    ...init,
+    headers: getHeadersCacheKeyJson(init.headers || {}),
+  };
 
   resourceCacheKeyJson.body = getBodyCacheKeyJson(resourceCacheKeyJson.body);
   initCacheKeyJson.body = getBodyCacheKeyJson(initCacheKeyJson.body);
@@ -88,8 +97,25 @@ function getCacheKey(requestArguments) {
   return md5(JSON.stringify([resourceCacheKeyJson, initCacheKeyJson, CACHE_VERSION]));
 }
 
+function hasOnlyWithCacheOption(resource, init) {
+  if (
+    init
+    && init.headers
+    && Object.entries(init.headers)
+      .some(([key, value]) => key.toLowerCase() === 'cache-control' && value === 'only-if-cached')
+  ) {
+    return true;
+  }
+
+  if (resource instanceof Request && resource.headers.get('Cache-Control') === 'only-if-cached') {
+    return true;
+  }
+
+  return false;
+}
+
 async function getResponse(cache, requestArguments) {
-  const cacheKey = getCacheKey(requestArguments);
+  const cacheKey = getCacheKey(...requestArguments);
   let cachedValue = await cache.get(cacheKey);
 
   const ejectSelfFromCache = () => cache.remove(cacheKey);
@@ -103,6 +129,10 @@ async function getResponse(cache, requestArguments) {
     );
   }
 
+  if (hasOnlyWithCacheOption(...requestArguments)) {
+    return undefined;
+  }
+
   await locko.lock(cacheKey);
   try {
     cachedValue = await cache.get(cacheKey);

test/tests.js

@@ -7,7 +7,7 @@ import rimraf from 'rimraf';
 import path from 'path';
 import { URLSearchParams } from 'url';
 import standardFetch from 'node-fetch';
-import FetchCache, { MemoryCache, FileSystemCache } from '../src/index.js';
+import FetchCache, { MemoryCache, FileSystemCache, getCacheKey } from '../src/index.js';
 import { Agent } from 'http';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -326,6 +326,17 @@ describe('Data tests', function() {
     assert.strictEqual(res.fromCache, true);
   });
 
+  it('Supports request objects with custom headers', async function() {
+    const request1 = new standardFetch.Request(TWO_HUNDRED_URL, { headers: { 'XXX': 'YYY' } });
+    const request2 = new standardFetch.Request(TWO_HUNDRED_URL, { headers: { 'XXX': 'ZZZ' } });
+
+    res = await cachedFetch(request1);
+    assert.strictEqual(res.fromCache, false);
+
+    res = await cachedFetch(request2);
+    assert.strictEqual(res.fromCache, false);
+  });
+
   it('Refuses to consume body twice', async function() {
     res = await cachedFetch(TEXT_BODY_URL);
     await res.text();
@@ -476,3 +487,45 @@ describe('File system cache tests', function() {
     assert.strictEqual(res.fromCache, true);
   });
 });
+
+describe('Cache mode tests', function() {
+  it('Can use the only-if-cached cache control setting via init', async function() {
+    res = await cachedFetch(TWO_HUNDRED_URL, { headers: { 'Cache-Control': 'only-if-cached' } });
+    assert(!res);
+    res = await cachedFetch(TWO_HUNDRED_URL, { headers: { 'Cache-Control': 'only-if-cached' } });
+    assert(!res);
+    res = await cachedFetch(TWO_HUNDRED_URL);
+    assert(res && !res.fromCache);
+    res = await cachedFetch(TWO_HUNDRED_URL, { headers: { 'Cache-Control': 'only-if-cached' } });
+    assert(res && res.fromCache);
+    await res.ejectFromCache();
+    res = await cachedFetch(TWO_HUNDRED_URL, { headers: { 'Cache-Control': 'only-if-cached' } });
+    assert(!res);
+  });
+
+  it('Can use the only-if-cached cache control setting via resource', async function() {
+    res = await cachedFetch(new standardFetch.Request(TWO_HUNDRED_URL, { headers: { 'Cache-Control': 'only-if-cached' } }));
+    assert(!res);
+    res = await cachedFetch(new standardFetch.Request(TWO_HUNDRED_URL));
+    assert(res && !res.fromCache);
+    res = await cachedFetch(new standardFetch.Request(TWO_HUNDRED_URL, { headers: { 'Cache-Control': 'only-if-cached' } }));
+    assert(res && res.fromCache);
+  });
+});
+
+describe('Cache key tests', function() {
+  it('Can calculate a cache key and check that it exists', async function() {
+    const cache = new MemoryCache();
+    cachedFetch = FetchCache.withCache(cache);
+    await cachedFetch(TWO_HUNDRED_URL);
+
+    const cacheKey = getCacheKey(TWO_HUNDRED_URL);
+    const nonExistentCacheKey = getCacheKey(TEXT_BODY_URL);
+
+    const cacheKeyResult = await cache.get(cacheKey);
+    const nonExistentCacheKeyResult = await cache.get(nonExistentCacheKey);
+
+    assert(cacheKeyResult);
+    assert(!nonExistentCacheKeyResult);
+  });
+});