@serwist/core 8.4.3 → 9.0.0-preview.0

package/src/_private/cacheNames.ts

@@ -0,0 +1,87 @@
+/*
+  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.
+*/
+
+declare let registration: ServiceWorkerRegistration | undefined;
+
+export interface CacheNameDetails {
+  googleAnalytics: string;
+  precache: string;
+  prefix: string;
+  runtime: string;
+  suffix: string;
+}
+
+export interface PartialCacheNameDetails {
+  /**
+   * The string to add to the beginning of the precache and runtime cache names.
+   */
+  prefix?: string;
+  /**
+   * The string to add to the end of the precache and runtime cache names.
+   */
+  suffix?: string;
+  /**
+   * The cache name to use for precache caching.
+   */
+  precache?: string;
+  /**
+   * The cache name to use for runtime caching.
+   */
+  runtime?: string;
+  /**
+   * The cache name to use for `@serwist/google-analytics` caching.
+   */
+  googleAnalytics?: string;
+  [propName: string]: string | undefined;
+}
+
+export type CacheNameDetailsProp = "googleAnalytics" | "precache" | "prefix" | "runtime" | "suffix";
+
+const _cacheNameDetails: CacheNameDetails = {
+  googleAnalytics: "googleAnalytics",
+  precache: "precache-v2",
+  prefix: "serwist",
+  runtime: "runtime",
+  suffix: typeof registration !== "undefined" ? registration.scope : "",
+};
+
+const _createCacheName = (cacheName: string): string => {
+  return [_cacheNameDetails.prefix, cacheName, _cacheNameDetails.suffix].filter((value) => value && value.length > 0).join("-");
+};
+
+const eachCacheNameDetail = (fn: (key: CacheNameDetailsProp) => void): void => {
+  for (const key of Object.keys(_cacheNameDetails)) {
+    fn(key as CacheNameDetailsProp);
+  }
+};
+
+export const cacheNames = {
+  updateDetails: (details: PartialCacheNameDetails): void => {
+    eachCacheNameDetail((key: CacheNameDetailsProp): void => {
+      const detail = details[key];
+      if (typeof detail === "string") {
+        _cacheNameDetails[key] = detail;
+      }
+    });
+  },
+  getGoogleAnalyticsName: (userCacheName?: string): string => {
+    return userCacheName || _createCacheName(_cacheNameDetails.googleAnalytics);
+  },
+  getPrecacheName: (userCacheName?: string): string => {
+    return userCacheName || _createCacheName(_cacheNameDetails.precache);
+  },
+  getPrefix: (): string => {
+    return _cacheNameDetails.prefix;
+  },
+  getRuntimeName: (userCacheName?: string): string => {
+    return userCacheName || _createCacheName(_cacheNameDetails.runtime);
+  },
+  getSuffix: (): string => {
+    return _cacheNameDetails.suffix;
+  },
+};

package/src/_private/canConstructReadableStream.ts

@@ -0,0 +1,34 @@
+/*
+  Copyright 2019 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.
+*/
+
+let supportStatus: boolean | undefined;
+
+/**
+ * A utility function that determines whether the current browser supports
+ * constructing a [`ReadableStream`](https://developer.mozilla.org/en-US/docs/Web/API/ReadableStream/ReadableStream)
+ * object.
+ *
+ * @returns `true`, if the current browser can successfully construct a `ReadableStream`, `false` otherwise.
+ *
+ * @private
+ */
+function canConstructReadableStream(): boolean {
+  if (supportStatus === undefined) {
+    // See https://github.com/GoogleChrome/workbox/issues/1473
+    try {
+      new ReadableStream({ start() {} });
+      supportStatus = true;
+    } catch (error) {
+      supportStatus = false;
+    }
+  }
+
+  return supportStatus;
+}
+
+export { canConstructReadableStream };

package/src/_private/canConstructResponseFromBodyStream.ts

