@serwist/precaching 8.4.4 → 9.0.0-preview.1

package/dist/matchPrecache.d.ts

@@ -12,3 +12,4 @@
  */
 declare function matchPrecache(request: string | Request): Promise<Response | undefined>;
 export { matchPrecache };
+//# sourceMappingURL=matchPrecache.d.ts.map

package/dist/matchPrecache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"matchPrecache.d.ts","sourceRoot":"","sources":["../src/matchPrecache.ts"],"names":[],"mappings":"AAUA;;;;;;;;;;;GAWG;AACH,iBAAS,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC,QAAQ,GAAG,SAAS,CAAC,CAG/E;AAED,OAAO,EAAE,aAAa,EAAE,CAAC"}

package/dist/precache.d.ts

@@ -15,5 +15,6 @@ import type { PrecacheEntry } from "./_types.js";
  *
  * @param entries Array of entries to precache.
  */
-declare function precache(entries: Array<PrecacheEntry | string>): void;
+declare function precache(entries: (PrecacheEntry | string)[]): void;
 export { precache };
+//# sourceMappingURL=precache.d.ts.map

package/dist/precache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precache.d.ts","sourceRoot":"","sources":["../src/precache.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD;;;;;;;;;;;;;;;GAeG;AACH,iBAAS,QAAQ,CAAC,OAAO,EAAE,CAAC,aAAa,GAAG,MAAM,CAAC,EAAE,GAAG,IAAI,CAG3D;AAED,OAAO,EAAE,QAAQ,EAAE,CAAC"}

package/dist/precacheAndRoute.d.ts

@@ -10,5 +10,6 @@ import type { PrecacheEntry, PrecacheRouteOptions } from "./_types.js";
  * @param entries Array of entries to precache.
  * @param options See the `@serwist/precaching.PrecacheRoute` options.
  */
-declare function precacheAndRoute(entries: Array<PrecacheEntry | string>, options?: PrecacheRouteOptions): void;
+declare function precacheAndRoute(entries: (PrecacheEntry | string)[], options?: PrecacheRouteOptions): void;
 export { precacheAndRoute };
+//# sourceMappingURL=precacheAndRoute.d.ts.map

