serwist 9.1.0-preview.0 → 10.0.0-preview.2

package/src/lib/expiration/ExpirationPlugin.ts

@@ -6,15 +6,15 @@
   https://opensource.org/licenses/MIT.
 */
 
+import { SerwistError } from "#utils/SerwistError.js";
+import { assert } from "#utils/assert.js";
+import { cacheNames as privateCacheNames } from "#utils/cacheNames.js";
+import { getFriendlyURL } from "#utils/getFriendlyURL.js";
+import { logger } from "#utils/logger.js";
 import { registerQuotaErrorCallback } from "../../registerQuotaErrorCallback.js";
-import type { CacheDidUpdateCallbackParam, CachedResponseWillBeUsedCallbackParam, SerwistPlugin } from "../../types.js";
-import { SerwistError } from "../../utils/SerwistError.js";
-import { assert } from "../../utils/assert.js";
-import { cacheNames as privateCacheNames } from "../../utils/cacheNames.js";
-import { getFriendlyURL } from "../../utils/getFriendlyURL.js";
-import { logger } from "../../utils/logger.js";
-import { CacheExpiration } from "./CacheExpiration.js";
+import type { CacheDidUpdateCallbackParam, CachedResponseWillBeUsedCallbackParam, StrategyPlugin } from "../../types.js";
 import type { Strategy } from "../strategies/Strategy.js";