@@ -0,0 +1,37 @@
+/*
+  Copyright 2019 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.
+*/
+
+let supportStatus: boolean | undefined;
+
+/**
+ * A utility function that determines whether the current browser supports
+ * constructing a new `Response` from a `response.body` stream.
+ *
+ * @returns `true`, if the current browser can successfully construct
+ * a `Response` from a `response.body` stream, `false` otherwise.
+ * @private
+ */
+function canConstructResponseFromBodyStream(): boolean {
+  if (supportStatus === undefined) {
+    const testResponse = new Response("");
+
+    if ("body" in testResponse) {
+      try {
+        new Response(testResponse.body);
+        supportStatus = true;
+      } catch (error) {
+        supportStatus = false;
+      }
+    }
+    supportStatus = false;
+  }
+
+  return supportStatus;
+}
+
+export { canConstructResponseFromBodyStream };

package/src/_private/dontWaitFor.ts

@@ -0,0 +1,16 @@
+/*
+  Copyright 2019 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.
+*/
+
+/**
+ * A helper function that prevents a promise from being flagged as unused.
+ *
+ * @private
+ **/
+export function dontWaitFor(promise: Promise<any>): void {
+  // Effective no-op.
+  void promise.then(() => {});
+}

package/src/_private/executeQuotaErrorCallbacks.ts

@@ -0,0 +1,35 @@
+/*
+  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 { logger } from "../_private/logger.js";
+import { quotaErrorCallbacks } from "../models/quotaErrorCallbacks.js";
+
+/**
+ * Runs all of the callback functions, one at a time sequentially, in the order
+ * in which they were registered.
+ *
+ * @private
+ */
+async function executeQuotaErrorCallbacks(): Promise<void> {
+  if (process.env.NODE_ENV !== "production") {
+    logger.log(`About to run ${quotaErrorCallbacks.size} callbacks to clean up caches.`);
+  }
+
+  for (const callback of quotaErrorCallbacks) {
+    await callback();
+    if (process.env.NODE_ENV !== "production") {
+      logger.log(callback, "is complete.");
+    }
+  }
+
+  if (process.env.NODE_ENV !== "production") {
+    logger.log("Finished running callbacks.");
+  }
+}
+
+export { executeQuotaErrorCallbacks };

package/src/_private/getFriendlyURL.ts

@@ -0,0 +1,16 @@
+/*
+  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.
+*/
+
+const getFriendlyURL = (url: URL | string): string => {
+  const urlObj = new URL(String(url), location.href);
+  // See https://github.com/GoogleChrome/workbox/issues/2323
+  // We want to include everything, except for the origin if it's same-origin.
+  return urlObj.href.replace(new RegExp(`^${location.origin}`), "");
+};
+
+export { getFriendlyURL };

package/src/_private/logger.ts