package/dist/precacheAndRoute.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"precacheAndRoute.d.ts","sourceRoot":"","sources":["../src/precacheAndRoute.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAIvE;;;;;;;;;;GAUG;AACH,iBAAS,gBAAgB,CAAC,OAAO,EAAE,CAAC,aAAa,GAAG,MAAM,CAAC,EAAE,EAAE,OAAO,CAAC,EAAE,oBAAoB,GAAG,IAAI,CAGnG;AAED,OAAO,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/utils/PrecacheCacheKeyPlugin.d.ts

@@ -14,3 +14,4 @@ declare class PrecacheCacheKeyPlugin implements SerwistPlugin {
     cacheKeyWillBeUsed: SerwistPlugin["cacheKeyWillBeUsed"];
 }
 export { PrecacheCacheKeyPlugin };
+//# sourceMappingURL=PrecacheCacheKeyPlugin.d.ts.map

package/dist/utils/PrecacheCacheKeyPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrecacheCacheKeyPlugin.d.ts","sourceRoot":"","sources":["../../src/utils/PrecacheCacheKeyPlugin.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAA8B,MAAM,eAAe,CAAC;AAE/E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAEnE;;;;;GAKG;AACH,cAAM,sBAAuB,YAAW,aAAa;IACnD,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;gBAE7C,EAAE,kBAAkB,EAAE,EAAE;QAAE,kBAAkB,EAAE,kBAAkB,CAAA;KAAE;IAI9E,kBAAkB,EAAE,aAAa,CAAC,oBAAoB,CAAC,CAOrD;CACH;AAED,OAAO,EAAE,sBAAsB,EAAE,CAAC"}

package/dist/utils/PrecacheInstallReportPlugin.d.ts

@@ -12,3 +12,4 @@ declare class PrecacheInstallReportPlugin implements SerwistPlugin {
     cachedResponseWillBeUsed: SerwistPlugin["cachedResponseWillBeUsed"];
 }
 export { PrecacheInstallReportPlugin };
+//# sourceMappingURL=PrecacheInstallReportPlugin.d.ts.map

package/dist/utils/PrecacheInstallReportPlugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PrecacheInstallReportPlugin.d.ts","sourceRoot":"","sources":["../../src/utils/PrecacheInstallReportPlugin.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAA8B,MAAM,eAAe,CAAC;AAE/E;;;;;GAKG;AACH,cAAM,2BAA4B,YAAW,aAAa;IACxD,WAAW,EAAE,MAAM,EAAE,CAAM;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAM;IAE9B,gBAAgB,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAKjD;IAEF,wBAAwB,EAAE,aAAa,CAAC,0BAA0B,CAAC,CAkBjE;CACH;AAED,OAAO,EAAE,2BAA2B,EAAE,CAAC"}

package/dist/utils/createCacheKey.d.ts

@@ -13,3 +13,4 @@ interface CacheKey {
  */
 export declare function createCacheKey(entry: PrecacheEntry | string): CacheKey;
 export {};
+//# sourceMappingURL=createCacheKey.d.ts.map

package/dist/utils/createCacheKey.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"createCacheKey.d.ts","sourceRoot":"","sources":["../../src/utils/createCacheKey.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,UAAU,QAAQ;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAKD;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,GAAG,QAAQ,CAuCtE"}

package/dist/utils/deleteOutdatedCaches.d.ts

@@ -16,3 +16,4 @@
  */
 declare const deleteOutdatedCaches: (currentPrecacheName: string, substringToFind?: string) => Promise<string[]>;
 export { deleteOutdatedCaches };
+//# sourceMappingURL=deleteOutdatedCaches.d.ts.map

package/dist/utils/deleteOutdatedCaches.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deleteOutdatedCaches.d.ts","sourceRoot":"","sources":["../../src/utils/deleteOutdatedCaches.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;GAeG;AACH,QAAA,MAAM,oBAAoB,wBAA+B,MAAM,oBAAmB,MAAM,KAAuB,QAAQ,MAAM,EAAE,CAU9H,CAAC;AAEF,OAAO,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/utils/generateURLVariations.d.ts

@@ -9,3 +9,4 @@ import type { PrecacheRouteOptions } from "../_types.js";
  * @private
  */
 export declare function generateURLVariations(url: string, { ignoreURLParametersMatching, directoryIndex, cleanURLs, urlManipulation, }?: PrecacheRouteOptions): Generator<string, void, unknown>;
+//# sourceMappingURL=generateURLVariations.d.ts.map

package/dist/utils/generateURLVariations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generateURLVariations.d.ts","sourceRoot":"","sources":["../../src/utils/generateURLVariations.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGzD;;;;;;;;GAQG;AACH,wBAAiB,qBAAqB,CACpC,GAAG,EAAE,MAAM,EACX,EACE,2BAAmD,EACnD,cAA6B,EAC7B,SAAgB,EAChB,eAAe,GAChB,GAAE,oBAAyB,GAC3B,SAAS,CAAC,MAAM,EAAE,IAAI,EAAE,OAAO,CAAC,CA0BlC"}

package/dist/utils/getCacheKeyForURL.d.ts

@@ -11,3 +11,4 @@ import type { PrecacheRouteOptions } from "../_types.js";
  * @private
  */
 export declare const getCacheKeyForURL: (url: string, options: PrecacheRouteOptions) => string | undefined;
+//# sourceMappingURL=getCacheKeyForURL.d.ts.map

package/dist/utils/getCacheKeyForURL.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getCacheKeyForURL.d.ts","sourceRoot":"","sources":["../../src/utils/getCacheKeyForURL.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAIzD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,iBAAiB,QAAS,MAAM,WAAW,oBAAoB,KAAG,MAAM,GAAG,SAYvF,CAAC"}

package/dist/utils/getOrCreatePrecacheController.d.ts

@@ -4,3 +4,4 @@ import { PrecacheController } from "../PrecacheController.js";
  * @private
  */
 export declare const getOrCreatePrecacheController: () => PrecacheController;
+//# sourceMappingURL=getOrCreatePrecacheController.d.ts.map

package/dist/utils/getOrCreatePrecacheController.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getOrCreatePrecacheController.d.ts","sourceRoot":"","sources":["../../src/utils/getOrCreatePrecacheController.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAI9D;;;GAGG;AACH,eAAO,MAAM,6BAA6B,QAAO,kBAKhD,CAAC"}

package/dist/utils/printCleanupDetails.d.ts

@@ -3,3 +3,4 @@
  * @private
  */
 export declare function printCleanupDetails(deletedURLs: string[]): void;
+//# sourceMappingURL=printCleanupDetails.d.ts.map

package/dist/utils/printCleanupDetails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"printCleanupDetails.d.ts","sourceRoot":"","sources":["../../src/utils/printCleanupDetails.ts"],"names":[],"mappings":"AA0BA;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,IAAI,CAO/D"}

package/dist/utils/printInstallDetails.d.ts

@@ -4,3 +4,4 @@
  * @private
  */
 export declare function printInstallDetails(urlsToPrecache: string[], urlsAlreadyPrecached: string[]): void;
+//# sourceMappingURL=printInstallDetails.d.ts.map

package/dist/utils/printInstallDetails.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"printInstallDetails.d.ts","sourceRoot":"","sources":["../../src/utils/printInstallDetails.ts"],"names":[],"mappings":"AA8BA;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,EAAE,EAAE,oBAAoB,EAAE,MAAM,EAAE,GAAG,IAAI,CAiBlG"}

