@serwist/precaching 9.0.0-preview.0 → 9.0.0-preview.10

package/dist/precache.d.ts

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

package/dist/precache.d.ts.map

@@ -1 +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"}
+{"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,eAAO,MAAM,QAAQ,YAAa,CAAC,aAAa,GAAG,MAAM,CAAC,EAAE,KAAG,IAG9D,CAAC"}

package/dist/precacheAndRoute.d.ts

@@ -10,6 +10,5 @@ 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: (PrecacheEntry | string)[], options?: PrecacheRouteOptions): void;
-export { precacheAndRoute };
+export declare const precacheAndRoute: (entries: (PrecacheEntry | string)[], options?: PrecacheRouteOptions) => void;
 //# sourceMappingURL=precacheAndRoute.d.ts.map

package/dist/precacheAndRoute.d.ts.map

@@ -1 +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"}
+{"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,eAAO,MAAM,gBAAgB,YAAa,CAAC,aAAa,GAAG,MAAM,CAAC,EAAE,YAAY,oBAAoB,KAAG,IAGtG,CAAC"}

package/dist/utils/deleteOutdatedCaches.d.ts

@@ -14,6 +14,5 @@
  * @returns A list of all the cache names that were deleted.
  * @private
  */
-declare const deleteOutdatedCaches: (currentPrecacheName: string, substringToFind?: string) => Promise<string[]>;
-export { deleteOutdatedCaches };
+export declare const deleteOutdatedCaches: (currentPrecacheName: string, substringToFind?: string) => Promise<string[]>;
 //# sourceMappingURL=deleteOutdatedCaches.d.ts.map

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