@@ -0,0 +1,92 @@
+/*
+  Copyright 2019 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.
+*/
+
+// logger is used inside of both service workers and the window global scope.
+declare global {
+  interface WorkerGlobalScope {
+    __WB_DISABLE_DEV_LOGS: boolean;
+  }
+
+  interface Window {
+    __WB_DISABLE_DEV_LOGS: boolean;
+  }
+}
+
+type LoggerMethods = "debug" | "log" | "warn" | "error" | "groupCollapsed" | "groupEnd";
+
+const logger = (
+  process.env.NODE_ENV === "production"
+    ? null
+    : (() => {
+        // Don't overwrite this value if it's already set.
+        // See https://github.com/GoogleChrome/workbox/pull/2284#issuecomment-560470923
+        if (!("__WB_DISABLE_DEV_LOGS" in globalThis)) {
+          self.__WB_DISABLE_DEV_LOGS = false;
+        }
+
+        let inGroup = false;
+
+        const methodToColorMap: { [methodName: string]: string | null } = {
+          debug: "#7f8c8d", // Gray
+          log: "#2ecc71", // Green
+          warn: "#f39c12", // Yellow
+          error: "#c0392b", // Red
+          groupCollapsed: "#3498db", // Blue
+          groupEnd: null, // No colored prefix on groupEnd
+        };
+
+        const print = (method: LoggerMethods, args: any[]) => {
+          if (self.__WB_DISABLE_DEV_LOGS) {
+            return;
+          }
+
+          if (method === "groupCollapsed") {
+            // Safari doesn't print all console.groupCollapsed() arguments:
+            // https://bugs.webkit.org/show_bug.cgi?id=182754
+            if (typeof navigator !== "undefined" && /^((?!chrome|android).)*safari/i.test(navigator.userAgent)) {
+              console[method](...args);
+              return;
+            }
+          }
+
+          const styles = [
+            `background: ${methodToColorMap[method]!}`,
+            "border-radius: 0.5em",
+            "color: white",
+            "font-weight: bold",
+            "padding: 2px 0.5em",
+          ];
+
+          // When in a group, the serwist prefix is not displayed.
+          const logPrefix = inGroup ? [] : ["%cserwist", styles.join(";")];
+
+          console[method](...logPrefix, ...args);
+
+          if (method === "groupCollapsed") {
+            inGroup = true;
+          }
+          if (method === "groupEnd") {
+            inGroup = false;
+          }
+        };
+        // biome-ignore lint/complexity/noBannedTypes: Unknown reason
+        const api: { [methodName: string]: Function } = {};
+        const loggerMethods = Object.keys(methodToColorMap);
+
+        for (const key of loggerMethods) {
+          const method = key as LoggerMethods;
+
+          api[method] = (...args: any[]) => {
+            print(method, args);
+          };
+        }
+
+        return api as unknown;
+      })()
+) as Console;
+
+export { logger };

package/src/_private/resultingClientExists.ts

@@ -0,0 +1,58 @@
+/*
+  Copyright 2019 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 { timeout } from "./timeout.js";
+
+// Give TypeScript the correct global.
+declare let self: ServiceWorkerGlobalScope;
+
+const MAX_RETRY_TIME = 2000;
+
+/**
+ * Returns a promise that resolves to a window client matching the passed
+ * `resultingClientId`. For browsers that don't support `resultingClientId`
+ * or if waiting for the resulting client to apper takes too long, resolve to
+ * `undefined`.
+ *
+ * @param resultingClientId
+ * @returns
+ * @private
+ */
+export async function resultingClientExists(resultingClientId?: string): Promise<Client | undefined> {
+  if (!resultingClientId) {
+    return;
+  }
+
+  let existingWindows = await self.clients.matchAll({ type: "window" });
+  const existingWindowIds = new Set(existingWindows.map((w) => w.id));
+
+  let resultingWindow: Client | undefined = undefined;
+  const startTime = performance.now();
+
+  // Only wait up to `MAX_RETRY_TIME` to find a matching client.
+  while (performance.now() - startTime < MAX_RETRY_TIME) {
+    existingWindows = await self.clients.matchAll({ type: "window" });
+
+    resultingWindow = existingWindows.find((w) => {
+      if (resultingClientId) {
+        // If we have a `resultingClientId`, we can match on that.
+        return w.id === resultingClientId;
+      }
+      // Otherwise match on finding a window not in `existingWindowIds`.
+      return !existingWindowIds.has(w.id);
+    });
+
+    if (resultingWindow) {
+      break;
+    }
+
+    // Sleep for 100ms and retry.
+    await timeout(100);
+  }
+
+  return resultingWindow;
+}

package/src/_private/timeout.ts

@@ -0,0 +1,19 @@
+/*
+  Copyright 2019 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.
+*/
+
+/**
+ * Returns a promise that resolves and the passed number of milliseconds.
+ * This utility is an async/await-friendly version of `setTimeout`.
+ *
+ * @param ms
+ * @returns
+ * @private
+ */
+
+export function timeout(ms: number): Promise<unknown> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/_private/waitUntil.ts