package/dist/utils/removeIgnoredSearchParams.d.ts

@@ -9,3 +9,4 @@
  * @private
  */
 export declare function removeIgnoredSearchParams(urlObject: URL, ignoreURLParametersMatching?: RegExp[]): URL;
+//# sourceMappingURL=removeIgnoredSearchParams.d.ts.map

package/dist/utils/removeIgnoredSearchParams.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"removeIgnoredSearchParams.d.ts","sourceRoot":"","sources":["../../src/utils/removeIgnoredSearchParams.ts"],"names":[],"mappings":"AAQA;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,GAAG,EAAE,2BAA2B,GAAE,MAAM,EAAO,GAAG,GAAG,CAUzG"}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@serwist/precaching",
-  "version": "8.4.4",
+  "version": "9.0.0-preview.1",
   "type": "module",
   "description": "This module efficiently precaches assets.",
   "files": [
-    "dist",
-    "!dist/**/dts"
+    "src",
+    "dist"
   ],
   "keywords": [
     "serwist",
@@ -18,30 +18,32 @@
   "repository": "serwist/serwist",
   "bugs": "https://github.com/serwist/serwist/issues",
   "homepage": "https://serwist.pages.dev",
-  "module": "./dist/index.js",
-  "main": "./dist/index.cjs",
+  "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
-      }
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     },
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@serwist/core": "8.4.4",
-    "@serwist/routing": "8.4.4",
-    "@serwist/strategies": "8.4.4"
+    "@serwist/core": "9.0.0-preview.1",
+    "@serwist/routing": "9.0.0-preview.1",
+    "@serwist/strategies": "9.0.0-preview.1"
   },
   "devDependencies": {
-    "rollup": "4.9.1",
-    "@serwist/constants": "8.4.4"
+    "rollup": "4.9.6",
+    "typescript": "5.4.0-dev.20240203",
+    "@serwist/constants": "9.0.0-preview.1"
+  },
+  "peerDependencies": {
+    "typescript": ">=5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "rimraf dist && cross-env NODE_ENV=production rollup --config rollup.config.js",

package/src/PrecacheController.ts

@@ -0,0 +1,331 @@
+/*
+  Copyright 2019 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/
+
+import type { RouteHandlerCallback, SerwistPlugin } from "@serwist/core";
+import { assert, SerwistError, logger, privateCacheNames, waitUntil } from "@serwist/core/internal";
+import type { Strategy } from "@serwist/strategies";
+
+import { PrecacheStrategy } from "./PrecacheStrategy.js";
+import type { CleanupResult, InstallResult, PrecacheEntry } from "./_types.js";
+import { PrecacheCacheKeyPlugin } from "./utils/PrecacheCacheKeyPlugin.js";
+import { PrecacheInstallReportPlugin } from "./utils/PrecacheInstallReportPlugin.js";
+import { createCacheKey } from "./utils/createCacheKey.js";
+import { printCleanupDetails } from "./utils/printCleanupDetails.js";
+import { printInstallDetails } from "./utils/printInstallDetails.js";
+
+// Give TypeScript the correct global.
+declare let self: ServiceWorkerGlobalScope;
+
+interface PrecacheControllerOptions {
+  /**
+   * The cache to use for precaching.
+   */
+  cacheName?: string;
+  /**
+   * Plugins to use when precaching as well as responding to fetch
+   * events for precached assets.
+   */
+  plugins?: SerwistPlugin[];
+  /**
+   * Whether to attempt to get the response from the network if there's
+   * a precache miss.
+   */
+  fallbackToNetwork?: boolean;
+}
+
+/**
+ * Performs efficient precaching of assets.
+ */
+class PrecacheController {
+  private _installAndActiveListenersAdded?: boolean;
+  private readonly _strategy: Strategy;
+  private readonly _urlsToCacheKeys: Map<string, string> = new Map();
+  private readonly _urlsToCacheModes: Map<string, "reload" | "default" | "no-store" | "no-cache" | "force-cache" | "only-if-cached"> = new Map();
+  private readonly _cacheKeysToIntegrities: Map<string, string> = new Map();
+
+  /**
+   * Create a new PrecacheController.
+   *
+   * @param options
+   */
+  constructor({ cacheName, plugins = [], fallbackToNetwork = true }: PrecacheControllerOptions = {}) {
+    this._strategy = new PrecacheStrategy({
+      cacheName: privateCacheNames.getPrecacheName(cacheName),
+      plugins: [...plugins, new PrecacheCacheKeyPlugin({ precacheController: this })],
+      fallbackToNetwork,
+    });
+
+    // Bind the install and activate methods to the instance.
+    this.install = this.install.bind(this);
+    this.activate = this.activate.bind(this);
+  }
+
+  /**
+   * The strategy created by this controller and
+   * used to cache assets and respond to fetch events.
+   */
+  get strategy(): Strategy {
+    return this._strategy;
+  }
+
+  /**
+   * Adds items to the precache list, removing any duplicates and
+   * stores the files in the precache cache when the service
+   * worker installs.
+   *
+   * This method can be called multiple times.
+   *
+   * @param entries Array of entries to precache.
+   */
+  precache(entries: (PrecacheEntry | string)[]): void {
+    this.addToCacheList(entries);
+
+    if (!this._installAndActiveListenersAdded) {
+      self.addEventListener("install", this.install);
+      self.addEventListener("activate", this.activate);
+      this._installAndActiveListenersAdded = true;
+    }
+  }
+
+  /**
+   * This method will add items to the precache list, removing duplicates
+   * and ensuring the information is valid.
+   *
+   * @param entries Array of entries to precache.
+   */
+  addToCacheList(entries: (PrecacheEntry | string)[]): void {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isArray(entries, {
+        moduleName: "@serwist/precaching",
+        className: "PrecacheController",
+        funcName: "addToCacheList",
+        paramName: "entries",
+      });
+    }
+
+    const urlsToWarnAbout: string[] = [];
+    for (const entry of entries) {
+      // See https://github.com/GoogleChrome/workbox/issues/2259
+      if (typeof entry === "string") {
+        urlsToWarnAbout.push(entry);
+      } else if (entry && entry.revision === undefined) {
+        urlsToWarnAbout.push(entry.url);
+      }
+
+      const { cacheKey, url } = createCacheKey(entry);
+      const cacheMode = typeof entry !== "string" && entry.revision ? "reload" : "default";
+
+      if (this._urlsToCacheKeys.has(url) && this._urlsToCacheKeys.get(url) !== cacheKey) {
+        throw new SerwistError("add-to-cache-list-conflicting-entries", {
+          firstEntry: this._urlsToCacheKeys.get(url),
+          secondEntry: cacheKey,
+        });
+      }
+
+      if (typeof entry !== "string" && entry.integrity) {
+        if (this._cacheKeysToIntegrities.has(cacheKey) && this._cacheKeysToIntegrities.get(cacheKey) !== entry.integrity) {
+          throw new SerwistError("add-to-cache-list-conflicting-integrities", {
+            url,
+          });
+        }
+        this._cacheKeysToIntegrities.set(cacheKey, entry.integrity);
+      }
+
+      this._urlsToCacheKeys.set(url, cacheKey);
+      this._urlsToCacheModes.set(url, cacheMode);
+
+      if (urlsToWarnAbout.length > 0) {
+        const warningMessage = `Serwist is precaching URLs without revision info: ${urlsToWarnAbout.join(
+          ", ",
+        )}\nThis is generally NOT safe. Learn more at https://bit.ly/wb-precache`;
+        if (process.env.NODE_ENV === "production") {
+          // Use console directly to display this warning without bloating
+          // bundle sizes by pulling in all of the logger codebase in prod.
+          console.warn(warningMessage);
+        } else {
+          logger.warn(warningMessage);
+        }
+      }
+    }
+  }
+
+  /**
+   * Precaches new and updated assets. Call this method from the service worker
+   * install event.
+   *
+   * Note: this method calls `event.waitUntil()` for you, so you do not need
+   * to call it yourself in your event handlers.
+   *
+   * @param event
+   * @returns
+   */
+  install(event: ExtendableEvent): Promise<InstallResult> {
+    // waitUntil returns Promise<any>
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return waitUntil(event, async () => {
+      const installReportPlugin = new PrecacheInstallReportPlugin();
+      this.strategy.plugins.push(installReportPlugin);
+
+      // Cache entries one at a time.
+      // See https://github.com/GoogleChrome/workbox/issues/2528
+      for (const [url, cacheKey] of this._urlsToCacheKeys) {
+        const integrity = this._cacheKeysToIntegrities.get(cacheKey);
+        const cacheMode = this._urlsToCacheModes.get(url);
+
+        const request = new Request(url, {
+          integrity,
+          cache: cacheMode,
+          credentials: "same-origin",
+        });
+
+        await Promise.all(
+          this.strategy.handleAll({
+            params: { cacheKey },
+            request,
+            event,
+          }),
+        );
+      }
+
+      const { updatedURLs, notUpdatedURLs } = installReportPlugin;
+
+      if (process.env.NODE_ENV !== "production") {
+        printInstallDetails(updatedURLs, notUpdatedURLs);
+      }
+
+      return { updatedURLs, notUpdatedURLs };
+    });
+  }
+
+  /**
+   * Deletes assets that are no longer present in the current precache manifest.
+   * Call this method from the service worker activate event.
+   *
+   * Note: this method calls `event.waitUntil()` for you, so you do not need
+   * to call it yourself in your event handlers.
+   *
+   * @param event
+   * @returns
+   */
+  activate(event: ExtendableEvent): Promise<CleanupResult> {
+    // waitUntil returns Promise<any>
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+    return waitUntil(event, async () => {
+      const cache = await self.caches.open(this.strategy.cacheName);
+      const currentlyCachedRequests = await cache.keys();
+      const expectedCacheKeys = new Set(this._urlsToCacheKeys.values());
+
+      const deletedURLs = [];
+      for (const request of currentlyCachedRequests) {
+        if (!expectedCacheKeys.has(request.url)) {
+          await cache.delete(request);
+          deletedURLs.push(request.url);
+        }
+      }
+
+      if (process.env.NODE_ENV !== "production") {
+        printCleanupDetails(deletedURLs);
+      }
+
+      return { deletedURLs };
+    });
+  }
+
+  /**
+   * Returns a mapping of a precached URL to the corresponding cache key, taking
+   * into account the revision information for the URL.
+   *
+   * @returns A URL to cache key mapping.
+   */
+  getURLsToCacheKeys(): Map<string, string> {
+    return this._urlsToCacheKeys;
+  }
+
+  /**
+   * Returns a list of all the URLs that have been precached by the current
+   * service worker.
+   *
+   * @returns The precached URLs.
+   */
+  getCachedURLs(): string[] {
+    return [...this._urlsToCacheKeys.keys()];
+  }
+
+  /**
+   * Returns the cache key used for storing a given URL. If that URL is
+   * unversioned, like `/index.html', then the cache key will be the original
+   * URL with a search parameter appended to it.
+   *
+   * @param url A URL whose cache key you want to look up.
+   * @returns The versioned URL that corresponds to a cache key
+   * for the original URL, or undefined if that URL isn't precached.
+   */
+  getCacheKeyForURL(url: string): string | undefined {
+    const urlObject = new URL(url, location.href);
+    return this._urlsToCacheKeys.get(urlObject.href);
+  }
+
+  /**
+   * @param url A cache key whose SRI you want to look up.
+   * @returns The subresource integrity associated with the cache key,
+   * or undefined if it's not set.
+   */
+  getIntegrityForCacheKey(cacheKey: string): string | undefined {
+    return this._cacheKeysToIntegrities.get(cacheKey);
+  }
+
+  /**
+   * This acts as a drop-in replacement for
+   * [`cache.match()`](https://developer.mozilla.org/en-US/docs/Web/API/Cache/match)
+   * with the following differences:
+   *
+   * - It knows what the name of the precache is, and only checks in that cache.
+   * - It allows you to pass in an "original" URL without versioning parameters,
+   * and it will automatically look up the correct cache key for the currently
+   * active revision of that URL.
+   *
+   * E.g., `matchPrecache('index.html')` will find the correct precached
+   * response for the currently active service worker, even if the actual cache
+   * key is `'/index.html?__WB_REVISION__=1234abcd'`.
+   *
+   * @param request The key (without revisioning parameters)
+   * to look up in the precache.
+   * @returns
+   */
+  async matchPrecache(request: string | Request): Promise<Response | undefined> {
+    const url = request instanceof Request ? request.url : request;
+    const cacheKey = this.getCacheKeyForURL(url);
+    if (cacheKey) {
+      const cache = await self.caches.open(this.strategy.cacheName);
+      return cache.match(cacheKey);
+    }
+    return undefined;
+  }
+
+  /**
+   * Returns a function that looks up `url` in the precache (taking into
+   * account revision information), and returns the corresponding `Response`.
+   *
+   * @param url The precached URL which will be used to lookup the response.
+   * @return
+   */
+  createHandlerBoundToURL(url: string): RouteHandlerCallback {
+    const cacheKey = this.getCacheKeyForURL(url);
+    if (!cacheKey) {
+      throw new SerwistError("non-precached-url", { url });
+    }
+    return (options) => {
+      options.request = new Request(url);
+      options.params = { cacheKey, ...options.params };
+
+      return this.strategy.handle(options);
+    };
+  }
+}
+
+export { PrecacheController };

