shared-http-cache 1.0.4 → 1.0.6

package/index.d.ts

@@ -0,0 +1,39 @@
+interface FetchRequest {
+    /** Request URL. */
+    url: string;
+    /** Resource integrity. */
+    integrity?: string;
+    /** Request init options [MDN reference](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit) */
+    options?: RequestInit;
+    /** Callback function. */
+    callback?: (response: {
+        /** Response buffer. */
+        buffer: Buffer;
+        /** Response headers [MDN reference](https://developer.mozilla.org/en-US/docs/Web/API/Headers) */
+        headers: Headers;
+        /** Is response from cache? */
+        fromCache: boolean;
+        /** Request index. */
+        index: number;
+    }) => void;
+}
+declare class SharedHttpCache {
+    constructor(options?: {
+        /** Cache directory (default: ".cache") */
+        cacheDir?: string;
+        /** Await storage (default: false) */
+        awaitStorage?: boolean;
+        /** Optional properties */
+        [key: string]: any;
+    });
+    /** Cache directory path (default: ".cache") */
+    readonly cacheDir: string;
+    /** Await storage (default: false) */
+    readonly awaitStorage: boolean;
+    /** Fetch multiple requests (async).*/
+    fetch(requests: readonly FetchRequest[]): Promise<this>;
+    /** Storage management */
+    readonly store: typeof import('cacache');
+}
+
+export = SharedHttpCache;

package/index.js

@@ -7,12 +7,6 @@ class SharedHttpCache {
         Object.assign(this, { cacheDir: '.cache', awaitStorage: false }, options);
         this.store = cacache;
     }
-    /**
-     * Fetch multiple resources with HTTP cache support.
-     * @param {Array<{url:string,integrity?:string,options?:RequestInit,callback:(response:{buffer:Buffer,headers:Headers,fromCache:boolean,index:number})=>void}>} requests
-     * @returns {Promise<this|{url:string,headers?:Headers,error:Error,index:number}[]>}
-     * @see [RequestInit](https://developer.mozilla.org/en-US/docs/Web/API/RequestInit), [Headers](https://developer.mozilla.org/en-US/docs/Web/API/Headers) MDN references
-     */
     async fetch(requests) {
         if (!Array.isArray(requests)) return Promise.reject([{ error: new TypeError('requests must be an array.') }]);
         const errors = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shared-http-cache",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Node.Js Utility for fetching multiple HTTP resources with browser-like cache management.",
   "keywords": [
     "http-cache",

package/readme.md

@@ -17,7 +17,7 @@ This implementation models a shared HTTP cache that follows the semantics define
 The cache is shared (not private) and applies shared-cache rules.
 
 - Request `methods` other than `GET` are not stored.
-- Private responses (request `Authorization`, response `Cache-Control="private"` and `Set-Cookie` headers) are not stored.
+- Private responses (request `Authorization`, response `Cache-Control="private"` and `Set-Cookie` headers) not stored.
 - Variant responses (response header `Vary` present) are not stored.
 - Partial content (response `Content-Range` header) is not stored.
 - Time calculations rely exclusively on locally recorded timestamps, not on server-provided `Date`.
@@ -315,6 +315,16 @@ The underlying cache store (`cacache`) is exposed directly.
 sharedHttpCache.store -> cacache
 ```
 
+**Listing (example with promise)**
+
+```js
+sharedHttpCache
+    .fetch(requests)
+    .then((sharedHttpCache) => sharedHttpCache.store.ls(sharedHttpCache.cacheDir))
+    .then(console.log)
+    .catch((errors) => console.error('Errors:', errors));
+```
+
 **Compacting (example with await)**
 
 ```ts
@@ -322,20 +332,38 @@ sharedHttpCache.store.verify(cacheDir) -> Promise<Object>
 ```
 
 ```js
-await sharedHttpCache.store.verify(sharedHttpCache.cacheDir);
+// deadbeef collected, because of invalid checksum.
+sharedHttpCache.store.verify(sharedHttpCache.cacheDir).then((stats) => {
+    console.log('cache is much nicer now! stats:', stats);
+});
 ```
 
-**Listing (example with promise)**
+**Basic cleanup strategy**
 
 ```js
-sharedHttpCache
-    .fetch(requests)
-    .then((sharedHttpCache) => sharedHttpCache.store.ls(sharedHttpCache.cacheDir))
-    .then(console.log)
-    .catch((errors) => console.error('Errors:', errors));
+const SharedHttpCache = require('shared-http-cache');
+// only-if-cached also means ... and is not stale!
+(async () => {
+    const cache = new SharedHttpCache({ cacheDir: '.cache', awaitStorage: true });
+    const entries = await cache.store.ls(cache.cacheDir);
+    const requests = Object.keys(entries).map((url) => ({ url, options: { headers: { 'cache-control': 'only-if-cached' } } }));
+    await cache.fetch(requests).catch(async (errors) => {
+        for (const { url } of errors) {
+            const file = url && await cache.store.get.info(cache.cacheDir, url);
+            if (file) {
+                await cache.store.rm.entry(cache.cacheDir, url, { removeFully: true });
+                await cache.store.rm.content(cache.cacheDir, file.integrity);
+            }
+        }
+    });
+})();
 ```
 
-Other available operations
+**Note:**
+
+- This is a fully `RFC 9111` compliant strategy that cleans up all the resources that can be determined as expired based on the stored response headers. For a more flexible approach, `max-stale=$acceptedStaleness` directive can be used in conjunction with `only-if-cached`. Cleanup strategies that rely on empirical calculations, such as `least recently used`, are `NOT RECOMMENDED`.
+
+**Other available operations**
 
 - sharedHttpCache.store.put(...)
 - sharedHttpCache.store.get(...)
@@ -347,6 +375,8 @@ See full list of [cacache options](https://github.com/npm/cacache?tab=readme-ov-
 
 ## Bottom line
 
-- `max-stale` is intended to be used: many servers enforce `max-age=0`, but clients usually know how much staleness they can tolerate. Using `max-stale` (recommended up to 24 h) can significantly reduce network requests.
+- `max-stale` is intended to be used: many servers enforce `max-age=0`, but clients know how much staleness they can tolerate. Using `max-stale` (recommended up to 24 h) can significantly reduce network requests.
 - providing `integrity` on requests enables fast loads by allowing cached content to be read directly from store.
+- `SharedHttpCache` init with `awaitStorage: true` is important when `fetch` is continued with `store` actions.
+- private or sensitive content is served, but not stored.
 - cache cleanup and eviction are deliberately left to the consumer; a well-chosen cleanup strategy is essential for maintaining good performance.