serwist 9.1.1 → 10.0.0-preview.10

package/src/lib/core.ts

@@ -0,0 +1,128 @@
+import { clientsClaim as clientsClaimImpl } from "#utils/clientsClaim.js";
+import type { HTTPMethod } from "./constants.js";
+import type { Extension } from "./extension.js";
+import { Precache } from "./extensions/index.js";
+import { iterateExtensions } from "./functions/handlers.js";
+import { enableNavigationPreload } from "./navigation-preload.js";
+import type { Route } from "./route.js";
+import type { PrecacheEntry, PrecacheOptions, RouteHandlerObject } from "./types.js";
+import { disableDevLogs as disableDevLogsImpl, setCacheNameDetails } from "./utils.js";
+
+export interface Serwist {
+  readonly routes: Map<HTTPMethod, Route[]>;
+  readonly defaultHandlerMap: Map<HTTPMethod, RouteHandlerObject>;
+  readonly precache: Precache;
+  readonly extensions: Extension[];
+  catchHandler?: RouteHandlerObject;
+}
+
+export interface SerwistOptions {
+  /**
+   * Options to customize precaching.
+   */
+  precache?: PrecacheOptions & {
+    entries: (PrecacheEntry | string)[] | undefined;
+  };
+  /**
+   * Forces the waiting service worker to become the active one.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerGlobalScope/skipWaiting
+   */
+  skipWaiting?: boolean;
+  /**
+   * Imports external scripts. They are executed in the order they
+   * are passed.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/WorkerGlobalScope/importScripts
+   */
+  importScripts?: string[];
+  /**
+   * Enables navigation preloading if it is supported.
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorkerRegistration/navigationPreload
+   */
+  navigationPreload?: boolean;
+  /**
+   * Modifies the prefix of the default cache names used by Serwist packages.
+   */
+  cacheId?: string | undefined;
+  /**
+   * Claims any currently available clients once the service worker
+   * becomes active. This is normally used in conjunction with `skipWaiting()`.
+   *
+   * @default false
+   */
+  clientsClaim?: boolean;
+  /**
+   * Disables Serwist's logging in development mode.
+   *
+   * @default false
+   */
+  disableDevLogs?: boolean;
+  /**
+   * A list of extensions.
+   */
+  extensions?: Extension[];
+}
+
+declare const self: ServiceWorkerGlobalScope;
+
+export const createSerwist = ({
+  precache,
+  skipWaiting = false,
+  importScripts,
+  navigationPreload = false,
+  cacheId,
+  clientsClaim = false,
+  disableDevLogs = false,
+  extensions = [],
+}: SerwistOptions = {}): Serwist => {
+  if (importScripts?.length) self.importScripts(...importScripts);
+
+  if (navigationPreload) enableNavigationPreload();
+
+  if (cacheId) setCacheNameDetails({ prefix: cacheId });
+
+  if (skipWaiting) {
+    self.skipWaiting();
+  } else {
+    self.addEventListener("message", (event) => {
+      if (event.data?.type === "SKIP_WAITING") {
+        self.skipWaiting();
+      }
+    });
+  }
+
+  if (clientsClaim) clientsClaimImpl();
+
+  const precacheExtension = new Precache(precache ?? { entries: [] });
+
+  const routes = new Map<HTTPMethod, Route[]>();
+
+  const defaultHandlerMap = new Map<HTTPMethod, RouteHandlerObject>();
+
+  const exts = [precacheExtension, ...extensions];
+
+  const state: Serwist = {
+    get routes() {
+      return routes;
+    },
+    get defaultHandlerMap() {
+      return defaultHandlerMap;
+    },
+    get precache() {
+      return precacheExtension;
+    },
+    get extensions() {
+      return exts;
+    },
+  };
+
+  for (const callback of iterateExtensions(state, "init")) {
+    callback({ serwist: state });
+  }
+
+  if (disableDevLogs) disableDevLogsImpl();
+
+  return state;
+};

