@serwist/expiration 9.0.0-preview.14 → 9.0.0-preview.16

package/dist/ExpirationPlugin.d.ts

@@ -1,4 +1,4 @@
-import type { SerwistPlugin } from "@serwist/core";
+import type { CacheDidUpdateCallbackParam, CachedResponseWillBeUsedCallbackParam, SerwistPlugin } from "@serwist/core";
 export interface ExpirationPluginOptions {
     /**
      * The maximum number of entries to cache. Entries used the least will be removed
@@ -6,9 +6,16 @@ export interface ExpirationPluginOptions {
      */
     maxEntries?: number;
     /**
-     * The maximum age of an entry before it's treated as stale and removed.
+     * The maximum number of seconds before an entry is treated as stale and removed.
      */
     maxAgeSeconds?: number;
+    /**
+     * Determines whether `maxAgeSeconds` should be calculated from when an
+     * entry was last fetched or when it was last used.
+     *
+     * @default "last-fetched"
+     */
+    maxAgeFrom?: "last-fetched" | "last-used";
     /**
      * The [`CacheQueryOptions`](https://developer.mozilla.org/en-US/docs/Web/API/Cache/delete#Parameters)
      * that will be used when calling `delete()` on the cache.
@@ -42,7 +49,6 @@ export interface ExpirationPluginOptions {
  */
 export declare class ExpirationPlugin implements SerwistPlugin {
     private readonly _config;
-    private readonly _maxAgeSeconds?;
     private _cacheExpirations;
     /**
      * @param config
@@ -66,11 +72,11 @@ export declare class ExpirationPlugin implements SerwistPlugin {
      * older than the configured `maxAgeSeconds`.
      *
      * @param options
-     * @returns Either the `cachedResponse`, if it's fresh, or `null` if the `Response`
-     * is older than `maxAgeSeconds`.
+     * @returns `cachedResponse` if it is fresh and `null` if it is stale or
+     * not available.
      * @private
      */
-    cachedResponseWillBeUsed: SerwistPlugin["cachedResponseWillBeUsed"];
+    cachedResponseWillBeUsed({ event, cacheName, request, cachedResponse }: CachedResponseWillBeUsedCallbackParam): Response | null;
     /**
      * @param cachedResponse
      * @returns
@@ -78,8 +84,7 @@ export declare class ExpirationPlugin implements SerwistPlugin {
      */
     private _isResponseDateFresh;
     /**
-     * This method will extract the data header and parse it into a useful
-     * value.
+     * Extracts the `Date` header and parse it into an useful value.
      *
      * @param cachedResponse
      * @returns
@@ -93,7 +98,7 @@ export declare class ExpirationPlugin implements SerwistPlugin {
      * @param options
      * @private
      */
-    cacheDidUpdate: SerwistPlugin["cacheDidUpdate"];
+    cacheDidUpdate({ cacheName, request }: CacheDidUpdateCallbackParam): Promise<void>;
     /**
      * Deletes the underlying `Cache` instance associated with this instance and the metadata
      * from IndexedDB used to keep track of expiration details for each `Cache` instance.

package/dist/ExpirationPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExpirationPlugin.d.ts","sourceRoot":"","sources":["../src/ExpirationPlugin.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAMnD,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;OAGG;IACH,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC;;OAEG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAS;IACzC,OAAO,CAAC,iBAAiB,CAA+B;IAExD;;OAEG;gBACS,MAAM,GAAE,uBAA4B;IAsChD;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;;;;;;;;;;;OAYG;IACH,wBAAwB,EAAE,aAAa,CAAC,0BAA0B,CAAC,CA+BjE;IAEF;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAqB5B;;;;;;;OAOG;IACH,OAAO,CAAC,uBAAuB;IAkB/B;;;;;;OAMG;IACH,cAAc,EAAE,aAAa,CAAC,gBAAgB,CAAC,CAmB7C;IAEF;;;;;;;;;;;OAWG;IACG,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;CAW9C"}
+{"version":3,"file":"ExpirationPlugin.d.ts","sourceRoot":"","sources":["../src/ExpirationPlugin.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,2BAA2B,EAAE,qCAAqC,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAMvH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,UAAU,CAAC,EAAE,cAAc,GAAG,WAAW,CAAC;IAC1C;;;OAGG;IACH,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC;;OAEG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,qBAAa,gBAAiB,YAAW,aAAa;IACpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA0B;IAClD,OAAO,CAAC,iBAAiB,CAA+B;IAExD;;OAEG;gBACS,MAAM,GAAE,uBAA4B;IAkDhD;;;;;;;OAOG;IACH,OAAO,CAAC,mBAAmB;IAa3B;;;;;;;;;;;;OAYG;IACH,wBAAwB,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,cAAc,EAAE,EAAE,qCAAqC;IAqC7G;;;;OAIG;IACH,OAAO,CAAC,oBAAoB;IAwB5B;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAkB/B;;;;;;OAMG;IACG,cAAc,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,EAAE,2BAA2B;IAqBxE;;;;;;;;;;;OAWG;IACG,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;CAW9C"}

package/dist/index.js

@@ -1,4 +1,4 @@
-import { assert, SerwistError, logger, dontWaitFor, privateCacheNames, getFriendlyURL } from '@serwist/core/internal';
+import { assert, SerwistError, logger, privateCacheNames, getFriendlyURL } from '@serwist/core/internal';
 import { deleteDB, openDB } from 'idb';
 import { registerQuotaErrorCallback } from '@serwist/core';
 
@@ -17,7 +17,10 @@ class CacheTimestampsModel {
     }
     _upgradeDb(db) {
         const objStore = db.createObjectStore(CACHE_OBJECT_STORE, {
-            keyPath: "id"
+            keyPath: [
+                "url",
+                "cacheName"
+            ]
         });
         objStore.createIndex("cacheName", "cacheName", {
             unique: false
@@ -35,10 +38,9 @@ class CacheTimestampsModel {
     async setTimestamp(url, timestamp) {
         url = normalizeURL(url);
         const entry = {
-            url,
-            timestamp,
             cacheName: this._cacheName,
-            id: this._getId(url)
+            url,
+            timestamp
         };
         const db = await this.getDb();
         const tx = db.transaction(CACHE_OBJECT_STORE, "readwrite", {
@@ -49,35 +51,31 @@ class CacheTimestampsModel {
     }
     async getTimestamp(url) {
         const db = await this.getDb();
-        const entry = await db.get(CACHE_OBJECT_STORE, this._getId(url));
+        const entry = await db.get(CACHE_OBJECT_STORE, [
+            this._cacheName,
+            normalizeURL(url)
+        ]);
         return entry?.timestamp;
     }
     async expireEntries(minTimestamp, maxCount) {
         const db = await this.getDb();
-        let cursor = await db.transaction(CACHE_OBJECT_STORE).store.index("timestamp").openCursor(null, "prev");
-        const entriesToDelete = [];
+        let cursor = await db.transaction(CACHE_OBJECT_STORE, "readwrite").store.index("timestamp").openCursor(null, "prev");
+        const urlsDeleted = [];
         let entriesNotDeletedCount = 0;
         while(cursor){
             const result = cursor.value;
             if (result.cacheName === this._cacheName) {
                 if (minTimestamp && result.timestamp < minTimestamp || maxCount && entriesNotDeletedCount >= maxCount) {
-                    entriesToDelete.push(cursor.value);
+                    cursor.delete();
+                    urlsDeleted.push(result.url);
                 } else {
                     entriesNotDeletedCount++;
                 }
             }
             cursor = await cursor.continue();
         }
-        const urlsDeleted = [];
-        for (const entry of entriesToDelete){
-            await db.delete(CACHE_OBJECT_STORE, entry.id);
-            urlsDeleted.push(entry.url);
-        }
         return urlsDeleted;
     }
-    _getId(url) {
-        return `${this._cacheName}|${normalizeURL(url)}`;
-    }
     async getDb() {
         if (!this._db) {
             this._db = await openDB(DB_NAME, 1, {
@@ -161,7 +159,7 @@ class CacheExpiration {
         this._isRunning = false;
         if (this._rerunRequested) {
             this._rerunRequested = false;
-            dontWaitFor(this.expireEntries());
+            void this.expireEntries();
         }
     }
     async updateTimestamp(url) {
@@ -191,27 +189,26 @@ class CacheExpiration {
     }
     async delete() {
         this._rerunRequested = false;
-        await this._timestampModel.expireEntries(Infinity);
+        await this._timestampModel.expireEntries(Number.POSITIVE_INFINITY);
     }
 }
 
 class ExpirationPlugin {
     _config;
-    _maxAgeSeconds;
     _cacheExpirations;
     constructor(config = {}){
         if (process.env.NODE_ENV !== "production") {
             if (!(config.maxEntries || config.maxAgeSeconds)) {
                 throw new SerwistError("max-entries-or-age-required", {
                     moduleName: "@serwist/expiration",
-                    className: "Plugin",
+                    className: "ExpirationPlugin",
                     funcName: "constructor"
                 });
             }
             if (config.maxEntries) {
                 assert.isType(config.maxEntries, "number", {
                     moduleName: "@serwist/expiration",
-                    className: "Plugin",
+                    className: "ExpirationPlugin",
                     funcName: "constructor",
                     paramName: "config.maxEntries"
                 });
@@ -219,16 +216,26 @@ class ExpirationPlugin {
             if (config.maxAgeSeconds) {
                 assert.isType(config.maxAgeSeconds, "number", {
                     moduleName: "@serwist/expiration",
-                    className: "Plugin",
+                    className: "ExpirationPlugin",
                     funcName: "constructor",
                     paramName: "config.maxAgeSeconds"
                 });
             }
+            if (config.maxAgeFrom) {
+                assert.isType(config.maxAgeFrom, "string", {
+                    moduleName: "@serwist/expiration",
+                    className: "ExpirationPlugin",
+                    funcName: "constructor",
+                    paramName: "config.maxAgeFrom"
+                });
+            }
         }
         this._config = config;
-        this._maxAgeSeconds = config.maxAgeSeconds;
         this._cacheExpirations = new Map();
-        if (config.purgeOnQuotaError) {
+        if (!this._config.maxAgeFrom) {
+            this._config.maxAgeFrom = "last-fetched";
+        }
+        if (this._config.purgeOnQuotaError) {
             registerQuotaErrorCallback(()=>this.deleteCacheAndMetadata());
         }
     }
@@ -243,37 +250,44 @@ class ExpirationPlugin {
         }
         return cacheExpiration;
     }
-    cachedResponseWillBeUsed = async ({ event, request, cacheName, cachedResponse })=>{
+    cachedResponseWillBeUsed({ event, cacheName, request, cachedResponse }) {
         if (!cachedResponse) {
             return null;
         }
         const isFresh = this._isResponseDateFresh(cachedResponse);
         const cacheExpiration = this._getCacheExpiration(cacheName);
-        dontWaitFor(cacheExpiration.expireEntries());
-        const updateTimestampDone = cacheExpiration.updateTimestamp(request.url);
-        if (event) {
-            try {
-                event.waitUntil(updateTimestampDone);
-            } catch (error) {
-                if (process.env.NODE_ENV !== "production") {
-                    if ("request" in event) {
-                        logger.warn(`Unable to ensure service worker stays alive when updating cache entry for '${getFriendlyURL(event.request.url)}'.`);
-                    }
+        const isMaxAgeFromLastUsed = this._config.maxAgeFrom === "last-used";
+        const done = (async ()=>{
+            if (isMaxAgeFromLastUsed) {
+                await cacheExpiration.updateTimestamp(request.url);
+            }
+            await cacheExpiration.expireEntries();
+        })();
+        try {
+            event.waitUntil(done);
+        } catch (error) {
+            if (process.env.NODE_ENV !== "production") {
+                if (event instanceof FetchEvent) {
+                    logger.warn(`Unable to ensure service worker stays alive when updating cache entry for '${getFriendlyURL(event.request.url)}'.`);
                 }
             }
         }
         return isFresh ? cachedResponse : null;
-    };
+    }
     _isResponseDateFresh(cachedResponse) {
-        if (!this._maxAgeSeconds) {
+        const isMaxAgeFromLastUsed = this._config.maxAgeFrom === "last-used";
+        if (isMaxAgeFromLastUsed) {
+            return true;
+        }
+        const now = Date.now();
+        if (!this._config.maxAgeSeconds) {
             return true;
         }
         const dateHeaderTimestamp = this._getDateHeaderTimestamp(cachedResponse);
         if (dateHeaderTimestamp === null) {
             return true;
         }
-        const now = Date.now();
-        return dateHeaderTimestamp >= now - this._maxAgeSeconds * 1000;
+        return dateHeaderTimestamp >= now - this._config.maxAgeSeconds * 1000;
     }
     _getDateHeaderTimestamp(cachedResponse) {
         if (!cachedResponse.headers.has("date")) {
@@ -287,7 +301,7 @@ class ExpirationPlugin {
         }
         return headerTime;
     }
-    cacheDidUpdate = async ({ cacheName, request })=>{
+    async cacheDidUpdate({ cacheName, request }) {
         if (process.env.NODE_ENV !== "production") {
             assert.isType(cacheName, "string", {
                 moduleName: "@serwist/expiration",
@@ -305,7 +319,7 @@ class ExpirationPlugin {
         const cacheExpiration = this._getCacheExpiration(cacheName);
         await cacheExpiration.updateTimestamp(request.url);
         await cacheExpiration.expireEntries();
-    };
+    }
     async deleteCacheAndMetadata() {
         for (const [cacheName, cacheExpiration] of this._cacheExpirations){
             await self.caches.delete(cacheName);

package/dist/models/CacheTimestampsModel.d.ts

@@ -3,7 +3,7 @@
  *
  * @private
  */
-declare class CacheTimestampsModel {
+export declare class CacheTimestampsModel {
     private readonly _cacheName;
     private _db;
     /**
@@ -55,14 +55,6 @@ declare class CacheTimestampsModel {
      * @private
      */
     expireEntries(minTimestamp: number, maxCount?: number): Promise<string[]>;
-    /**
-     * Takes a URL and returns an ID that will be unique in the object store.
-     *
-     * @param url
-     * @returns
-     * @private
-     */
-    private _getId;
     /**
      * Returns an open connection to the database.
      *
@@ -70,5 +62,4 @@ declare class CacheTimestampsModel {
      */
     private getDb;
 }
-export { CacheTimestampsModel };
 //# sourceMappingURL=CacheTimestampsModel.d.ts.map

package/dist/models/CacheTimestampsModel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"CacheTimestampsModel.d.ts","sourceRoot":"","sources":["../../src/models/CacheTimestampsModel.ts"],"names":[],"mappings":"AAoCA;;;;GAIG;AACH,cAAM,oBAAoB;IACxB,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,GAAG,CAA4C;IAEvD;;;;;OAKG;gBACS,SAAS,EAAE,MAAM;IAI7B;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAgBlB;;;;;;OAMG;IACH,OAAO,CAAC,yBAAyB;IAOjC;;;;;OAKG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAoBjE;;;;;;OAMG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAM5D;;;;;;;;;OASG;IACG,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IA2C/E;;;;;;OAMG;IACH,OAAO,CAAC,MAAM;IAOd;;;;OAIG;YACW,KAAK;CAQpB;AAED,OAAO,EAAE,oBAAoB,EAAE,CAAC"}
+{"version":3,"file":"CacheTimestampsModel.d.ts","sourceRoot":"","sources":["../../src/models/CacheTimestampsModel.ts"],"names":[],"mappings":"AAmCA;;;;GAIG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAS;IACpC,OAAO,CAAC,GAAG,CAA4C;IAEvD;;;;;OAKG;gBACS,SAAS,EAAE,MAAM;IAI7B;;;;;;OAMG;IACH,OAAO,CAAC,UAAU;IAYlB;;;;;;OAMG;IACH,OAAO,CAAC,yBAAyB;IAOjC;;;;;OAKG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBjE;;;;;;OAMG;IACG,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC;IAM5D;;;;;;;;;OASG;IACG,aAAa,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAyB/E;;;;OAIG;YACW,KAAK;CAQpB"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serwist/expiration",
-  "version": "9.0.0-preview.14",
+  "version": "9.0.0-preview.16",
   "type": "module",
   "description": "A module that expires cached responses based on age or maximum number of entries.",
   "files": [
@@ -30,12 +30,12 @@
   },
   "dependencies": {
     "idb": "8.0.0",
-    "@serwist/core": "9.0.0-preview.14"
+    "@serwist/core": "9.0.0-preview.16"
   },
   "devDependencies": {
     "rollup": "4.13.0",
-    "typescript": "5.5.0-dev.20240312",
-    "@serwist/constants": "9.0.0-preview.14"
+    "typescript": "5.5.0-dev.20240323",
+    "@serwist/constants": "9.0.0-preview.16"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"

package/src/CacheExpiration.ts

@@ -6,7 +6,7 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { assert, SerwistError, dontWaitFor, logger } from "@serwist/core/internal";
+import { assert, SerwistError, logger } from "@serwist/core/internal";
 
 import { CacheTimestampsModel } from "./models/CacheTimestampsModel.js";
 
@@ -131,7 +131,7 @@ export class CacheExpiration {
     this._isRunning = false;
     if (this._rerunRequested) {
       this._rerunRequested = false;
-      dontWaitFor(this.expireEntries());
+      void this.expireEntries();
     }
   }
 
@@ -187,6 +187,6 @@ export class CacheExpiration {
     // Make sure we don't attempt another rerun if we're called in the middle of
     // a cache expiration.
     this._rerunRequested = false;
-    await this._timestampModel.expireEntries(Infinity); // Expires all.
+    await this._timestampModel.expireEntries(Number.POSITIVE_INFINITY); // Expires all.
   }
 }

package/src/ExpirationPlugin.ts

@@ -6,9 +6,9 @@
   https://opensource.org/licenses/MIT.
 */
 
-import type { SerwistPlugin } from "@serwist/core";
+import type { CacheDidUpdateCallbackParam, CachedResponseWillBeUsedCallbackParam, SerwistPlugin } from "@serwist/core";
 import { registerQuotaErrorCallback } from "@serwist/core";
-import { assert, SerwistError, dontWaitFor, getFriendlyURL, logger, privateCacheNames } from "@serwist/core/internal";
+import { assert, SerwistError, getFriendlyURL, logger, privateCacheNames } from "@serwist/core/internal";
 
 import { CacheExpiration } from "./CacheExpiration.js";
 
@@ -19,9 +19,16 @@ export interface ExpirationPluginOptions {
    */
   maxEntries?: number;
   /**
-   * The maximum age of an entry before it's treated as stale and removed.
+   * The maximum number of seconds before an entry is treated as stale and removed.
    */
   maxAgeSeconds?: number;
+  /**
+   * Determines whether `maxAgeSeconds` should be calculated from when an
+   * entry was last fetched or when it was last used.
+   *
+   * @default "last-fetched"
+   */
+  maxAgeFrom?: "last-fetched" | "last-used";
   /**
    * The [`CacheQueryOptions`](https://developer.mozilla.org/en-US/docs/Web/API/Cache/delete#Parameters)
    * that will be used when calling `delete()` on the cache.
@@ -56,7 +63,6 @@ export interface ExpirationPluginOptions {
  */
 export class ExpirationPlugin implements SerwistPlugin {
   private readonly _config: ExpirationPluginOptions;
-  private readonly _maxAgeSeconds?: number;
   private _cacheExpirations: Map<string, CacheExpiration>;
 
   /**
@@ -67,7 +73,7 @@ export class ExpirationPlugin implements SerwistPlugin {
       if (!(config.maxEntries || config.maxAgeSeconds)) {
         throw new SerwistError("max-entries-or-age-required", {
           moduleName: "@serwist/expiration",
-          className: "Plugin",
+          className: "ExpirationPlugin",
           funcName: "constructor",
         });
       }
@@ -75,7 +81,7 @@ export class ExpirationPlugin implements SerwistPlugin {
       if (config.maxEntries) {
         assert!.isType(config.maxEntries, "number", {
           moduleName: "@serwist/expiration",
-          className: "Plugin",
+          className: "ExpirationPlugin",
           funcName: "constructor",
           paramName: "config.maxEntries",
         });
@@ -84,18 +90,30 @@ export class ExpirationPlugin implements SerwistPlugin {
       if (config.maxAgeSeconds) {
         assert!.isType(config.maxAgeSeconds, "number", {
           moduleName: "@serwist/expiration",
-          className: "Plugin",
+          className: "ExpirationPlugin",
           funcName: "constructor",
           paramName: "config.maxAgeSeconds",
         });
       }
+
+      if (config.maxAgeFrom) {
+        assert!.isType(config.maxAgeFrom, "string", {
+          moduleName: "@serwist/expiration",
+          className: "ExpirationPlugin",
+          funcName: "constructor",
+          paramName: "config.maxAgeFrom",
+        });
+      }
     }
 
     this._config = config;
-    this._maxAgeSeconds = config.maxAgeSeconds;
     this._cacheExpirations = new Map();
 
-    if (config.purgeOnQuotaError) {
+    if (!this._config.maxAgeFrom) {
+      this._config.maxAgeFrom = "last-fetched";
+    }
+
+    if (this._config.purgeOnQuotaError) {
       registerQuotaErrorCallback(() => this.deleteCacheAndMetadata());
     }
   }
@@ -130,11 +148,11 @@ export class ExpirationPlugin implements SerwistPlugin {
    * older than the configured `maxAgeSeconds`.
    *
    * @param options
-   * @returns Either the `cachedResponse`, if it's fresh, or `null` if the `Response`
-   * is older than `maxAgeSeconds`.
+   * @returns `cachedResponse` if it is fresh and `null` if it is stale or
+   * not available.
    * @private
    */
-  cachedResponseWillBeUsed: SerwistPlugin["cachedResponseWillBeUsed"] = async ({ event, request, cacheName, cachedResponse }) => {
+  cachedResponseWillBeUsed({ event, cacheName, request, cachedResponse }: CachedResponseWillBeUsedCallbackParam) {
     if (!cachedResponse) {
       return null;
     }
@@ -144,28 +162,32 @@ export class ExpirationPlugin implements SerwistPlugin {
     // Expire entries to ensure that even if the expiration date has
     // expired, it'll only be used once.
     const cacheExpiration = this._getCacheExpiration(cacheName);
-    dontWaitFor(cacheExpiration.expireEntries());
 
-    // Update the metadata for the request URL to the current timestamp,
-    // but don't `await` it as we don't want to block the response.
-    const updateTimestampDone = cacheExpiration.updateTimestamp(request.url);
-    if (event) {
-      try {
-        event.waitUntil(updateTimestampDone);
-      } catch (error) {
-        if (process.env.NODE_ENV !== "production") {
-          // The event may not be a fetch event; only log the URL if it is.
-          if ("request" in event) {
-            logger.warn(
-              `Unable to ensure service worker stays alive when updating cache entry for '${getFriendlyURL((event as FetchEvent).request.url)}'.`,
-            );
-          }
+    const isMaxAgeFromLastUsed = this._config.maxAgeFrom === "last-used";
+
+    const done = (async () => {
+      // Update the metadata for the request URL to the current timestamp.
+      // Only applies if `maxAgeFrom` is `"last-used"`, since the current
+      // lifecycle callback is `cachedResponseWillBeUsed`.
+      // This needs to be called before `expireEntries()` so as to avoid
+      // this URL being marked as expired.
+      if (isMaxAgeFromLastUsed) {
+        await cacheExpiration.updateTimestamp(request.url);
+      }
+      await cacheExpiration.expireEntries();
+    })();
+    try {
+      event.waitUntil(done);
+    } catch (error) {
+      if (process.env.NODE_ENV !== "production") {
+        if (event instanceof FetchEvent) {
+          logger.warn(`Unable to ensure service worker stays alive when updating cache entry for '${getFriendlyURL(event.request.url)}'.`);
         }
       }
     }
 
     return isFresh ? cachedResponse : null;
-  };
+  }
 
   /**
    * @param cachedResponse
@@ -173,12 +195,17 @@ export class ExpirationPlugin implements SerwistPlugin {
    * @private
    */
   private _isResponseDateFresh(cachedResponse: Response): boolean {
-    if (!this._maxAgeSeconds) {
-      // We aren't expiring by age, so return true, it's fresh
+    const isMaxAgeFromLastUsed = this._config.maxAgeFrom === "last-used";
+    // If `maxAgeFrom` is `"last-used"`, the `Date` header doesn't really
+    // matter since it is about when the response was created.
+    if (isMaxAgeFromLastUsed) {
       return true;
     }
-
-    // Check if the 'date' header will suffice a quick expiration check.
+    const now = Date.now();
+    if (!this._config.maxAgeSeconds) {
+      return true;
+    }
+    // Check if the `Date` header will suffice a quick expiration check.
     // See https://github.com/GoogleChromeLabs/sw-toolbox/issues/164 for
     // discussion.
     const dateHeaderTimestamp = this._getDateHeaderTimestamp(cachedResponse);
@@ -186,16 +213,13 @@ export class ExpirationPlugin implements SerwistPlugin {
       // Unable to parse date, so assume it's fresh.
       return true;
     }
-
-    // If we have a valid headerTime, then our response is fresh iff the
+    // If we have a valid headerTime, then our response is fresh if the
     // headerTime plus maxAgeSeconds is greater than the current time.
-    const now = Date.now();
-    return dateHeaderTimestamp >= now - this._maxAgeSeconds * 1000;
+    return dateHeaderTimestamp >= now - this._config.maxAgeSeconds * 1000;
   }
 
   /**
-   * This method will extract the data header and parse it into a useful
-   * value.
+   * Extracts the `Date` header and parse it into an useful value.
    *
    * @param cachedResponse
    * @returns
@@ -206,11 +230,11 @@ export class ExpirationPlugin implements SerwistPlugin {
       return null;
     }
 
-    const dateHeader = cachedResponse.headers.get("date");
-    const parsedDate = new Date(dateHeader!);
+    const dateHeader = cachedResponse.headers.get("date")!;
+    const parsedDate = new Date(dateHeader);
     const headerTime = parsedDate.getTime();
 
-    // If the Date header was invalid for some reason, parsedDate.getTime()
+    // If the `Date` header is invalid for some reason, `parsedDate.getTime()`
     // will return NaN.
     if (Number.isNaN(headerTime)) {
       return null;
@@ -226,7 +250,7 @@ export class ExpirationPlugin implements SerwistPlugin {
    * @param options
    * @private
    */
-  cacheDidUpdate: SerwistPlugin["cacheDidUpdate"] = async ({ cacheName, request }) => {
+  async cacheDidUpdate({ cacheName, request }: CacheDidUpdateCallbackParam) {
     if (process.env.NODE_ENV !== "production") {
       assert!.isType(cacheName, "string", {
         moduleName: "@serwist/expiration",
@@ -245,7 +269,7 @@ export class ExpirationPlugin implements SerwistPlugin {
     const cacheExpiration = this._getCacheExpiration(cacheName);
     await cacheExpiration.updateTimestamp(request.url);
     await cacheExpiration.expireEntries();
-  };
+  }
 
   /**
    * Deletes the underlying `Cache` instance associated with this instance and the metadata

package/src/models/CacheTimestampsModel.ts

@@ -20,7 +20,6 @@ const normalizeURL = (unNormalizedUrl: string) => {
 };
 
 interface CacheTimestampsModelEntry {
-  id: string;
   cacheName: string;
   url: string;
   timestamp: number;
@@ -28,7 +27,7 @@ interface CacheTimestampsModelEntry {
 
 interface CacheDbSchema extends DBSchema {
   "cache-entries": {
-    key: string;
+    key: [string, string];
     value: CacheTimestampsModelEntry;
     indexes: { cacheName: string; timestamp: number };
   };
@@ -39,7 +38,7 @@ interface CacheDbSchema extends DBSchema {
  *
  * @private
  */
-class CacheTimestampsModel {
+export class CacheTimestampsModel {
   private readonly _cacheName: string;
   private _db: IDBPDatabase<CacheDbSchema> | null = null;
 
@@ -61,12 +60,8 @@ class CacheTimestampsModel {
    * @private
    */
   private _upgradeDb(db: IDBPDatabase<CacheDbSchema>) {
-    // TODO(philipwalton): EdgeHTML doesn't support arrays as a keyPath, so we
-    // have to use the `id` keyPath here and create our own values (a
-    // concatenation of `url + cacheName`) instead of simply using
-    // `keyPath: ['url', 'cacheName']`, which is supported in other browsers.
     const objStore = db.createObjectStore(CACHE_OBJECT_STORE, {
-      keyPath: "id",
+      keyPath: ["url", "cacheName"],
     });
 
     // TODO(philipwalton): once we don't have to support EdgeHTML, we can
@@ -99,15 +94,11 @@ class CacheTimestampsModel {
   async setTimestamp(url: string, timestamp: number): Promise<void> {
     url = normalizeURL(url);
 
-    const entry: CacheTimestampsModelEntry = {
+    const entry = {
+      cacheName: this._cacheName,
       url,
       timestamp,
-      cacheName: this._cacheName,
-      // Creating an ID from the URL and cache name won't be necessary once
-      // Edge switches to Chromium and all browsers we support work with
-      // array keyPaths.
-      id: this._getId(url),
-    };
+    } satisfies CacheTimestampsModelEntry;
     const db = await this.getDb();
     const tx = db.transaction(CACHE_OBJECT_STORE, "readwrite", {
       durability: "relaxed",
@@ -125,7 +116,7 @@ class CacheTimestampsModel {
    */
   async getTimestamp(url: string): Promise<number | undefined> {
     const db = await this.getDb();
-    const entry = await db.get(CACHE_OBJECT_STORE, this._getId(url));
+    const entry = await db.get(CACHE_OBJECT_STORE, [this._cacheName, normalizeURL(url)]);
     return entry?.timestamp;
   }
 
@@ -141,8 +132,8 @@ class CacheTimestampsModel {
    */
   async expireEntries(minTimestamp: number, maxCount?: number): Promise<string[]> {
     const db = await this.getDb();
-    let cursor = await db.transaction(CACHE_OBJECT_STORE).store.index("timestamp").openCursor(null, "prev");
-    const entriesToDelete: CacheTimestampsModelEntry[] = [];
+    let cursor = await db.transaction(CACHE_OBJECT_STORE, "readwrite").store.index("timestamp").openCursor(null, "prev");
+    const urlsDeleted: string[] = [];
     let entriesNotDeletedCount = 0;
     while (cursor) {
       const result = cursor.value;
@@ -152,16 +143,8 @@ class CacheTimestampsModel {
         // Delete an entry if it's older than the max age or
         // if we already have the max number allowed.
         if ((minTimestamp && result.timestamp < minTimestamp) || (maxCount && entriesNotDeletedCount >= maxCount)) {
-          // TODO(philipwalton): we should be able to delete the
-          // entry right here, but doing so causes an iteration
-          // bug in Safari stable (fixed in TP). Instead we can
-          // store the keys of the entries to delete, and then
-          // delete the separate transactions.
-          // https://github.com/GoogleChrome/workbox/issues/1978
-          // cursor.delete();
-
-          // We only need to return the URL, not the whole entry.
-          entriesToDelete.push(cursor.value);
+          cursor.delete();
+          urlsDeleted.push(result.url);
         } else {
           entriesNotDeletedCount++;
         }
@@ -169,33 +152,9 @@ class CacheTimestampsModel {
       cursor = await cursor.continue();
     }
 
-    // TODO(philipwalton): once the Safari bug in the following issue is fixed,
-    // we should be able to remove this loop and do the entry deletion in the
-    // cursor loop above:
-    // https://github.com/GoogleChrome/workbox/issues/1978
-    const urlsDeleted: string[] = [];
-    for (const entry of entriesToDelete) {
-      await db.delete(CACHE_OBJECT_STORE, entry.id);
-      urlsDeleted.push(entry.url);
-    }
-
     return urlsDeleted;
   }
 
-  /**
-   * Takes a URL and returns an ID that will be unique in the object store.
-   *
-   * @param url
-   * @returns
-   * @private
-   */
-  private _getId(url: string): string {
-    // Creating an ID from the URL and cache name won't be necessary once
-    // Edge switches to Chromium and all browsers we support work with
-    // array keyPaths.
-    return `${this._cacheName}|${normalizeURL(url)}`;
-  }
-
   /**
    * Returns an open connection to the database.
    *
@@ -210,5 +169,3 @@ class CacheTimestampsModel {
     return this._db;
   }
 }
-
-export { CacheTimestampsModel };