package/src/PrecacheFallbackPlugin.ts

@@ -0,0 +1,61 @@
+/*
+  Copyright 2020 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/
+
+import type { SerwistPlugin } from "@serwist/core";
+
+import type { PrecacheController } from "./PrecacheController.js";
+import { getOrCreatePrecacheController } from "./utils/getOrCreatePrecacheController.js";
+
+interface PrecacheFallbackPluginOptions {
+  /**
+   * A precached URL to use as the fallback
+   * if the associated strategy can't generate a response.
+   */
+  fallbackURL: string;
+  /**
+   * An optional
+   * PrecacheController instance. If not provided, the default
+   * PrecacheController will be used.
+   */
+  precacheController?: PrecacheController;
+}
+
+/**
+ * `PrecacheFallbackPlugin` allows you to specify an "offline fallback"
+ * response to be used when a given strategy is unable to generate a response.
+ *
+ * It does this by intercepting the `handlerDidError` plugin callback
+ * and returning a precached response, taking the expected revision parameter
+ * into account automatically.
+ *
+ * Unless you explicitly pass in a `PrecacheController` instance to the
+ * constructor, the default instance will be used. Generally speaking, most
+ * developers will end up using the default.
+ */
+class PrecacheFallbackPlugin implements SerwistPlugin {
+  private readonly _fallbackURL: string;
+  private readonly _precacheController: PrecacheController;
+
+  /**
+   * Constructs a new PrecacheFallbackPlugin with the associated fallbackURL.
+   *
+   * @param config
+   */
+  constructor({ fallbackURL, precacheController }: PrecacheFallbackPluginOptions) {
+    this._fallbackURL = fallbackURL;
+    this._precacheController = precacheController || getOrCreatePrecacheController();
+  }
+
+  /**
+   * @returns The precache response for the fallback URL.
+   * @private
+   */
+  handlerDidError: SerwistPlugin["handlerDidError"] = () => this._precacheController.matchPrecache(this._fallbackURL);
+}
+
+export { PrecacheFallbackPlugin };