@@ -0,0 +1,23 @@
+/*
+  Copyright 2020 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.
+*/
+
+/**
+ * A utility method that makes it easier to use `event.waitUntil` with
+ * async functions and return the result.
+ *
+ * @param event
+ * @param asyncFn
+ * @returns
+ * @private
+ */
+function waitUntil(event: ExtendableEvent, asyncFn: () => Promise<any>): Promise<any> {
+  const returnPromise = asyncFn();
+  event.waitUntil(returnPromise);
+  return returnPromise;
+}
+
+export { waitUntil };

package/src/cacheNames.ts

@@ -0,0 +1,41 @@
+/*
+  Copyright 2019 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 { cacheNames as _cacheNames } from "./_private/cacheNames.js";
+
+/**
+ * Get the current cache names and prefix/suffix used by Workbox.
+ *
+ * `cacheNames.precache` is used for precached assets,
+ * `cacheNames.googleAnalytics` is used by `@serwist/google-analytics` to
+ * store `analytics.js`, and `cacheNames.runtime` is used for everything else.
+ *
+ * `cacheNames.prefix` can be used to retrieve just the current prefix value.
+ * `cacheNames.suffix` can be used to retrieve just the current suffix value.
+ *
+ * @returns An object with `precache`, `runtime`, `prefix`, and `googleAnalytics` properties.
+ */
+const cacheNames = {
+  get googleAnalytics(): string {
+    return _cacheNames.getGoogleAnalyticsName();
+  },
+  get precache(): string {
+    return _cacheNames.getPrecacheName();
+  },
+  get prefix(): string {
+    return _cacheNames.getPrefix();
+  },
+  get runtime(): string {
+    return _cacheNames.getRuntimeName();
+  },
+  get suffix(): string {
+    return _cacheNames.getSuffix();
+  },
+};
+
+export { cacheNames };

package/src/clientsClaim.ts

@@ -0,0 +1,20 @@
+/*
+  Copyright 2019 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.
+*/
+
+// Give TypeScript the correct global.
+declare let self: ServiceWorkerGlobalScope;
+
+/**
+ * Claim any currently available clients once the service worker
+ * becomes active. This is normally used in conjunction with `skipWaiting()`.
+ */
+function clientsClaim(): void {
+  self.addEventListener("activate", () => self.clients.claim());
+}
+
+export { clientsClaim };

package/src/copyResponse.ts

@@ -0,0 +1,62 @@
+/*
+  Copyright 2019 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 { SerwistError } from "./_private/SerwistError.js";
+import { canConstructResponseFromBodyStream } from "./_private/canConstructResponseFromBodyStream.js";
+
+/**
+ * Allows developers to copy a response and modify its `headers`, `status`,
+ * or `statusText` values (the values settable via a
+ * [`ResponseInit`](https://developer.mozilla.org/en-US/docs/Web/API/Response/Response#Syntax)
+ * object in the constructor).
+ * To modify these values, pass a function as the second argument. That
+ * function will be invoked with a single object with the response properties
+ * `{headers, status, statusText}`. The return value of this function will
+ * be used as the `ResponseInit` for the new `Response`. To change the values
+ * either modify the passed parameter(s) and return it, or return a totally
+ * new object.
+ *
+ * This method is intentionally limited to same-origin responses, regardless of
+ * whether CORS was used or not.
+ *
+ * @param response
+ * @param modifier
+ */
+async function copyResponse(response: Response, modifier?: (responseInit: ResponseInit) => ResponseInit): Promise<Response> {
+  let origin = null;
+  // If response.url isn't set, assume it's cross-origin and keep origin null.
+  if (response.url) {
+    const responseURL = new URL(response.url);
+    origin = responseURL.origin;
+  }
+
+  if (origin !== self.location.origin) {
+    throw new SerwistError("cross-origin-copy-response", { origin });
+  }
+
+  const clonedResponse = response.clone();
+
+  // Create a fresh `ResponseInit` object by cloning the headers.
+  const responseInit: ResponseInit = {
+    headers: new Headers(clonedResponse.headers),
+    status: clonedResponse.status,
+    statusText: clonedResponse.statusText,
+  };
+
+  // Apply any user modifications.
+  const modifiedResponseInit = modifier ? modifier(responseInit) : responseInit;
+
+  // Create the new response from the body stream and `ResponseInit`
+  // modifications. Note: not all browsers support the Response.body stream,
+  // so fall back to reading the entire body into memory as a blob.
+  const body = canConstructResponseFromBodyStream() ? clonedResponse.body : await clonedResponse.blob();
+
+  return new Response(body, modifiedResponseInit);
+}
+
+export { copyResponse };

