@serwist/expiration 9.0.0-preview.0 → 9.0.0-preview.1

package/dist/index.js

@@ -9,38 +9,16 @@ const normalizeURL = (unNormalizedUrl)=>{
     url.hash = "";
     return url.href;
 };
-/**
- * Returns the timestamp model.
- *
- * @private
- */ class CacheTimestampsModel {
+class CacheTimestampsModel {
     _cacheName;
     _db = null;
-    /**
-   *
-   * @param cacheName
-   *
-   * @private
-   */ constructor(cacheName){
+    constructor(cacheName){
         this._cacheName = cacheName;
     }
-    /**
-   * Performs an upgrade of indexedDB.
-   *
-   * @param db
-   *
-   * @private
-   */ _upgradeDb(db) {
-        // 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.
+    _upgradeDb(db) {
         const objStore = db.createObjectStore(CACHE_OBJECT_STORE, {
             keyPath: "id"
         });
-        // TODO(philipwalton): once we don't have to support EdgeHTML, we can
-        // create a single index with the keyPath `['cacheName', 'timestamp']`
-        // instead of doing both these indexes.
         objStore.createIndex("cacheName", "cacheName", {
             unique: false
         });
@@ -48,32 +26,18 @@ const normalizeURL = (unNormalizedUrl)=>{
             unique: false
         });
     }
-    /**
-   * Performs an upgrade of indexedDB and deletes deprecated DBs.
-   *
-   * @param db
-   *
-   * @private
-   */ _upgradeDbAndDeleteOldDbs(db) {
+    _upgradeDbAndDeleteOldDbs(db) {
         this._upgradeDb(db);
         if (this._cacheName) {
             void deleteDB(this._cacheName);
         }
     }
-    /**
-   * @param url
-   * @param timestamp
-   *
-   * @private
-   */ async setTimestamp(url, timestamp) {
+    async setTimestamp(url, timestamp) {
         url = normalizeURL(url);
         const entry = {
             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)
         };
         const db = await this.getDb();
@@ -83,47 +47,20 @@ const normalizeURL = (unNormalizedUrl)=>{
         await tx.store.put(entry);
         await tx.done;
     }
-    /**
-   * Returns the timestamp stored for a given URL.
-   *
-   * @param url
-   * @returns
-   * @private
-   */ async getTimestamp(url) {
+    async getTimestamp(url) {
         const db = await this.getDb();
         const entry = await db.get(CACHE_OBJECT_STORE, this._getId(url));
         return entry?.timestamp;
     }
-    /**
-   * Iterates through all the entries in the object store (from newest to
-   * oldest) and removes entries once either `maxCount` is reached or the
-   * entry's timestamp is less than `minTimestamp`.
-   *
-   * @param minTimestamp
-   * @param maxCount
-   * @returns
-   * @private
-   */ async expireEntries(minTimestamp, maxCount) {
+    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 entriesNotDeletedCount = 0;
         while(cursor){
             const result = cursor.value;
-            // TODO(philipwalton): once we can use a multi-key index, we
-            // won't have to check `cacheName` here.
             if (result.cacheName === this._cacheName) {
-                // 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);
                 } else {
                     entriesNotDeletedCount++;
@@ -131,10 +68,6 @@ const normalizeURL = (unNormalizedUrl)=>{
             }
             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 = [];
         for (const entry of entriesToDelete){
             await db.delete(CACHE_OBJECT_STORE, entry.id);
@@ -142,23 +75,10 @@ const normalizeURL = (unNormalizedUrl)=>{
         }
         return urlsDeleted;
     }
-    /**
-   * Takes a URL and returns an ID that will be unique in the object store.
-   *
-   * @param url
-   * @returns
-   * @private
-   */ _getId(url) {
-        // 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.
+    _getId(url) {
         return `${this._cacheName}|${normalizeURL(url)}`;
     }
-    /**
-   * Returns an open connection to the database.
-   *
-   * @private
-   */ async getDb() {
+    async getDb() {
         if (!this._db) {
             this._db = await openDB(DB_NAME, 1, {
                 upgrade: this._upgradeDbAndDeleteOldDbs.bind(this)
@@ -168,11 +88,7 @@ const normalizeURL = (unNormalizedUrl)=>{
     }
 }
 
-/**
- * The `CacheExpiration` class allows you define an expiration and / or
- * limit on the number of responses stored in a
- * [`Cache`](https://developer.mozilla.org/en-US/docs/Web/API/Cache).
- */ class CacheExpiration {
+class CacheExpiration {
     _isRunning = false;
     _rerunRequested = false;
     _maxEntries;
@@ -180,13 +96,7 @@ const normalizeURL = (unNormalizedUrl)=>{
     _matchOptions;
     _cacheName;
     _timestampModel;
-    /**
-   * To construct a new CacheExpiration instance you must provide at least
-   * one of the `config` properties.
-   *
-   * @param cacheName Name of the cache to apply restrictions to.
-   * @param config
-   */ constructor(cacheName, config = {}){
+    constructor(cacheName, config = {}){
         if (process.env.NODE_ENV !== "production") {
             assert.isType(cacheName, "string", {
                 moduleName: "@serwist/expiration",
@@ -224,9 +134,7 @@ const normalizeURL = (unNormalizedUrl)=>{
         this._cacheName = cacheName;
         this._timestampModel = new CacheTimestampsModel(cacheName);
     }
-    /**
-   * Expires entries for the given cache and given criteria.
-   */ async expireEntries() {
+    async expireEntries() {
         if (this._isRunning) {
             this._rerunRequested = true;
             return;
@@ -234,7 +142,6 @@ const normalizeURL = (unNormalizedUrl)=>{
         this._isRunning = true;
         const minTimestamp = this._maxAgeSeconds ? Date.now() - this._maxAgeSeconds * 1000 : 0;
         const urlsExpired = await this._timestampModel.expireEntries(minTimestamp, this._maxEntries);
-        // Delete URLs from the cache
         const cache = await self.caches.open(this._cacheName);
         for (const url of urlsExpired){
             await cache.delete(url, this._matchOptions);
@@ -257,13 +164,7 @@ const normalizeURL = (unNormalizedUrl)=>{
             dontWaitFor(this.expireEntries());
         }
     }
-    /**
-   * Update the timestamp for the given URL. This ensures the when
-   * removing entries based on maximum entries, most recently used
-   * is accurate or when expiring, the timestamp is up-to-date.
-   *
-   * @param url
-   */ async updateTimestamp(url) {
+    async updateTimestamp(url) {
         if (process.env.NODE_ENV !== "production") {
             assert.isType(url, "string", {
                 moduleName: "@serwist/expiration",
@@ -274,17 +175,7 @@ const normalizeURL = (unNormalizedUrl)=>{
         }
         await this._timestampModel.setTimestamp(url, Date.now());
     }
-    /**
-   * Can be used to check if a URL has expired or not before it's used.
-   *
-   * This requires a look up from IndexedDB, so can be slow.
-   *
-   * Note: This method will not remove the cached entry, call
-   * `expireEntries()` to remove indexedDB and Cache entries.
-   *
-   * @param url
-   * @returns
-   */ async isURLExpired(url) {
+    async isURLExpired(url) {
         if (!this._maxAgeSeconds) {
             if (process.env.NODE_ENV !== "production") {
                 throw new SerwistError("expired-test-without-max-age", {
@@ -298,44 +189,17 @@ const normalizeURL = (unNormalizedUrl)=>{
         const expireOlderThan = Date.now() - this._maxAgeSeconds * 1000;
         return timestamp !== undefined ? timestamp < expireOlderThan : true;
     }
-    /**
-   * Removes the IndexedDB object store used to keep track of cache expiration
-   * metadata.
-   */ async delete() {
-        // Make sure we don't attempt another rerun if we're called in the middle of
-        // a cache expiration.
+    async delete() {
         this._rerunRequested = false;
-        await this._timestampModel.expireEntries(Infinity); // Expires all.
+        await this._timestampModel.expireEntries(Infinity);
     }
 }
 
-/**
- * This plugin can be used in a `@serwist/strategies` Strategy to regularly enforce a
- * limit on the age and / or the number of cached requests.
- *
- * It can only be used with Strategy instances that have a
- * [custom `cacheName` property set](/web/tools/workbox/guides/configure-workbox#custom_cache_names_in_strategies).
- * In other words, it can't be used to expire entries in strategy that uses the
- * default runtime cache name.
- *
- * Whenever a cached response is used or updated, this plugin will look
- * at the associated cache and remove any old or extra responses.
- *
- * When using `maxAgeSeconds`, responses may be used *once* after expiring
- * because the expiration clean up will not have occurred until *after* the
- * cached response has been used. If the response has a "Date" header, then
- * a light weight expiration check is performed and the response will not be
- * used immediately.
- *
- * When using `maxEntries`, the entry least-recently requested will be removed
- * from the cache first.
- */ class ExpirationPlugin {
+class ExpirationPlugin {
     _config;
     _maxAgeSeconds;
     _cacheExpirations;
-    /**
-   * @param config
-   */ constructor(config = {}){
+    constructor(config = {}){
         if (process.env.NODE_ENV !== "production") {
             if (!(config.maxEntries || config.maxAgeSeconds)) {
                 throw new SerwistError("max-entries-or-age-required", {
@@ -368,14 +232,7 @@ const normalizeURL = (unNormalizedUrl)=>{
             registerQuotaErrorCallback(()=>this.deleteCacheAndMetadata());
         }
     }
-    /**
-   * A simple helper method to return a CacheExpiration instance for a given
-   * cache name.
-   *
-   * @param cacheName
-   * @returns
-   * @private
-   */ _getCacheExpiration(cacheName) {
+    _getCacheExpiration(cacheName) {
         if (cacheName === privateCacheNames.getRuntimeName()) {
             throw new SerwistError("expire-custom-caches-only");
         }
@@ -386,36 +243,19 @@ const normalizeURL = (unNormalizedUrl)=>{
         }
         return cacheExpiration;
     }
-    /**
-   * A "lifecycle" callback that will be triggered automatically by the
-   * `@serwist/strategies` handlers when a `Response` is about to be returned
-   * from a [Cache](https://developer.mozilla.org/en-US/docs/Web/API/Cache) to
-   * the handler. It allows the `Response` to be inspected for freshness and
-   * prevents it from being used if the `Response`'s `Date` header value is
-   * older than the configured `maxAgeSeconds`.
-   *
-   * @param options
-   * @returns Either the `cachedResponse`, if it's fresh, or `null` if the `Response`
-   * is older than `maxAgeSeconds`.
-   * @private
-   */ cachedResponseWillBeUsed = async ({ event, request, cacheName, cachedResponse })=>{
+    cachedResponseWillBeUsed = async ({ event, request, cacheName, cachedResponse })=>{
         if (!cachedResponse) {
             return null;
         }
         const isFresh = this._isResponseDateFresh(cachedResponse);
-        // 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.request.url)}'.`);
                     }
@@ -424,56 +264,30 @@ const normalizeURL = (unNormalizedUrl)=>{
         }
         return isFresh ? cachedResponse : null;
     };
-    /**
-   * @param cachedResponse
-   * @returns
-   * @private
-   */ _isResponseDateFresh(cachedResponse) {
+    _isResponseDateFresh(cachedResponse) {
         if (!this._maxAgeSeconds) {
-            // We aren't expiring by age, so return true, it's fresh
             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);
         if (dateHeaderTimestamp === null) {
-            // Unable to parse date, so assume it's fresh.
             return true;
         }
-        // If we have a valid headerTime, then our response is fresh iff the
-        // headerTime plus maxAgeSeconds is greater than the current time.
         const now = Date.now();
         return dateHeaderTimestamp >= now - this._maxAgeSeconds * 1000;
     }
-    /**
-   * This method will extract the data header and parse it into a useful
-   * value.
-   *
-   * @param cachedResponse
-   * @returns
-   * @private
-   */ _getDateHeaderTimestamp(cachedResponse) {
+    _getDateHeaderTimestamp(cachedResponse) {
         if (!cachedResponse.headers.has("date")) {
             return null;
         }
         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()
-        // will return NaN.
         if (Number.isNaN(headerTime)) {
             return null;
         }
         return headerTime;
     }
-    /**
-   * A "lifecycle" callback that will be triggered automatically by the
-   * `@serwist/strategies` handlers when an entry is added to a cache.
-   *
-   * @param options
-   * @private
-   */ cacheDidUpdate = async ({ cacheName, request })=>{
+    cacheDidUpdate = async ({ cacheName, request })=>{
         if (process.env.NODE_ENV !== "production") {
             assert.isType(cacheName, "string", {
                 moduleName: "@serwist/expiration",
@@ -492,29 +306,11 @@ const normalizeURL = (unNormalizedUrl)=>{
         await cacheExpiration.updateTimestamp(request.url);
         await cacheExpiration.expireEntries();
     };
-    /**
-   * This is a helper method that performs two operations:
-   *
-   * - Deletes *all* the underlying Cache instances associated with this plugin
-   * instance, by calling caches.delete() on your behalf.
-   * - Deletes the metadata from IndexedDB used to keep track of expiration
-   * details for each Cache instance.
-   *
-   * When using cache expiration, calling this method is preferable to calling
-   * `caches.delete()` directly, since this will ensure that the IndexedDB
-   * metadata is also cleanly removed and open IndexedDB instances are deleted.
-   *
-   * Note that if you're *not* using cache expiration for a given cache, calling
-   * `caches.delete()` and passing in the cache's name should be sufficient.
-   * There is no Serwist-specific method needed for cleanup in that case.
-   */ async deleteCacheAndMetadata() {
-        // Do this one at a time instead of all at once via `Promise.all()` to
-        // reduce the chance of inconsistency if a promise rejects.
+    async deleteCacheAndMetadata() {
         for (const [cacheName, cacheExpiration] of this._cacheExpirations){
             await self.caches.delete(cacheName);
             await cacheExpiration.delete();
         }
-        // Reset this._cacheExpirations to its initial state.
         this._cacheExpirations = new Map();
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serwist/expiration",
-  "version": "9.0.0-preview.0",
+  "version": "9.0.0-preview.1",
   "type": "module",
   "description": "A service worker helper library 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.0"
+    "@serwist/core": "9.0.0-preview.1"
   },
   "devDependencies": {
     "rollup": "4.9.6",
     "typescript": "5.4.0-dev.20240203",
-    "@serwist/constants": "9.0.0-preview.0"
+    "@serwist/constants": "9.0.0-preview.1"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"