@serwist/sw 9.0.0-preview.17 → 9.0.0-preview.18

package/src/index.precaching.ts

@@ -0,0 +1,38 @@
+import { PrecacheController } from "./precaching/PrecacheController.js";
+import { PrecacheRoute } from "./precaching/PrecacheRoute.js";
+import { PrecacheStrategy } from "./precaching/PrecacheStrategy.js";
+import { addPlugins } from "./precaching/addPlugins.js";
+import { addRoute } from "./precaching/addRoute.js";
+import { cleanupOutdatedCaches } from "./precaching/cleanupOutdatedCaches.js";
+import { createHandlerBoundToURL } from "./precaching/createHandlerBoundToURL.js";
+import { getCacheKeyForURL } from "./precaching/getCacheKeyForURL.js";
+import { matchPrecache } from "./precaching/matchPrecache.js";
+import { precache } from "./precaching/precache.js";
+import { precacheAndRoute } from "./precaching/precacheAndRoute.js";
+
+/**
+ * Most consumers of this module will want to use the
+ * `@serwist/sw/precaching.precacheAndRoute`
+ * method to add assets to the cache and respond to network requests with these
+ * cached assets.
+ *
+ * If you require more control over caching and routing, you can use the
+ * `@serwist/precaching.PrecacheController`
+ * interface.
+ */
+
+export {
+  addPlugins,
+  addRoute,
+  cleanupOutdatedCaches,
+  createHandlerBoundToURL,
+  getCacheKeyForURL,
+  matchPrecache,
+  precache,
+  precacheAndRoute,
+  PrecacheController,
+  PrecacheRoute,
+  PrecacheStrategy,
+};
+
+export type * from "./precaching/types.js";

package/src/index.routing.ts

@@ -0,0 +1,14 @@
+import type { NavigationRouteMatchOptions } from "./routing/NavigationRoute.js";
+import { NavigationRoute } from "./routing/NavigationRoute.js";
+import { RegExpRoute } from "./routing/RegExpRoute.js";
+import { Route } from "./routing/Route.js";
+import { Router } from "./routing/Router.js";
+import { registerRoute } from "./routing/registerRoute.js";
+import { setCatchHandler } from "./routing/setCatchHandler.js";
+import { setDefaultHandler } from "./routing/setDefaultHandler.js";
+import { unregisterRoute } from "./routing/unregisterRoute.js";
+import type { HTTPMethod } from "./routing/utils/constants.js";
+
+export { NavigationRoute, RegExpRoute, registerRoute, Route, Router, setCatchHandler, setDefaultHandler, unregisterRoute };
+
+export type { HTTPMethod, NavigationRouteMatchOptions };

package/src/index.strategies.ts

@@ -1,6 +1,26 @@
-import type { NetworkFirstOptions, NetworkOnlyOptions, StrategyOptions } from "@serwist/strategies";
-import { CacheFirst, CacheOnly, NetworkFirst, NetworkOnly, StaleWhileRevalidate, Strategy, StrategyHandler } from "@serwist/strategies";
+import { CacheFirst } from "./strategies/CacheFirst.js";
+import { CacheOnly } from "./strategies/CacheOnly.js";
+import type { NetworkFirstOptions } from "./strategies/NetworkFirst.js";
+import { NetworkFirst } from "./strategies/NetworkFirst.js";
+import type { NetworkOnlyOptions } from "./strategies/NetworkOnly.js";
+import { NetworkOnly } from "./strategies/NetworkOnly.js";
+import { StaleWhileRevalidate } from "./strategies/StaleWhileRevalidate.js";
+import type { StrategyOptions } from "./strategies/Strategy.js";
+import { Strategy } from "./strategies/Strategy.js";
+import { StrategyHandler } from "./strategies/StrategyHandler.js";
 
+// See https://github.com/GoogleChrome/workbox/issues/2946
+declare global {
+  interface FetchEvent {
+    // See https://github.com/GoogleChrome/workbox/issues/2974
+    readonly preloadResponse: Promise<any>;
+  }
+}
+
+/**
+ * There are common caching strategies that most service workers will need
+ * and use. This module provides simple implementations of these strategies.
+ */
 export { CacheFirst, CacheOnly, NetworkFirst, NetworkOnly, StaleWhileRevalidate, Strategy, StrategyHandler };
 
 export type { NetworkFirstOptions, NetworkOnlyOptions, StrategyOptions };