+import { CacheExpiration } from "./CacheExpiration.js";
 
 export interface ExpirationPluginOptions {
   /**
@@ -66,7 +66,7 @@ export interface ExpirationPluginOptions {
  *
  * @see https://serwist.pages.dev/docs/serwist/runtime-caching/plugins/expiration-plugin
  */
-export class ExpirationPlugin implements SerwistPlugin {
+export class ExpirationPlugin implements StrategyPlugin {
   private readonly _config: ExpirationPluginOptions;
   private _cacheExpirations: Map<string, CacheExpiration>;
 

package/src/lib/expiration/index.ts

@@ -0,0 +1,3 @@
+export { CacheExpiration } from "./CacheExpiration.js";
+export type { ExpirationPluginOptions } from "./ExpirationPlugin.js";
+export { ExpirationPlugin } from "./ExpirationPlugin.js";

package/src/lib/googleAnalytics/index.ts

@@ -0,0 +1,2 @@
+export { initializeGoogleAnalytics } from "./initializeGoogleAnalytics.js";
+export type { GoogleAnalyticsInitializeOptions } from "./initializeGoogleAnalytics.js";

package/src/lib/googleAnalytics/initializeGoogleAnalytics.ts

@@ -6,16 +6,16 @@
   https://opensource.org/licenses/MIT.
 */
 
+import { cacheNames as privateCacheNames } from "#utils/cacheNames.js";
+import { getFriendlyURL } from "#utils/getFriendlyURL.js";
+import { logger } from "#utils/logger.js";
 import { Route } from "../../Route.js";
 import type { Serwist } from "../../Serwist.js";
-import { NetworkFirst } from "../../lib/strategies/NetworkFirst.js";
-import { NetworkOnly } from "../../lib/strategies/NetworkOnly.js";
 import type { RouteMatchCallbackOptions } from "../../types.js";
-import { cacheNames as privateCacheNames } from "../../utils/cacheNames.js";
-import { getFriendlyURL } from "../../utils/getFriendlyURL.js";
-import { logger } from "../../utils/logger.js";
 import { BackgroundSyncPlugin } from "../backgroundSync/BackgroundSyncPlugin.js";
 import type { BackgroundSyncQueue, BackgroundSyncQueueEntry } from "../backgroundSync/BackgroundSyncQueue.js";
+import { NetworkFirst } from "../strategies/NetworkFirst.js";
+import { NetworkOnly } from "../strategies/NetworkOnly.js";
 import {
   ANALYTICS_JS_PATH,
   COLLECT_PATHS_REGEX,

package/src/lib/precaching/PrecacheFallbackPlugin.ts

@@ -6,19 +6,20 @@
   https://opensource.org/licenses/MIT.
 */
 
+import type { PrecacheController } from "#lib/controllers/PrecacheController/PrecacheController.js";
 import type { Serwist } from "../../Serwist.js";
-import type { HandlerDidErrorCallbackParam, SerwistPlugin } from "../../types.js";
+import type { HandlerDidErrorCallbackParam, StrategyPlugin } from "../../types.js";
 
 export interface PrecacheFallbackEntry {
+  /**
+   * A precached URL to be used as a fallback.
+   */
+  url: string;
   /**
    * 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 {
@@ -27,10 +28,15 @@ export interface PrecacheFallbackPluginOptions {
    * if the associated strategy can't generate a response.
    */
   fallbackUrls: (string | PrecacheFallbackEntry)[];
+  /**
+   * A {@linkcode PrecacheController} instance.
+   */
+  precacheController: PrecacheController;
   /**
    * A {@linkcode Serwist} instance.
+   * @deprecated Use `precacheController` instead.
    */
-  serwist: Serwist;
+  serwist?: Serwist;
 }
 
 /**
@@ -41,18 +47,23 @@ export interface PrecacheFallbackPluginOptions {
  * and returning a precached response, taking the expected revision parameter
  * into account automatically.
  */
-export class PrecacheFallbackPlugin implements SerwistPlugin {
+export class PrecacheFallbackPlugin implements StrategyPlugin {
   private readonly _fallbackUrls: (string | PrecacheFallbackEntry)[];
-  private readonly _serwist: Serwist;
+  private readonly _precacheController: PrecacheController;
 
   /**
    * Constructs a new instance with the associated `fallbackUrls`.
    *
    * @param config
    */
-  constructor({ fallbackUrls, serwist }: PrecacheFallbackPluginOptions) {
+  constructor({ fallbackUrls, precacheController, serwist }: PrecacheFallbackPluginOptions) {
     this._fallbackUrls = fallbackUrls;
-    this._serwist = serwist;
+    // TODO(ducanhgh): remove in v11.
+    if (!serwist) {
+      this._precacheController = precacheController;
+    } else {
+      this._precacheController = serwist.precache;
+    }
   }
 
   /**
@@ -63,12 +74,12 @@ export class PrecacheFallbackPlugin implements SerwistPlugin {
   async handlerDidError(param: HandlerDidErrorCallbackParam) {
     for (const fallback of this._fallbackUrls) {
       if (typeof fallback === "string") {
-        const fallbackResponse = await this._serwist.matchPrecache(fallback);
+        const fallbackResponse = await this._precacheController.matchPrecache(fallback);
         if (fallbackResponse !== undefined) {
           return fallbackResponse;
         }
       } else if (fallback.matcher(param)) {
-        const fallbackResponse = await this._serwist.matchPrecache(fallback.url);
+        const fallbackResponse = await this._precacheController.matchPrecache(fallback.url);
         if (fallbackResponse !== undefined) {
           return fallbackResponse;
         }

package/src/lib/precaching/index.ts

@@ -0,0 +1,2 @@
+export type { PrecacheFallbackEntry, PrecacheFallbackPluginOptions } from "./PrecacheFallbackPlugin.js";
+export { PrecacheFallbackPlugin } from "./PrecacheFallbackPlugin.js";

package/src/lib/rangeRequests/RangeRequestsPlugin.ts

@@ -6,7 +6,7 @@
   https://opensource.org/licenses/MIT.
 */
 
-import type { SerwistPlugin } from "../../types.js";
+import type { StrategyPlugin } from "../../types.js";
 import { createPartialResponse } from "./createPartialResponse.js";
 
 /**
@@ -15,7 +15,7 @@ import { createPartialResponse } from "./createPartialResponse.js";
  * It does this by intercepting the `cachedResponseWillBeUsed` plugin callback
  * and returning the appropriate subset of the cached response body.
  */
-export class RangeRequestsPlugin implements SerwistPlugin {
+export class RangeRequestsPlugin implements StrategyPlugin {
   /**
    * @param options
    * @returns If request contains a `Range` header, then a
@@ -23,7 +23,7 @@ export class RangeRequestsPlugin implements SerwistPlugin {
    * returned. Otherwise, `cachedResponse` is returned as-is.
    * @private
    */
-  cachedResponseWillBeUsed: SerwistPlugin["cachedResponseWillBeUsed"] = async ({ request, cachedResponse }) => {
+  cachedResponseWillBeUsed: StrategyPlugin["cachedResponseWillBeUsed"] = async ({ request, cachedResponse }) => {
     // Only return a sliced response if there's something valid in the cache,
     // and there's a Range: header in the request.
     if (cachedResponse && request.headers.has("range")) {

package/src/lib/rangeRequests/createPartialResponse.ts

@@ -6,9 +6,9 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "../../utils/SerwistError.js";
-import { assert } from "../../utils/assert.js";
-import { logger } from "../../utils/logger.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { assert } from "#utils/assert.js";
+import { logger } from "#utils/logger.js";
 import { calculateEffectiveBoundaries } from "./utils/calculateEffectiveBoundaries.js";
 import { parseRangeHeader } from "./utils/parseRangeHeader.js";
 

package/src/lib/rangeRequests/index.ts

@@ -0,0 +1,2 @@
+export { RangeRequestsPlugin } from "./RangeRequestsPlugin.js";
+export { createPartialResponse } from "./createPartialResponse.js";

package/src/lib/rangeRequests/utils/calculateEffectiveBoundaries.ts

@@ -6,8 +6,8 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "../../../utils/SerwistError.js";
-import { assert } from "../../../utils/assert.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { assert } from "#utils/assert.js";
 
 /**
  * @param blob A source blob.

package/src/lib/rangeRequests/utils/parseRangeHeader.ts

@@ -6,8 +6,8 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "../../../utils/SerwistError.js";
-import { assert } from "../../../utils/assert.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { assert } from "#utils/assert.js";
 
 /**
  * @param rangeHeader A `Range` header value.

package/src/lib/strategies/CacheFirst.ts

@@ -6,9 +6,9 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "../../utils/SerwistError.js";
-import { assert } from "../../utils/assert.js";
-import { logger } from "../../utils/logger.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { assert } from "#utils/assert.js";
+import { logger } from "#utils/logger.js";
 import { Strategy } from "./Strategy.js";
 import type { StrategyHandler } from "./StrategyHandler.js";
 import { messages } from "./utils/messages.js";

package/src/lib/strategies/CacheOnly.ts

@@ -6,9 +6,9 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "../../utils/SerwistError.js";
-import { assert } from "../../utils/assert.js";
-import { logger } from "../../utils/logger.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { assert } from "#utils/assert.js";
+import { logger } from "#utils/logger.js";
 import { Strategy } from "./Strategy.js";
 import type { StrategyHandler } from "./StrategyHandler.js";
 import { messages } from "./utils/messages.js";

package/src/lib/strategies/NetworkFirst.ts

@@ -6,9 +6,9 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "../../utils/SerwistError.js";
-import { assert } from "../../utils/assert.js";
-import { logger } from "../../utils/logger.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { assert } from "#utils/assert.js";
+import { logger } from "#utils/logger.js";
 import type { StrategyOptions } from "./Strategy.js";
 import { Strategy } from "./Strategy.js";
 import type { StrategyHandler } from "./StrategyHandler.js";

package/src/lib/strategies/NetworkOnly.ts

@@ -6,10 +6,10 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "../../utils/SerwistError.js";
-import { assert } from "../../utils/assert.js";
-import { logger } from "../../utils/logger.js";
-import { timeout } from "../../utils/timeout.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { assert } from "#utils/assert.js";
+import { logger } from "#utils/logger.js";
+import { timeout } from "#utils/timeout.js";
 import type { StrategyOptions } from "./Strategy.js";
 import { Strategy } from "./Strategy.js";
 import type { StrategyHandler } from "./StrategyHandler.js";

package/src/lib/strategies/StaleWhileRevalidate.ts

@@ -6,9 +6,9 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "../../utils/SerwistError.js";
-import { assert } from "../../utils/assert.js";
-import { logger } from "../../utils/logger.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { assert } from "#utils/assert.js";
+import { logger } from "#utils/logger.js";
 import type { StrategyOptions } from "./Strategy.js";
 import { Strategy } from "./Strategy.js";
 import type { StrategyHandler } from "./StrategyHandler.js";

package/src/lib/strategies/Strategy.ts

@@ -6,11 +6,11 @@
   https://opensource.org/licenses/MIT.
 */
 
-import type { HandlerCallbackOptions, RouteHandlerObject, SerwistPlugin } from "../../types.js";
-import { SerwistError } from "../../utils/SerwistError.js";
-import { cacheNames as privateCacheNames } from "../../utils/cacheNames.js";
-import { getFriendlyURL } from "../../utils/getFriendlyURL.js";
-import { logger } from "../../utils/logger.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { cacheNames as privateCacheNames } from "#utils/cacheNames.js";
+import { getFriendlyURL } from "#utils/getFriendlyURL.js";
+import { logger } from "#utils/logger.js";
+import type { HandlerCallbackOptions, RouteHandlerObject, StrategyPlugin } from "../../types.js";
 import { StrategyHandler } from "./StrategyHandler.js";
 
 export interface StrategyOptions {
@@ -21,7 +21,7 @@ export interface StrategyOptions {
   /**
    * [Plugins](https://serwist.pages.dev/docs/serwist/runtime-caching/plugins) to use in conjunction with this caching strategy.
    */
-  plugins?: SerwistPlugin[];
+  plugins?: StrategyPlugin[];
   /**
    * Options passed to [non-navigation](https://github.com/GoogleChrome/workbox/issues/1796) `fetch()` calls made by
    * this strategy.
@@ -42,7 +42,7 @@ export interface StrategyOptions {
  */
 export abstract class Strategy implements RouteHandlerObject {
   cacheName: string;
-  plugins: SerwistPlugin[];
+  plugins: StrategyPlugin[];
   fetchOptions?: RequestInit;
   matchOptions?: CacheQueryOptions;
 

package/src/lib/strategies/StrategyHandler.ts

@@ -6,17 +6,17 @@
   https://opensource.org/licenses/MIT.
 */
 
-import type { HandlerCallbackOptions, MapLikeObject, SerwistPlugin, SerwistPluginCallbackParam } from "../../types.js";
-import { Deferred } from "../../utils/Deferred.js";
-import { SerwistError } from "../../utils/SerwistError.js";
-import { assert } from "../../utils/assert.js";
-import { cacheMatchIgnoreParams } from "../../utils/cacheMatchIgnoreParams.js";
-import { executeQuotaErrorCallbacks } from "../../utils/executeQuotaErrorCallbacks.js";
-import { getFriendlyURL } from "../../utils/getFriendlyURL.js";
-import { logger } from "../../utils/logger.js";
-import { timeout } from "../../utils/timeout.js";
-import type { Strategy } from "./Strategy.js";
+import { Deferred } from "#utils/Deferred.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { assert } from "#utils/assert.js";
+import { cacheMatchIgnoreParams } from "#utils/cacheMatchIgnoreParams.js";
+import { executeQuotaErrorCallbacks } from "#utils/executeQuotaErrorCallbacks.js";
+import { getFriendlyURL } from "#utils/getFriendlyURL.js";
+import { logger } from "#utils/logger.js";
+import { timeout } from "#utils/timeout.js";
 import type { Route } from "../../Route.js";
+import type { HandlerCallbackOptions, MapLikeObject, StrategyPlugin, StrategyPluginCallbackParam } from "../../types.js";
+import type { Strategy } from "./Strategy.js";
 
 function toRequest(input: RequestInfo) {
   return typeof input === "string" ? new Request(input) : input;
@@ -59,8 +59,8 @@ export class StrategyHandler {
   private readonly _strategy: Strategy;
   private readonly _handlerDeferred: Deferred<any>;
   private readonly _extendLifetimePromises: Promise<any>[];
-  private readonly _plugins: SerwistPlugin[];
-  private readonly _pluginStateMap: Map<SerwistPlugin, MapLikeObject>;
+  private readonly _plugins: StrategyPlugin[];
+  private readonly _pluginStateMap: Map<StrategyPlugin, MapLikeObject>;
 
   /**
    * Creates a new instance associated with the passed strategy and event
@@ -405,7 +405,7 @@ export class StrategyHandler {
    * @param name The name of the callback to check for.
    * @returns
    */
-  hasCallback<C extends keyof SerwistPlugin>(name: C): boolean {
+  hasCallback<C extends keyof StrategyPlugin>(name: C): boolean {
     for (const plugin of this._strategy.plugins) {
       if (name in plugin) {
         return true;
@@ -426,10 +426,10 @@ export class StrategyHandler {
    * @param param The object to pass as the first (and only) param when executing each callback. This object will be merged with the
    * current plugin state prior to callback execution.
    */
-  async runCallbacks<C extends keyof NonNullable<SerwistPlugin>>(name: C, param: Omit<SerwistPluginCallbackParam[C], "state">): Promise<void> {
+  async runCallbacks<C extends keyof NonNullable<StrategyPlugin>>(name: C, param: Omit<StrategyPluginCallbackParam[C], "state">): Promise<void> {
     for (const callback of this.iterateCallbacks(name)) {
       // TODO(philipwalton): not sure why `any` is needed. It seems like
-      // this should work with `as SerwistPluginCallbackParam[C]`.
+      // this should work with `as StrategyPluginCallbackParam[C]`.
       await callback(param as any);
     }
   }
@@ -440,18 +440,18 @@ export class StrategyHandler {
    * @param name The name fo the callback to run
    * @returns
    */
-  *iterateCallbacks<C extends keyof SerwistPlugin>(name: C): Generator<NonNullable<SerwistPlugin[C]>> {
+  *iterateCallbacks<C extends keyof StrategyPlugin>(name: C): Generator<NonNullable<StrategyPlugin[C]>> {
     for (const plugin of this._strategy.plugins) {
       if (typeof plugin[name] === "function") {
         const state = this._pluginStateMap.get(plugin);
-        const statefulCallback = (param: Omit<SerwistPluginCallbackParam[C], "state">) => {
+        const statefulCallback = (param: Omit<StrategyPluginCallbackParam[C], "state">) => {
           const statefulParam = { ...param, state };
 
           // TODO(philipwalton): not sure why `any` is needed. It seems like
           // this should work with `as WorkboxPluginCallbackParam[C]`.
           return plugin[name]!(statefulParam as any);
         };
-        yield statefulCallback as NonNullable<SerwistPlugin[C]>;
+        yield statefulCallback as NonNullable<StrategyPlugin[C]>;
       }
     }
   }

package/src/lib/strategies/index.ts

@@ -0,0 +1,10 @@
+export { CacheFirst } from "./CacheFirst.js";
+export { CacheOnly } from "./CacheOnly.js";
+export type { NetworkFirstOptions } from "./NetworkFirst.js";
+export { NetworkFirst } from "./NetworkFirst.js";
+export type { NetworkOnlyOptions } from "./NetworkOnly.js";
+export { NetworkOnly } from "./NetworkOnly.js";
+export { StaleWhileRevalidate } from "./StaleWhileRevalidate.js";
+export type { StrategyOptions } from "./Strategy.js";
+export { Strategy } from "./Strategy.js";
+export { StrategyHandler } from "./StrategyHandler.js";

package/src/lib/strategies/plugins/cacheOkAndOpaquePlugin.ts

@@ -6,9 +6,9 @@
   https://opensource.org/licenses/MIT.
 */
 
-import type { SerwistPlugin } from "../../../types.js";
+import type { StrategyPlugin } from "../../../types.js";
 
-export const cacheOkAndOpaquePlugin: SerwistPlugin = {
+export const cacheOkAndOpaquePlugin: StrategyPlugin = {
   /**
    * Returns a valid response (to allow caching) if the status is 200 (OK) or
    * 0 (opaque).

package/src/lib/strategies/utils/messages.ts

@@ -6,8 +6,8 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { getFriendlyURL } from "../../../utils/getFriendlyURL.js";
-import { logger } from "../../../utils/logger.js";
+import { getFriendlyURL } from "#utils/getFriendlyURL.js";
+import { logger } from "#utils/logger.js";
 
 export const messages = {
   strategyStart: (strategyName: string, request: Request): string => `Using ${strategyName} to respond to '${getFriendlyURL(request.url)}'`,

package/src/models/messages/messages.ts

@@ -64,7 +64,7 @@ export const messages = {
   },
 
   "add-to-cache-list-unexpected-type": ({ entry }) => {
-    return `An unexpected entry was passed to 'serwist.Serwist.addToPrecacheList()' The entry '${JSON.stringify(
+    return `An unexpected entry was passed to 'serwist.Serwist.precache.addToCacheList()' The entry '${JSON.stringify(
       entry,
     )}' isn't supported. You must supply an array of strings with one or more characters, objects with a url property or Request objects.`;
   },
@@ -74,7 +74,7 @@ export const messages = {
       throw new Error("Unexpected input to " + `'add-to-cache-list-duplicate-entries' error.`);
     }
 
-    return `Two of the entries passed to 'serwist.Serwist.addToPrecacheList()' had the URL ${firstEntry} but different revision details. Serwist is unable to cache and version the asset correctly. Please remove one of the entries.`;
+    return `Two of the entries passed to 'serwist.Serwist.precache.addToCacheList()' had the URL ${firstEntry} but different revision details. Serwist is unable to cache and version the asset correctly. Please remove one of the entries.`;
   },
 
   "plugin-error-request-will-fetch": ({ thrownErrorMessage }) => {
@@ -210,7 +210,7 @@ export const messages = {
   },
 
   "add-to-cache-list-conflicting-integrities": ({ url }) => {
-    return `Two of the entries passed to 'serwist.Serwist.addToPrecacheList()' had the URL ${url} with different integrity values. Please remove one of them.`;
+    return `Two of the entries passed to 'serwist.Serwist.precache.addToCacheList()' had the URL ${url} with different integrity values. Please remove one of them.`;
   },
 
   "missing-precache-entry": ({ cacheName, url }) => {

package/src/navigationPreload.ts

@@ -1,4 +1,4 @@
-import { logger } from "./utils/logger.js";
+import { logger } from "#utils/logger.js";
 
 declare const self: ServiceWorkerGlobalScope;
 

package/src/registerQuotaErrorCallback.ts

@@ -6,9 +6,9 @@
   https://opensource.org/licenses/MIT.
 */
 
+import { assert } from "#utils/assert.js";
+import { logger } from "#utils/logger.js";
 import { quotaErrorCallbacks } from "./models/quotaErrorCallbacks.js";
-import { assert } from "./utils/assert.js";
-import { logger } from "./utils/logger.js";
 
 /**
  * Adds a function to the set of quotaErrorCallbacks that will be executed if

package/src/setCacheNameDetails.ts

@@ -6,10 +6,10 @@
   https://opensource.org/licenses/MIT.
 */
 
-import { SerwistError } from "./utils/SerwistError.js";
-import { assert } from "./utils/assert.js";
-import type { PartialCacheNameDetails } from "./utils/cacheNames.js";
-import { cacheNames } from "./utils/cacheNames.js";
+import { SerwistError } from "#utils/SerwistError.js";
+import { assert } from "#utils/assert.js";
+import type { PartialCacheNameDetails } from "#utils/cacheNames.js";
+import { cacheNames } from "#utils/cacheNames.js";
 
 /**
  * Modifies the default cache names used by Serwist packages.