package/src/index.internal.ts

@@ -0,0 +1,33 @@
+import { Deferred } from "./_private/Deferred.js";
+import { SerwistError } from "./_private/SerwistError.js";
+import { assert } from "./_private/assert.js";
+import { cacheMatchIgnoreParams } from "./_private/cacheMatchIgnoreParams.js";
+import { cacheNames as privateCacheNames } from "./_private/cacheNames.js";
+import { canConstructReadableStream } from "./_private/canConstructReadableStream.js";
+import { canConstructResponseFromBodyStream } from "./_private/canConstructResponseFromBodyStream.js";
+import { dontWaitFor } from "./_private/dontWaitFor.js";
+import { executeQuotaErrorCallbacks } from "./_private/executeQuotaErrorCallbacks.js";
+import { getFriendlyURL } from "./_private/getFriendlyURL.js";
+import { logger } from "./_private/logger.js";
+import { resultingClientExists } from "./_private/resultingClientExists.js";
+import { timeout } from "./_private/timeout.js";
+import { waitUntil } from "./_private/waitUntil.js";
+
+// Serwist's internal functions, classes, variables, and more. Feel free to use them,
+// but they are not documented. Note: they do follow semver.
+export {
+  assert,
+  cacheMatchIgnoreParams,
+  canConstructReadableStream,
+  canConstructResponseFromBodyStream,
+  Deferred,
+  dontWaitFor,
+  executeQuotaErrorCallbacks,
+  getFriendlyURL,
+  logger,
+  privateCacheNames,
+  resultingClientExists,
+  SerwistError,
+  timeout,
+  waitUntil,
+};

package/{dist/index.d.cts → src/index.ts}

@@ -1,11 +1,20 @@
+/*
+  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 { cacheNames } from "./cacheNames.js";
 import { clientsClaim } from "./clientsClaim.js";
 import { copyResponse } from "./copyResponse.js";
 import { registerQuotaErrorCallback } from "./registerQuotaErrorCallback.js";
 import { setCacheNameDetails } from "./setCacheNameDetails.js";
+
 /**
  * All Serwist libraries use `@serwist/core` for shared code as well as
  * setting default values that need to be shared (like cache names).
  */
 export { cacheNames, clientsClaim, copyResponse, registerQuotaErrorCallback, setCacheNameDetails };
+
 export * from "./types.js";

package/src/models/messages/messageGenerator.ts

@@ -0,0 +1,28 @@
+/*
+  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 { messages } from "./messages.js";
+
+const fallback = (code: string, ...args: any[]) => {
+  let msg = code;
+  if (args.length > 0) {
+    msg += ` :: ${JSON.stringify(args)}`;
+  }
+  return msg;
+};
+
+const generatorFunction = (code: string, details = {}) => {
+  const message = messages[code];
+  if (!message) {
+    throw new Error(`Unable to find message for code '${code}'.`);
+  }
+
+  return message(details);
+};
+
+export const messageGenerator = process.env.NODE_ENV === "production" ? fallback : generatorFunction;