package/src/PrecacheRoute.ts

@@ -0,0 +1,50 @@
+/*
+  Copyright 2020 Google LLC
+
+  Use of this source code is governed by an MIT-style
+  license that can be found in the LICENSE file or at
+  https://opensource.org/licenses/MIT.
+*/
+
+import type { RouteMatchCallback, RouteMatchCallbackOptions } from "@serwist/core";
+import { getFriendlyURL, logger } from "@serwist/core/internal";
+import { Route } from "@serwist/routing";
+
+import type { PrecacheController } from "./PrecacheController.js";
+import type { PrecacheRouteOptions } from "./_types.js";
+import { generateURLVariations } from "./utils/generateURLVariations.js";
+
+/**
+ * A subclass of `@serwist/routing.Route` that takes a
+ * `@serwist/precaching.PrecacheController`
+ * instance and uses it to match incoming requests and handle fetching
+ * responses from the precache.
+ */
+class PrecacheRoute extends Route {
+  /**
+   * @param precacheController A `PrecacheController`
+   * instance used to both match requests and respond to fetch events.
+   * @param options Options to control how requests are matched
+   * against the list of precached URLs.
+   */
+  constructor(precacheController: PrecacheController, options?: PrecacheRouteOptions) {
+    const match: RouteMatchCallback = ({ request }: RouteMatchCallbackOptions) => {
+      const urlsToCacheKeys = precacheController.getURLsToCacheKeys();
+      for (const possibleURL of generateURLVariations(request.url, options)) {
+        const cacheKey = urlsToCacheKeys.get(possibleURL);
+        if (cacheKey) {
+          const integrity = precacheController.getIntegrityForCacheKey(cacheKey);
+          return { cacheKey, integrity };
+        }
+      }
+      if (process.env.NODE_ENV !== "production") {
+        logger.debug(`Precaching did not find a match for ${getFriendlyURL(request.url)}`);
+      }
+      return;
+    };
+
+    super(match, precacheController.strategy);
+  }
+}
+
+export { PrecacheRoute };