package/src/lib/expiration/CacheExpiration.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 { assert } from "#utils/assert.js";
+import { logger } from "#utils/logger.js";
+import { SerwistError } from "#utils/SerwistError.js";
 import { CacheTimestampsModel } from "./models/CacheTimestampsModel.js";
 
 interface CacheExpirationConfig {

package/src/lib/expiration/ExpirationPlugin.ts

@@ -5,16 +5,15 @@
   license that can be found in the LICENSE file or at
   https://opensource.org/licenses/MIT.
 */
-
-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 "#lib/types.js";
+import { registerQuotaErrorCallback } from "#lib/utils.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 { SerwistError } from "#utils/SerwistError.js";
 import type { Strategy } from "../strategies/Strategy.js";
+import { CacheExpiration } from "./CacheExpiration.js";
 
 export interface ExpirationPluginOptions {
   /**
@@ -66,7 +65,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/extension.ts

@@ -0,0 +1,37 @@
+import type { MaybePromise } from "@serwist/utils";
+import type { Serwist } from "./core.js";
+
+export interface InitCallbackParam {
+  serwist: Serwist;
+}
+
+export type InitCallback = (param: InitCallbackParam) => MaybePromise<void>;
+
+export interface InstallCallbackParam {
+  event: ExtendableEvent;
+  serwist: Serwist;
+}
+
+export type InstallCallback = (param: InstallCallbackParam) => MaybePromise<void>;
+
+export interface ActivateCallbackParam {
+  event: ExtendableEvent;
+  serwist: Serwist;
+}
+
+export type ActivateCallback = (param: ActivateCallbackParam) => MaybePromise<void>;
+
+/**
+ * An object with optional lifecycle callback properties for Serwist's operations.
+ */
+export interface Extension {
+  init?: InitCallback;
+  install?: InstallCallback;
+  activate?: ActivateCallback;
+}
+
+export interface ExtensionParam {
+  init: InitCallbackParam;
+  install: InstallCallbackParam;
+  activate: ActivateCallbackParam;
+}

package/src/lib/{googleAnalytics/initializeGoogleAnalytics.ts → extensions/google-analytics/extension.ts}

@@ -1,21 +1,15 @@
-/*
-  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 { 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 { BackgroundSyncPlugin } from "#lib/background-sync/BackgroundSyncPlugin.js";
+import type { BackgroundSyncQueue, BackgroundSyncQueueEntry } from "#lib/background-sync/BackgroundSyncQueue.js";
+import type { Serwist } from "#lib/core.js";
+import type { Extension } from "#lib/extension.js";
+import { registerRoute } from "#lib/functions/router.js";
+import { Route } from "#lib/route.js";
+import { NetworkFirst } from "#lib/strategies/NetworkFirst.js";
+import { NetworkOnly } from "#lib/strategies/NetworkOnly.js";
+import type { RouteMatchCallbackOptions } from "#lib/types.js";
+import { cacheNames as privateCacheNames } from "#utils/cacheNames.js";
+import { getFriendlyURL } from "#utils/getFriendlyURL.js";
+import { logger } from "#utils/logger.js";
 import {
   ANALYTICS_JS_PATH,
   COLLECT_PATHS_REGEX,
@@ -27,8 +21,7 @@ import {
   QUEUE_NAME,
 } from "./constants.js";
 
-export interface GoogleAnalyticsInitializeOptions {
-  serwist: Serwist;
+export interface GoogleAnalyticsOptions {
   /**
    * The cache name to store and retrieve analytics.js. Defaults to Serwist's default cache names.
    */
@@ -58,7 +51,7 @@ export interface GoogleAnalyticsInitializeOptions {
  * @returns The requestWillDequeue callback function.
  * @private
  */
-const createOnSyncCallback = (config: Pick<GoogleAnalyticsInitializeOptions, "parameterOverrides" | "hitFilter">) => {
+export const createOnSyncCallback = (config: Pick<GoogleAnalyticsOptions, "parameterOverrides" | "hitFilter">) => {
   return async ({ queue }: { queue: BackgroundSyncQueue }) => {
     let entry: BackgroundSyncQueueEntry | undefined;
     while ((entry = await queue.shiftRequest())) {
@@ -128,7 +121,7 @@ const createOnSyncCallback = (config: Pick<GoogleAnalyticsInitializeOptions, "pa
  * @returns The created routes.
  * @private
  */
-const createCollectRoutes = (bgSyncPlugin: BackgroundSyncPlugin) => {
+export const createCollectRoutes = (bgSyncPlugin: BackgroundSyncPlugin) => {
   const match = ({ url }: RouteMatchCallbackOptions) => url.hostname === GOOGLE_ANALYTICS_HOST && COLLECT_PATHS_REGEX.test(url.pathname);
 
   const handler = new NetworkOnly({
@@ -145,7 +138,7 @@ const createCollectRoutes = (bgSyncPlugin: BackgroundSyncPlugin) => {
  * @returns The created route.
  * @private
  */
-const createAnalyticsJsRoute = (cacheName: string) => {
+export const createAnalyticsJsRoute = (cacheName: string) => {
   const match = ({ url }: RouteMatchCallbackOptions) => url.hostname === GOOGLE_ANALYTICS_HOST && url.pathname === ANALYTICS_JS_PATH;
 
   const handler = new NetworkFirst({ cacheName });
@@ -160,7 +153,7 @@ const createAnalyticsJsRoute = (cacheName: string) => {
  * @returns The created route.
  * @private
  */
-const createGtagJsRoute = (cacheName: string) => {
+export const createGtagJsRoute = (cacheName: string) => {
   const match = ({ url }: RouteMatchCallbackOptions) => url.hostname === GTM_HOST && url.pathname === GTAG_JS_PATH;
 
   const handler = new NetworkFirst({ cacheName });
@@ -175,7 +168,7 @@ const createGtagJsRoute = (cacheName: string) => {
  * @returns The created route.
  * @private
  */
-const createGtmJsRoute = (cacheName: string) => {
+export const createGtmJsRoute = (cacheName: string) => {
   const match = ({ url }: RouteMatchCallbackOptions) => url.hostname === GTM_HOST && url.pathname === GTM_JS_PATH;
 
   const handler = new NetworkFirst({ cacheName });
@@ -183,27 +176,28 @@ const createGtmJsRoute = (cacheName: string) => {
   return new Route(match, handler, "GET");
 };
 
-/**
- * Initialize Serwist's offline Google Analytics v3 support.
- *
- * @param options
- */
-export const initializeGoogleAnalytics = ({ serwist, cacheName, ...options }: GoogleAnalyticsInitializeOptions): void => {
-  const resolvedCacheName = privateCacheNames.getGoogleAnalyticsName(cacheName);
-
-  const bgSyncPlugin = new BackgroundSyncPlugin(QUEUE_NAME, {
-    maxRetentionTime: MAX_RETENTION_TIME,
-    onSync: createOnSyncCallback(options),
-  });
-
-  const routes = [
-    createGtmJsRoute(resolvedCacheName),
-    createAnalyticsJsRoute(resolvedCacheName),
-    createGtagJsRoute(resolvedCacheName),
-    ...createCollectRoutes(bgSyncPlugin),
-  ];
-
-  for (const route of routes) {
-    serwist.registerRoute(route);
+export class GoogleAnalytics implements Extension {
+  private _options: GoogleAnalyticsOptions;
+  constructor(options: GoogleAnalyticsOptions = {}) {
+    this._options = options;
   }
-};
+  init({ serwist }: { serwist: Serwist }) {
+    const resolvedCacheName = privateCacheNames.getGoogleAnalyticsName(this._options.cacheName);
+
+    const bgSyncPlugin = new BackgroundSyncPlugin(QUEUE_NAME, {
+      maxRetentionTime: MAX_RETENTION_TIME,
+      onSync: createOnSyncCallback(this._options),
+    });
+
+    const routes = [
+      createGtmJsRoute(resolvedCacheName),
+      createAnalyticsJsRoute(resolvedCacheName),
+      createGtagJsRoute(resolvedCacheName),
+      ...createCollectRoutes(bgSyncPlugin),
+    ];
+
+    for (const route of routes) {
+      registerRoute(serwist, route);
+    }
+  }
+}

package/src/lib/extensions/google-analytics/initialize.ts

@@ -0,0 +1,48 @@
+/*
+  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 { BackgroundSyncPlugin } from "#lib/background-sync/BackgroundSyncPlugin.js";
+import type { Serwist } from "#lib/serwist.js";
+import { cacheNames as privateCacheNames } from "#utils/cacheNames.js";
+import { MAX_RETENTION_TIME, QUEUE_NAME } from "./constants.js";
+import {
+  createAnalyticsJsRoute,
+  createCollectRoutes,
+  createGtagJsRoute,
+  createGtmJsRoute,
+  createOnSyncCallback,
+  type GoogleAnalyticsOptions,
+} from "./extension.js";
+
+export interface GoogleAnalyticsInitializeOptions extends GoogleAnalyticsOptions {
+  serwist: Serwist;
+}
+
+/**
+ * Initialize Serwist's offline Google Analytics v3 support.
+ *
+ * @param options
+ */
+export const initializeGoogleAnalytics = ({ serwist, cacheName, ...options }: GoogleAnalyticsInitializeOptions): void => {
+  const resolvedCacheName = privateCacheNames.getGoogleAnalyticsName(cacheName);
+
+  const bgSyncPlugin = new BackgroundSyncPlugin(QUEUE_NAME, {
+    maxRetentionTime: MAX_RETENTION_TIME,
+    onSync: createOnSyncCallback(options),
+  });
+
+  const routes = [
+    createGtmJsRoute(resolvedCacheName),
+    createAnalyticsJsRoute(resolvedCacheName),
+    createGtagJsRoute(resolvedCacheName),
+    ...createCollectRoutes(bgSyncPlugin),
+  ];
+
+  for (const route of routes) {
+    serwist.registerRoute(route);
+  }
+};

package/src/lib/extensions/index.ts

@@ -0,0 +1,13 @@
+export type { GoogleAnalyticsOptions } from "./google-analytics/extension.js";
+export { GoogleAnalytics } from "./google-analytics/extension.js";
+export type { GoogleAnalyticsInitializeOptions } from "./google-analytics/initialize.js";
+export { initializeGoogleAnalytics } from "./google-analytics/initialize.js";
+export type { PrecacheEntry, PrecacheExtensionOptions, PrecacheOptions } from "./precache/extension.js";
+export { Precache } from "./precache/extension.js";
+export type { PrecacheFallbackEntry, PrecacheFallbackPluginOptions } from "./precache/plugin-fallback.js";
+export { PrecacheFallbackPlugin } from "./precache/plugin-fallback.js";
+export type { PrecacheRouteOptions } from "./precache/route.js";
+export { PrecacheRoute } from "./precache/route.js";
+export type { PrecacheStrategyOptions } from "./precache/strategy.js";
+export { PrecacheStrategy } from "./precache/strategy.js";
+export { RuntimeCache, type RuntimeCacheOptions } from "./runtime-cache.js";