package/src/index.ts

@@ -1,11 +1,11 @@
-import { Serwist, type SerwistOptions, type SerwistInstallOptions } from "./Serwist.js";
-import { disableDevLogs } from "./disableDevLogs.js";
-import type { FallbackEntry, FallbackMatcher, FallbacksOptions } from "./fallbacks.js";
-import { fallbacks } from "./fallbacks.js";
-import { type HandlePrecachingOptions, handlePrecaching } from "./handlePrecaching.js";
-import { type InstallSerwistOptions, installSerwist } from "./installSerwist.js";
-import { registerRuntimeCaching } from "./registerRuntimeCaching.js";
-import type { RuntimeCaching } from "./types.js";
+import { Serwist, type SerwistInstallOptions, type SerwistOptions } from "./abstractions/Serwist.js";
+import { disableDevLogs } from "./abstractions/disableDevLogs.js";
+import type { FallbackEntry, FallbackMatcher, FallbacksOptions } from "./abstractions/fallbacks.js";
+import { fallbacks } from "./abstractions/fallbacks.js";
+import { type HandlePrecachingOptions, handlePrecaching } from "./abstractions/handlePrecaching.js";
+import { type InstallSerwistOptions, installSerwist } from "./abstractions/installSerwist.js";
+import { registerRuntimeCaching } from "./abstractions/registerRuntimeCaching.js";
+import type { RuntimeCaching } from "./abstractions/types.js";
 
 export { disableDevLogs, fallbacks, handlePrecaching, installSerwist, Serwist, registerRuntimeCaching };
 export type {

package/src/plugins/backgroundSync/BackgroundSyncPlugin.ts

@@ -0,0 +1,39 @@
+/*
+  Copyright 2018 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 { FetchDidFailCallbackParam, SerwistPlugin } from "@serwist/core";
+
+import type { QueueOptions } from "./Queue.js";
+import { Queue } from "./Queue.js";
+
+/**
+ * A class implementing the `fetchDidFail` lifecycle callback. This makes it
+ * easier to add failed requests to a background sync Queue.
+ */
+export class BackgroundSyncPlugin implements SerwistPlugin {
+  private readonly _queue: Queue;
+
+  /**
+   * @param name See the `@serwist/sw/plugins.BackgroundSyncQueue`
+   * documentation for parameter details.
+   * @param options See the `@serwist/sw/plugins.BackgroundSyncQueue`
+   * documentation for parameter details.
+   * @see https://serwist.pages.dev/docs/background-sync/queue
+   */
+  constructor(name: string, options?: QueueOptions) {
+    this._queue = new Queue(name, options);
+  }
+
+  /**
+   * @param options
+   * @private
+   */
+  async fetchDidFail({ request }: FetchDidFailCallbackParam) {
+    await this._queue.pushRequest({ request });
+  }
+}

package/src/plugins/backgroundSync/Queue.ts

@@ -0,0 +1,438 @@
+/*
+  Copyright 2018 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 { assert, SerwistError, getFriendlyURL, logger } from "@serwist/core/internal";
+
+import type { QueueStoreEntry, UnidentifiedQueueStoreEntry } from "./QueueDb.js";
+import { QueueStore } from "./QueueStore.js";
+import { StorableRequest } from "./StorableRequest.js";
+
+// Give TypeScript the correct global.
+declare let self: ServiceWorkerGlobalScope;
+
+interface OnSyncCallbackOptions {
+  queue: Queue;
+}
+
+type OnSyncCallback = (options: OnSyncCallbackOptions) => void | Promise<void>;
+
+export interface QueueOptions {
+  /**
+   * If `true`, instead of attempting to use background sync events, always attempt
+   * to replay queued request at service worker startup. Most folks will not need
+   * this, unless you explicitly target a runtime like Electron that exposes the
+   * interfaces for background sync, but does not have a working implementation.
+   *
+   * @default false
+   */
+  forceSyncFallback?: boolean;
+  /**
+   * The amount of time (in minutes) a request may be retried. After this amount
+   * of time has passed, the request will be deleted from the queue.
+   *
+   * @default 60 * 24 * 7
+   */
+  maxRetentionTime?: number;
+  /**
+   * A function that gets invoked whenever the 'sync' event fires. The function
+   * is invoked with an object containing the `queue` property (referencing this
+   * instance), and you can use the callback to customize the replay behavior of
+   * the queue. When not set the `replayRequests()` method is called. Note: if the
+   * replay fails after a sync event, make sure you throw an error, so the browser
+   * knows to retry the sync event later.
+   */
+  onSync?: OnSyncCallback;
+}
+
+export interface QueueEntry {
+  /**
+   * The request to store in the queue.
+   */
+  request: Request;
+  /**
+   * The timestamp (Epoch time in milliseconds) when the request was first added
+   * to the queue. This is used along with `maxRetentionTime` to remove outdated
+   * requests. In general you don't need to set this value, as it's automatically
+   * set for you (defaulting to `Date.now()`), but you can update it if you don't
+   * want particular requests to expire.
+   */
+  timestamp?: number;
+  /**
+   * Any metadata you want associated with the stored request. When requests are
+   * replayed you'll have access to this metadata object in case you need to modify
+   * the request beforehand.
+   */
+  metadata?: Record<string, unknown>;
+}
+
+const TAG_PREFIX = "serwist-background-sync";
+const MAX_RETENTION_TIME = 60 * 24 * 7; // 7 days in minutes
+
+const queueNames = new Set<string>();
+
+/**
+ * Converts a QueueStore entry into the format exposed by Queue. This entails
+ * converting the request data into a real request and omitting the `id` and
+ * `queueName` properties.
+ *
+ * @param queueStoreEntry
+ * @returns
+ * @private
+ */
+const convertEntry = (queueStoreEntry: UnidentifiedQueueStoreEntry): QueueEntry => {
+  const queueEntry: QueueEntry = {
+    request: new StorableRequest(queueStoreEntry.requestData).toRequest(),
+    timestamp: queueStoreEntry.timestamp,
+  };
+  if (queueStoreEntry.metadata) {
+    queueEntry.metadata = queueStoreEntry.metadata;
+  }
+  return queueEntry;
+};
+
+/**
+ * A class to manage storing failed requests in IndexedDB and retrying them
+ * later. All parts of the storing and replaying process are observable via
+ * callbacks.
+ */
+export class Queue {
+  private readonly _name: string;
+  private readonly _onSync: OnSyncCallback;
+  private readonly _maxRetentionTime: number;
+  private readonly _queueStore: QueueStore;
+  private readonly _forceSyncFallback: boolean;
+  private _syncInProgress = false;
+  private _requestsAddedDuringSync = false;
+
+  /**
+   * Creates an instance of Queue with the given options
+   *
+   * @param name The unique name for this queue. This name must be
+   * unique as it's used to register sync events and store requests
+   * in IndexedDB specific to this instance. An error will be thrown if
+   * a duplicate name is detected.
+   * @param options
+   */
+  constructor(name: string, { forceSyncFallback, onSync, maxRetentionTime }: QueueOptions = {}) {
+    // Ensure the store name is not already being used
+    if (queueNames.has(name)) {
+      throw new SerwistError("duplicate-queue-name", { name });
+    }
+    queueNames.add(name);
+
+    this._name = name;
+    this._onSync = onSync || this.replayRequests;
+    this._maxRetentionTime = maxRetentionTime || MAX_RETENTION_TIME;
+    this._forceSyncFallback = Boolean(forceSyncFallback);
+    this._queueStore = new QueueStore(this._name);
+
+    this._addSyncListener();
+  }
+
+  /**
+   * @returns
+   */
+  get name(): string {
+    return this._name;
+  }
+
+  /**
+   * Stores the passed request in IndexedDB (with its timestamp and any
+   * metadata) at the end of the queue.
+   *
+   * @param entry
+   */
+  async pushRequest(entry: QueueEntry): Promise<void> {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(entry, "object", {
+        moduleName: "@serwist/sw/plugins",
+        className: "BackgroundSyncQueue",
+        funcName: "pushRequest",
+        paramName: "entry",
+      });
+      assert!.isInstance(entry.request, Request, {
+        moduleName: "@serwist/sw/plugins",
+        className: "BackgroundSyncQueue",
+        funcName: "pushRequest",
+        paramName: "entry.request",
+      });
+    }
+
+    await this._addRequest(entry, "push");
+  }
+
+  /**
+   * Stores the passed request in IndexedDB (with its timestamp and any
+   * metadata) at the beginning of the queue.
+   *
+   * @param entry
+   */
+  async unshiftRequest(entry: QueueEntry): Promise<void> {
+    if (process.env.NODE_ENV !== "production") {
+      assert!.isType(entry, "object", {
+        moduleName: "@serwist/sw/plugins",
+        className: "BackgroundSyncQueue",
+        funcName: "unshiftRequest",
+        paramName: "entry",
+      });
+      assert!.isInstance(entry.request, Request, {
+        moduleName: "@serwist/sw/plugins",
+        className: "BackgroundSyncQueue",
+        funcName: "unshiftRequest",
+        paramName: "entry.request",
+      });
+    }
+
+    await this._addRequest(entry, "unshift");
+  }
+
+  /**
+   * Removes and returns the last request in the queue (along with its
+   * timestamp and any metadata).
+   *
+   * @returns
+   */
+  async popRequest(): Promise<QueueEntry | undefined> {
+    return this._removeRequest("pop");
+  }
+
+  /**
+   * Removes and returns the first request in the queue (along with its
+   * timestamp and any metadata).
+   *
+   * @returns
+   */
+  async shiftRequest(): Promise<QueueEntry | undefined> {
+    return this._removeRequest("shift");
+  }
+
+  /**
+   * Returns all the entries that have not expired (per `maxRetentionTime`).
+   * Any expired entries are removed from the queue.
+   *
+   * @returns
+   */
+  async getAll(): Promise<QueueEntry[]> {
+    const allEntries = await this._queueStore.getAll();
+    const now = Date.now();
+
+    const unexpiredEntries = [];
+    for (const entry of allEntries) {
+      // Ignore requests older than maxRetentionTime. Call this function
+      // recursively until an unexpired request is found.
+      const maxRetentionTimeInMs = this._maxRetentionTime * 60 * 1000;
+      if (now - entry.timestamp > maxRetentionTimeInMs) {
+        await this._queueStore.deleteEntry(entry.id);
+      } else {
+        unexpiredEntries.push(convertEntry(entry));
+      }
+    }
+
+    return unexpiredEntries;
+  }
+
+  /**
+   * Returns the number of entries present in the queue.
+   * Note that expired entries (per `maxRetentionTime`) are also included in this count.
+   *
+   * @returns
+   */
+  async size(): Promise<number> {
+    return await this._queueStore.size();
+  }
+
+  /**
+   * Adds the entry to the QueueStore and registers for a sync event.
+   *
+   * @param entry
+   * @param operation
+   * @private
+   */
+  async _addRequest({ request, metadata, timestamp = Date.now() }: QueueEntry, operation: "push" | "unshift"): Promise<void> {
+    const storableRequest = await StorableRequest.fromRequest(request.clone());
+    const entry: UnidentifiedQueueStoreEntry = {
+      requestData: storableRequest.toObject(),
+      timestamp,
+    };
+
+    // Only include metadata if it's present.
+    if (metadata) {
+      entry.metadata = metadata;
+    }
+
+    switch (operation) {
+      case "push":
+        await this._queueStore.pushEntry(entry);
+        break;
+      case "unshift":
+        await this._queueStore.unshiftEntry(entry);
+        break;
+    }
+
+    if (process.env.NODE_ENV !== "production") {
+      logger.log(`Request for '${getFriendlyURL(request.url)}' has ` + `been added to background sync queue '${this._name}'.`);
+    }
+
+    // Don't register for a sync if we're in the middle of a sync. Instead,
+    // we wait until the sync is complete and call register if
+    // `this._requestsAddedDuringSync` is true.
+    if (this._syncInProgress) {
+      this._requestsAddedDuringSync = true;
+    } else {
+      await this.registerSync();
+    }
+  }
+
+  /**
+   * Removes and returns the first or last (depending on `operation`) entry
+   * from the QueueStore that's not older than the `maxRetentionTime`.
+   *
+   * @param operation
+   * @returns
+   * @private
+   */
+  async _removeRequest(operation: "pop" | "shift"): Promise<QueueEntry | undefined> {
+    const now = Date.now();
+    let entry: QueueStoreEntry | undefined;
+    switch (operation) {
+      case "pop":
+        entry = await this._queueStore.popEntry();
+        break;
+      case "shift":
+        entry = await this._queueStore.shiftEntry();
+        break;
+    }
+
+    if (entry) {
+      // Ignore requests older than maxRetentionTime. Call this function
+      // recursively until an unexpired request is found.
+      const maxRetentionTimeInMs = this._maxRetentionTime * 60 * 1000;
+      if (now - entry.timestamp > maxRetentionTimeInMs) {
+        return this._removeRequest(operation);
+      }
+
+      return convertEntry(entry);
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Loops through each request in the queue and attempts to re-fetch it.
+   * If any request fails to re-fetch, it's put back in the same position in
+   * the queue (which registers a retry for the next sync event).
+   */
+  async replayRequests(): Promise<void> {
+    let entry: QueueEntry | undefined = undefined;
+    while ((entry = await this.shiftRequest())) {
+      try {
+        await fetch(entry.request.clone());
+
+        if (process.env.NODE_ENV !== "production") {
+          logger.log(`Request for '${getFriendlyURL(entry.request.url)}' ` + `has been replayed in queue '${this._name}'`);
+        }
+      } catch (error) {
+        await this.unshiftRequest(entry);
+
+        if (process.env.NODE_ENV !== "production") {
+          logger.log(`Request for '${getFriendlyURL(entry.request.url)}' ` + `failed to replay, putting it back in queue '${this._name}'`);
+        }
+        throw new SerwistError("queue-replay-failed", { name: this._name });
+      }
+    }
+    if (process.env.NODE_ENV !== "production") {
+      logger.log(`All requests in queue '${this.name}' have successfully replayed; the queue is now empty!`);
+    }
+  }
+
+  /**
+   * Registers a sync event with a tag unique to this instance.
+   */
+  async registerSync(): Promise<void> {
+    // See https://github.com/GoogleChrome/workbox/issues/2393
+    if ("sync" in self.registration && !this._forceSyncFallback) {
+      try {
+        await self.registration.sync.register(`${TAG_PREFIX}:${this._name}`);
+      } catch (err) {
+        // This means the registration failed for some reason, possibly due to
+        // the user disabling it.
+        if (process.env.NODE_ENV !== "production") {
+          logger.warn(`Unable to register sync event for '${this._name}'.`, err);
+        }
+      }
+    }
+  }
+
+  /**
+   * In sync-supporting browsers, this adds a listener for the sync event.
+   * In non-sync-supporting browsers, or if _forceSyncFallback is true, this
+   * will retry the queue on service worker startup.
+   *
+   * @private
+   */
+  private _addSyncListener() {
+    // See https://github.com/GoogleChrome/workbox/issues/2393
+    if ("sync" in self.registration && !this._forceSyncFallback) {
+      self.addEventListener("sync", (event: SyncEvent) => {
+        if (event.tag === `${TAG_PREFIX}:${this._name}`) {
+          if (process.env.NODE_ENV !== "production") {
+            logger.log(`Background sync for tag '${event.tag}' has been received`);
+          }
+
+          const syncComplete = async () => {
+            this._syncInProgress = true;
+
+            let syncError: Error | undefined = undefined;
+            try {
+              await this._onSync({ queue: this });
+            } catch (error) {
+              if (error instanceof Error) {
+                syncError = error;
+
+                // Rethrow the error. Note: the logic in the finally clause
+                // will run before this gets rethrown.
+                throw syncError;
+              }
+            } finally {
+              // New items may have been added to the queue during the sync,
+              // so we need to register for a new sync if that's happened...
+              // Unless there was an error during the sync, in which
+              // case the browser will automatically retry later, as long
+              // as `event.lastChance` is not true.
+              if (this._requestsAddedDuringSync && !(syncError && !event.lastChance)) {
+                await this.registerSync();
+              }
+
+              this._syncInProgress = false;
+              this._requestsAddedDuringSync = false;
+            }
+          };
+          event.waitUntil(syncComplete());
+        }
+      });
+    } else {
+      if (process.env.NODE_ENV !== "production") {
+        logger.log("Background sync replaying without background sync event");
+      }
+      // If the browser doesn't support background sync, or the developer has
+      // opted-in to not using it, retry every time the service worker starts up
+      // as a fallback.
+      void this._onSync({ queue: this });
+    }
+  }
+
+  /**
+   * Returns the set of queue names. This is primarily used to reset the list
+   * of queue names in tests.
+   *
+   * @returns
+   * @private
+   */
+  static get _queueNames(): Set<string> {
+    return queueNames;
+  }
+}