@serwist/precaching 9.0.0-preview.1 → 9.0.0-preview.3

package/dist/PrecacheFallbackPlugin.d.ts

@@ -1,21 +1,31 @@
-import type { SerwistPlugin } from "@serwist/core";
+import type { HandlerDidErrorCallbackParam, SerwistPlugin } from "@serwist/core";
 import type { PrecacheController } from "./PrecacheController.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
@@ -25,20 +35,20 @@ interface PrecacheFallbackPluginOptions {
  * constructor, the default instance will be used. Generally speaking, most
  * developers will end up using the default.
  */
-declare class PrecacheFallbackPlugin implements SerwistPlugin {
-    private readonly _fallbackURL;
+export declare class PrecacheFallbackPlugin implements SerwistPlugin {
+    private readonly _fallbackUrls;
     private readonly _precacheController;
     /**
-     * Constructs a new PrecacheFallbackPlugin with the associated fallbackURL.
+     * Constructs a new `PrecacheFallbackPlugin` with the associated `fallbackUrls`.
      *
      * @param config
      */
-    constructor({ fallbackURL, precacheController }: PrecacheFallbackPluginOptions);
+    constructor({ fallbackUrls, precacheController }: PrecacheFallbackPluginOptions);
     /**
-     * @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"];
+    handlerDidError(param: HandlerDidErrorCallbackParam): Promise<Response | undefined>;
 }
-export { PrecacheFallbackPlugin };
 //# sourceMappingURL=PrecacheFallbackPlugin.d.ts.map

package/dist/PrecacheFallbackPlugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"PrecacheFallbackPlugin.d.ts","sourceRoot":"","sources":["../src/PrecacheFallbackPlugin.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEnD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,UAAU,6BAA6B;IACrC;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED;;;;;;;;;;;GAWG;AACH,cAAM,sBAAuB,YAAW,aAAa;IACnD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD;;;;OAIG;gBACS,EAAE,WAAW,EAAE,kBAAkB,EAAE,EAAE,6BAA6B;IAK9E;;;OAGG;IACH,eAAe,EAAE,aAAa,CAAC,iBAAiB,CAAC,CAAmE;CACrH;AAED,OAAO,EAAE,sBAAsB,EAAE,CAAC"}
+{"version":3,"file":"PrecacheFallbackPlugin.d.ts","sourceRoot":"","sources":["../src/PrecacheFallbackPlugin.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,4BAA4B,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAEjF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAGlE,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,OAAO,EAAE,CAAC,KAAK,EAAE,4BAA4B,KAAK,OAAO,CAAC;IAC1D;;OAEG;IACH,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,6BAA6B;IAC5C;;;OAGG;IACH,YAAY,EAAE,CAAC,MAAM,GAAG,qBAAqB,CAAC,EAAE,CAAC;IACjD;;;OAGG;IACH,kBAAkB,CAAC,EAAE,kBAAkB,CAAC;CACzC;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,sBAAuB,YAAW,aAAa;IAC1D,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqC;IACnE,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAqB;IAEzD;;;;OAIG;gBACS,EAAE,YAAY,EAAE,kBAAkB,EAAE,EAAE,6BAA6B;IAK/E;;;;OAIG;IACG,eAAe,CAAC,KAAK,EAAE,4BAA4B;CAgB1D"}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 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";
@@ -21,5 +22,6 @@ import { precacheAndRoute } from "./precacheAndRoute.js";
  * interface.
  */
 export { addPlugins, addRoute, cleanupOutdatedCaches, createHandlerBoundToURL, getCacheKeyForURL, matchPrecache, precache, precacheAndRoute, PrecacheController, PrecacheFallbackPlugin, PrecacheRoute, PrecacheStrategy, };
-export * from "./_types.js";
+export type * from "./_types.js";
+export type { PrecacheFallbackPluginOptions, PrecacheFallbackEntry };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;;;;;;;GASG;AAEH,OAAO,EACL,UAAU,EACV,QAAQ,EACR,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,EACb,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,gBAAgB,GACjB,CAAC;AAEF,cAAc,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AACrE,OAAO,KAAK,EAAE,qBAAqB,EAAE,6BAA6B,EAAE,MAAM,6BAA6B,CAAC;AACxG,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAEzD;;;;;;;;;GASG;AAEH,OAAO,EACL,UAAU,EACV,QAAQ,EACR,qBAAqB,EACrB,uBAAuB,EACvB,iBAAiB,EACjB,aAAa,EACb,QAAQ,EACR,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,gBAAgB,GACjB,CAAC;AAEF,mBAAmB,aAAa,CAAC;AAEjC,YAAY,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,CAAC"}

package/dist/index.js

@@ -399,13 +399,28 @@ const getOrCreatePrecacheController = ()=>{
 };
 
 class PrecacheFallbackPlugin {
-    _fallbackURL;
+    _fallbackUrls;
     _precacheController;
-    constructor({ fallbackURL, precacheController }){
-        this._fallbackURL = fallbackURL;
+    constructor({ fallbackUrls, precacheController }){
+        this._fallbackUrls = fallbackUrls;
         this._precacheController = precacheController || getOrCreatePrecacheController();
     }
-    handlerDidError = ()=>this._precacheController.matchPrecache(this._fallbackURL);
+    async handlerDidError(param) {
+        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;
+    }
 }
 
 function removeIgnoredSearchParams(urlObject, ignoreURLParametersMatching = []) {

package/package.json

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

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/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 };