@@ -1 +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"}
+{"version":3,"file":"deleteOutdatedCaches.d.ts","sourceRoot":"","sources":["../../src/utils/deleteOutdatedCaches.ts"],"names":[],"mappings":"AAaA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,oBAAoB,wBAA+B,MAAM,oBAAmB,MAAM,KAAuB,QAAQ,MAAM,EAAE,CAUrI,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@serwist/precaching",
-  "version": "9.0.0-preview.0",
+  "version": "9.0.0-preview.10",
   "type": "module",
   "description": "This module efficiently precaches assets.",
   "files": [
@@ -28,14 +28,15 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@serwist/core": "9.0.0-preview.0",
-    "@serwist/routing": "9.0.0-preview.0",
-    "@serwist/strategies": "9.0.0-preview.0"
+    "@serwist/core": "9.0.0-preview.10",
+    "@serwist/routing": "9.0.0-preview.10",
+    "@serwist/strategies": "9.0.0-preview.10"
   },
   "devDependencies": {
     "rollup": "4.9.6",
-    "typescript": "5.4.0-dev.20240203",
-    "@serwist/constants": "9.0.0-preview.0"
+    "typescript": "5.4.0-dev.20240206",
+    "@serwist/constants": "9.0.0-preview.10",
+    "@serwist/utils": "9.0.0-preview.10"
   },
   "peerDependencies": {
     "typescript": ">=5.0.0"

package/src/PrecacheController.ts

@@ -9,6 +9,7 @@
 import type { RouteHandlerCallback, SerwistPlugin } from "@serwist/core";
 import { assert, SerwistError, logger, privateCacheNames, waitUntil } from "@serwist/core/internal";
 import type { Strategy } from "@serwist/strategies";
+import { parallel } from "@serwist/utils";
 
 import { PrecacheStrategy } from "./PrecacheStrategy.js";
 import type { CleanupResult, InstallResult, PrecacheEntry } from "./_types.js";
@@ -19,7 +20,7 @@ import { printCleanupDetails } from "./utils/printCleanupDetails.js";
 import { printInstallDetails } from "./utils/printInstallDetails.js";
 
 // Give TypeScript the correct global.
-declare let self: ServiceWorkerGlobalScope;
+declare const self: ServiceWorkerGlobalScope;
 
 interface PrecacheControllerOptions {
   /**
@@ -36,13 +37,21 @@ interface PrecacheControllerOptions {
    * a precache miss.
    */
   fallbackToNetwork?: boolean;
+  /**
+   * A number of how many precache requests should be made concurrently.
+   * By default, this value is set to 1, but this can be overriden by
+   * setting this option or `self.__WB_CONCURRENT_PRECACHING`. The former takes
+   * precedence over the latter.
+   */
+  concurrentPrecaching?: number;
 }
 
 /**
  * Performs efficient precaching of assets.
  */
-class PrecacheController {
+export class PrecacheController {
   private _installAndActiveListenersAdded?: boolean;
+  private _concurrentPrecaching: number | undefined;
   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();
@@ -53,12 +62,13 @@ class PrecacheController {
    *
    * @param options
    */
-  constructor({ cacheName, plugins = [], fallbackToNetwork = true }: PrecacheControllerOptions = {}) {
+  constructor({ cacheName, plugins = [], fallbackToNetwork = true, concurrentPrecaching }: PrecacheControllerOptions = {}) {
     this._strategy = new PrecacheStrategy({
       cacheName: privateCacheNames.getPrecacheName(cacheName),
       plugins: [...plugins, new PrecacheCacheKeyPlugin({ precacheController: this })],
       fallbackToNetwork,
     });
+    this._concurrentPrecaching = concurrentPrecaching;
 
     // Bind the install and activate methods to the instance.
     this.install = this.install.bind(this);
@@ -165,15 +175,20 @@ class PrecacheController {
    * @returns
    */
   install(event: ExtendableEvent): Promise<InstallResult> {
-    // waitUntil returns Promise<any>
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    return waitUntil(event, async () => {
+    return waitUntil<InstallResult>(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) {
+      let concurrents = this._concurrentPrecaching;
+
+      if (concurrents === undefined) {
+        if (!("__WB_CONCURRENT_PRECACHING" in globalThis)) {
+          self.__WB_CONCURRENT_PRECACHING = 1;
+        }
+        concurrents = self.__WB_CONCURRENT_PRECACHING;
+      }
+
+      await parallel(concurrents, Array.from(this._urlsToCacheKeys.entries()), async ([url, cacheKey]) => {
         const integrity = this._cacheKeysToIntegrities.get(cacheKey);
         const cacheMode = this._urlsToCacheModes.get(url);
 
@@ -190,7 +205,7 @@ class PrecacheController {
             event,
           }),
         );
-      }
+      });
 
       const { updatedURLs, notUpdatedURLs } = installReportPlugin;
 
@@ -213,26 +228,25 @@ class PrecacheController {
    * @returns
    */
   activate(event: ExtendableEvent): Promise<CleanupResult> {
-    // waitUntil returns Promise<any>
-    // eslint-disable-next-line @typescript-eslint/no-unsafe-return
-    return waitUntil(event, async () => {
+    return waitUntil<CleanupResult>(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 = [];
+      const deletedCacheRequests: string[] = [];
+
       for (const request of currentlyCachedRequests) {
         if (!expectedCacheKeys.has(request.url)) {
           await cache.delete(request);
-          deletedURLs.push(request.url);
+          deletedCacheRequests.push(request.url);
         }
       }
 
       if (process.env.NODE_ENV !== "production") {
-        printCleanupDetails(deletedURLs);
+        printCleanupDetails(deletedCacheRequests);
       }
 
-      return { deletedURLs };
+      return { deletedCacheRequests };
     });
   }
 
@@ -327,5 +341,3 @@ class PrecacheController {
     };
   }
 }
-
-export { PrecacheController };

package/src/PrecacheFallbackPlugin.ts

@@ -6,28 +6,39 @@
   https://opensource.org/licenses/MIT.
 */
 
-import type { SerwistPlugin } from "@serwist/core";
+import type { HandlerDidErrorCallbackParam, SerwistPlugin } from "@serwist/core";
 
 import type { PrecacheController } from "./PrecacheController.js";
 import { getOrCreatePrecacheController } from "./utils/getOrCreatePrecacheController.js";
 
-interface PrecacheFallbackPluginOptions {
+export interface PrecacheFallbackEntry {
   /**
-   * A precached URL to use as the fallback
+   * A function that checks whether the fallback entry can be used
+   * for a request.
+   */
+  matcher: (param: HandlerDidErrorCallbackParam) => boolean;
+  /**
+   * A precached URL to be used as a fallback.
+   */
+  url: string;
+}
+
+export interface PrecacheFallbackPluginOptions {
+  /**
+   * Precached URLs to use as the fallback
    * if the associated strategy can't generate a response.
    */
-  fallbackURL: string;
+  fallbackUrls: (string | PrecacheFallbackEntry)[];
   /**
-   * An optional
-   * PrecacheController instance. If not provided, the default
-   * PrecacheController will be used.
+   * 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.
+ * `PrecacheFallbackPlugin` allows you to specify offline fallbacks
+ * 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
@@ -37,25 +48,39 @@ interface PrecacheFallbackPluginOptions {
  * 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;
+export class PrecacheFallbackPlugin implements SerwistPlugin {
+  private readonly _fallbackUrls: (string | PrecacheFallbackEntry)[];
   private readonly _precacheController: PrecacheController;
 
   /**
-   * Constructs a new PrecacheFallbackPlugin with the associated fallbackURL.
+   * Constructs a new `PrecacheFallbackPlugin` with the associated `fallbackUrls`.
    *
    * @param config
    */
-  constructor({ fallbackURL, precacheController }: PrecacheFallbackPluginOptions) {
-    this._fallbackURL = fallbackURL;
+  constructor({ fallbackUrls, precacheController }: PrecacheFallbackPluginOptions) {
+    this._fallbackUrls = fallbackUrls;
     this._precacheController = precacheController || getOrCreatePrecacheController();
   }
 
   /**
-   * @returns The precache response for the fallback URL.
+   * @returns The precache response for one of the fallback URLs, or `undefined` if
+   * nothing satisfies the conditions.
    * @private
    */
-  handlerDidError: SerwistPlugin["handlerDidError"] = () => this._precacheController.matchPrecache(this._fallbackURL);
+  async handlerDidError(param: HandlerDidErrorCallbackParam) {
+    for (const fallback of this._fallbackUrls) {
+      if (typeof fallback === "string") {
+        const fallbackResponse = await this._precacheController.matchPrecache(fallback);
+        if (fallbackResponse !== undefined) {
+          return fallbackResponse;
+        }
+      } else if (fallback.matcher(param)) {
+        const fallbackResponse = await this._precacheController.matchPrecache(fallback.url);
+        if (fallbackResponse !== undefined) {
+          return fallbackResponse;
+        }
+      }
+    }
+    return undefined;
+  }
 }
-
-export { PrecacheFallbackPlugin };

package/src/addRoute.ts

@@ -23,11 +23,9 @@ import { getOrCreatePrecacheController } from "./utils/getOrCreatePrecacheContro
  *
  * @param options See the `@serwist/precaching.PrecacheRoute` options.
  */
-function addRoute(options?: PrecacheRouteOptions): void {
+export const addRoute = (options?: PrecacheRouteOptions): void => {
   const precacheController = getOrCreatePrecacheController();
 
   const precacheRoute = new PrecacheRoute(precacheController, options);
   registerRoute(precacheRoute);
-}
-
-export { addRoute };
+};

package/src/cleanupOutdatedCaches.ts

@@ -10,25 +10,24 @@ import { logger, privateCacheNames } from "@serwist/core/internal";
 
 import { deleteOutdatedCaches } from "./utils/deleteOutdatedCaches.js";
 
+declare const self: ServiceWorkerGlobalScope;
+
 /**
  * Adds an `activate` event listener which will clean up incompatible
  * precaches that were created by older versions of Serwist.
  */
-function cleanupOutdatedCaches(): void {
-  // See https://github.com/Microsoft/TypeScript/issues/28357#issuecomment-436484705
-  self.addEventListener("activate", ((event: ExtendableEvent) => {
+export const cleanupOutdatedCaches = (): void => {
+  self.addEventListener("activate", (event: ExtendableEvent) => {
     const cacheName = privateCacheNames.getPrecacheName();
 
     event.waitUntil(
       deleteOutdatedCaches(cacheName).then((cachesDeleted) => {
         if (process.env.NODE_ENV !== "production") {
           if (cachesDeleted.length > 0) {
-            logger.log("The following out-of-date precaches were cleaned up " + "automatically:", cachesDeleted);
+            logger.log("The following out-of-date precaches were cleaned up automatically:", cachesDeleted);
           }
         }
       }),
     );
-  }) as EventListener);
-}
-
-export { cleanupOutdatedCaches };
+  });
+};

package/src/createHandlerBoundToURL.ts

@@ -24,9 +24,7 @@ import { getOrCreatePrecacheController } from "./utils/getOrCreatePrecacheContro
  * response from the network if there's a precache miss.
  * @return
  */
-function createHandlerBoundToURL(url: string): RouteHandlerCallback {
+export const createHandlerBoundToURL = (url: string): RouteHandlerCallback => {
   const precacheController = getOrCreatePrecacheController();
   return precacheController.createHandlerBoundToURL(url);
-}
-
-export { createHandlerBoundToURL };
+};

package/src/index.ts

@@ -8,6 +8,7 @@
 
 import { PrecacheController } from "./PrecacheController.js";
 import { PrecacheFallbackPlugin } from "./PrecacheFallbackPlugin.js";
+import type { PrecacheFallbackEntry, PrecacheFallbackPluginOptions } from "./PrecacheFallbackPlugin.js";
 import { PrecacheRoute } from "./PrecacheRoute.js";
 import { PrecacheStrategy } from "./PrecacheStrategy.js";
 import { addPlugins } from "./addPlugins.js";
@@ -45,4 +46,6 @@ export {
   PrecacheStrategy,
 };
 
-export * from "./_types.js";
+export type * from "./_types.js";
+
+export type { PrecacheFallbackPluginOptions, PrecacheFallbackEntry };

package/src/precache.ts

@@ -25,9 +25,7 @@ import { getOrCreatePrecacheController } from "./utils/getOrCreatePrecacheContro
  *
  * @param entries Array of entries to precache.
  */
-function precache(entries: (PrecacheEntry | string)[]): void {
+export const precache = (entries: (PrecacheEntry | string)[]): void => {
   const precacheController = getOrCreatePrecacheController();
   precacheController.precache(entries);
-}
-
-export { precache };
+};

package/src/precacheAndRoute.ts

@@ -21,9 +21,7 @@ import { precache } from "./precache.js";
  * @param entries Array of entries to precache.
  * @param options See the `@serwist/precaching.PrecacheRoute` options.
  */
-function precacheAndRoute(entries: (PrecacheEntry | string)[], options?: PrecacheRouteOptions): void {
+export const precacheAndRoute = (entries: (PrecacheEntry | string)[], options?: PrecacheRouteOptions): void => {
   precache(entries);
   addRoute(options);
-}
-
-export { precacheAndRoute };
+};

package/src/utils/deleteOutdatedCaches.ts

@@ -27,7 +27,7 @@ const SUBSTRING_TO_FIND = "-precache-";
  * @returns A list of all the cache names that were deleted.
  * @private
  */
-const deleteOutdatedCaches = async (currentPrecacheName: string, substringToFind: string = SUBSTRING_TO_FIND): Promise<string[]> => {
+export const deleteOutdatedCaches = async (currentPrecacheName: string, substringToFind: string = SUBSTRING_TO_FIND): Promise<string[]> => {
   const cacheNames = await self.caches.keys();
 
   const cacheNamesToDelete = cacheNames.filter((cacheName) => {
@@ -38,5 +38,3 @@ const deleteOutdatedCaches = async (currentPrecacheName: string, substringToFind
 
   return cacheNamesToDelete;
 };
-
-export { deleteOutdatedCaches };