@serwist/build 8.4.4 → 9.0.0-preview.0

package/src/lib/get-file-manifest-entries.ts

@@ -0,0 +1,126 @@
+/*
+  Copyright 2021 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 from "assert";
+
+import type { FileDetails, GetManifestOptions, GetManifestResult } from "../types.js";
+import { errors } from "./errors.js";
+import { getCompositeDetails } from "./get-composite-details.js";
+import { getFileDetails } from "./get-file-details.js";
+import { getStringDetails } from "./get-string-details.js";
+import { transformManifest } from "./transform-manifest.js";
+
+export async function getFileManifestEntries({
+  additionalPrecacheEntries,
+  dontCacheBustURLsMatching,
+  globDirectory,
+  globFollow,
+  globIgnores,
+  globPatterns = [],
+  globStrict,
+  manifestTransforms,
+  maximumFileSizeToCacheInBytes,
+  modifyURLPrefix,
+  templatedURLs,
+  disablePrecacheManifest,
+}: GetManifestOptions): Promise<GetManifestResult> {
+  if (disablePrecacheManifest) {
+    return {
+      count: 0,
+      size: 0,
+      manifestEntries: undefined,
+      warnings: [],
+    };
+  }
+
+  const warnings: string[] = [];
+  const allFileDetails = new Map<string, FileDetails>();
+
+  try {
+    for (const globPattern of globPatterns) {
+      const { globbedFileDetails, warning } = getFileDetails({
+        globDirectory,
+        globFollow,
+        globIgnores,
+        globPattern,
+        globStrict,
+      });
+
+      if (warning) {
+        warnings.push(warning);
+      }
+
+      for (const details of globbedFileDetails) {
+        if (details && !allFileDetails.has(details.file)) {
+          allFileDetails.set(details.file, details);
+        }
+      }
+    }
+  } catch (error) {
+    // If there's an exception thrown while globbing, then report
+    // it back as a warning, and don't consider it fatal.
+    if (error instanceof Error && error.message) {
+      warnings.push(error.message);
+    }
+  }
+
+  if (templatedURLs) {
+    for (const url of Object.keys(templatedURLs)) {
+      assert(!allFileDetails.has(url), errors["templated-url-matches-glob"]);
+
+      const dependencies = templatedURLs[url];
+      if (Array.isArray(dependencies)) {
+        const details = dependencies.reduce<FileDetails[]>((previous, globPattern) => {
+          try {
+            const { globbedFileDetails, warning } = getFileDetails({
+              globDirectory,
+              globFollow,
+              globIgnores,
+              globPattern,
+              globStrict,
+            });
+
+            if (warning) {
+              warnings.push(warning);
+            }
+
+            return previous.concat(globbedFileDetails);
+          } catch (error) {
+            const debugObj: { [key: string]: string[] } = {};
+            debugObj[url] = dependencies;
+            throw new Error(
+              `${errors["bad-template-urls-asset"]} ` +
+                `'${globPattern}' from '${JSON.stringify(debugObj)}':\n` +
+                `${error instanceof Error ? error.toString() : ""}`,
+            );
+          }
+        }, []);
+        if (details.length === 0) {
+          throw new Error(`${errors["bad-template-urls-asset"]} The glob ` + `pattern '${dependencies.toString()}' did not match anything.`);
+        }
+        allFileDetails.set(url, getCompositeDetails(url, details));
+      } else if (typeof dependencies === "string") {
+        allFileDetails.set(url, getStringDetails(url, dependencies));
+      }
+    }
+  }
+
+  const transformedManifest = await transformManifest({
+    additionalPrecacheEntries,
+    dontCacheBustURLsMatching,
+    manifestTransforms,
+    maximumFileSizeToCacheInBytes,
+    modifyURLPrefix,
+    fileDetails: Array.from(allFileDetails.values()),
+    disablePrecacheManifest,
+  });
+
+  transformedManifest.warnings.push(...warnings);
+
+  return transformedManifest;
+}

package/src/lib/get-file-size.ts

@@ -0,0 +1,23 @@
+/*
+  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 fse from "fs-extra";
+
+import { errors } from "./errors.js";
+
+export function getFileSize(file: string): number | null {
+  try {
+    const stat = fse.statSync(file);
+    if (!stat.isFile()) {
+      return null;
+    }
+    return stat.size;
+  } catch (err) {
+    throw new Error(`${errors["unable-to-get-file-size"]} '${err instanceof Error && err.message ? err.message : ""}'`);
+  }
+}

package/src/lib/get-source-map-url.ts

@@ -0,0 +1,17 @@
+/*
+  Copyright 2022 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.
+*/
+
+// Adapted from https://github.com/lydell/source-map-url/blob/master/source-map-url.js
+// See https://github.com/GoogleChrome/workbox/issues/3019
+const innerRegex = /[#@] sourceMappingURL=([^\s'"]*)/;
+const regex = RegExp(`(?:/\\*(?:\\s*\r?\n(?://)?)?(?:${innerRegex.source})\\s*\\*/|//(?:${innerRegex.source}))\\s*`);
+
+export function getSourceMapURL(srcContents: string): string | null {
+  const match = srcContents.match(regex);
+  return match ? match[1] || match[2] || "" : null;
+}

package/src/lib/get-string-details.ts

@@ -0,0 +1,18 @@
+/*
+  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 { FileDetails } from "../types.js";
+import { getStringHash } from "./get-string-hash.js";
+
+export function getStringDetails(url: string, str: string): FileDetails {
+  return {
+    file: url,
+    hash: getStringHash(str),
+    size: str.length,
+  };
+}

package/src/lib/get-string-hash.ts

@@ -0,0 +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 crypto from "crypto";
+
+export function getStringHash(input: crypto.BinaryLike): string {
+  const md5 = crypto.createHash("md5");
+  md5.update(input);
+  return md5.digest("hex");
+}

package/src/lib/maximum-size-transform.ts

@@ -0,0 +1,29 @@
+/*
+  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 prettyBytes from "pretty-bytes";
+
+import type { ManifestTransform } from "../types.js";
+
+export function maximumSizeTransform(maximumFileSizeToCacheInBytes: number): ManifestTransform {
+  return (originalManifest) => {
+    const warnings: string[] = [];
+    const manifest = originalManifest.filter((entry) => {
+      if (entry.size <= maximumFileSizeToCacheInBytes) {
+        return true;
+      }
+
+      warnings.push(
+        `${entry.url} is ${prettyBytes(entry.size)}, and won't be precached. Configure maximumFileSizeToCacheInBytes to change this limit.`,
+      );
+      return false;
+    });
+
+    return { manifest, warnings };
+  };
+}

package/src/lib/modify-url-prefix-transform.ts

@@ -0,0 +1,55 @@
+/*
+  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 { ManifestTransform } from "../types.js";
+import { errors } from "./errors.js";
+import { escapeRegExp } from "./escape-regexp.js";
+
+export function modifyURLPrefixTransform(modifyURLPrefix: { [key: string]: string }): ManifestTransform {
+  if (!modifyURLPrefix || typeof modifyURLPrefix !== "object" || Array.isArray(modifyURLPrefix)) {
+    throw new Error(errors["modify-url-prefix-bad-prefixes"]);
+  }
+
+  // If there are no entries in modifyURLPrefix, just return an identity
+  // function as a shortcut.
+  if (Object.keys(modifyURLPrefix).length === 0) {
+    return (manifest) => {
+      return { manifest };
+    };
+  }
+
+  for (const key of Object.keys(modifyURLPrefix)) {
+    if (typeof modifyURLPrefix[key] !== "string") {
+      throw new Error(errors["modify-url-prefix-bad-prefixes"]);
+    }
+  }
+
+  // Escape the user input so it's safe to use in a regex.
+  const safeModifyURLPrefixes = Object.keys(modifyURLPrefix).map(escapeRegExp);
+  // Join all the `modifyURLPrefix` keys so a single regex can be used.
+  const prefixMatchesStrings = safeModifyURLPrefixes.join("|");
+  // Add `^` to the front the prefix matches so it only matches the start of
+  // a string.
+  const modifyRegex = new RegExp(`^(${prefixMatchesStrings})`);
+
+  return (originalManifest) => {
+    const manifest = originalManifest.map((entry) => {
+      if (typeof entry.url !== "string") {
+        throw new Error(errors["manifest-entry-bad-url"]);
+      }
+
+      entry.url = entry.url.replace(modifyRegex, (match) => {
+        return modifyURLPrefix[match];
+      });
+
+      return entry;
+    });
+
+    return { manifest };
+  };
+}

package/src/lib/no-revision-for-urls-matching-transform.ts

@@ -0,0 +1,32 @@
+/*
+  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 { ManifestTransform } from "../types.js";
+import { errors } from "./errors.js";
+
+export function noRevisionForURLsMatchingTransform(regexp: RegExp): ManifestTransform {
+  if (!(regexp instanceof RegExp)) {
+    throw new Error(errors["invalid-dont-cache-bust"]);
+  }
+
+  return (originalManifest) => {
+    const manifest = originalManifest.map((entry) => {
+      if (typeof entry.url !== "string") {
+        throw new Error(errors["manifest-entry-bad-url"]);
+      }
+
+      if (entry.url.match(regexp)) {
+        entry.revision = null;
+      }
+
+      return entry;
+    });
+
+    return { manifest };
+  };
+}

package/src/lib/rebase-path.ts

@@ -0,0 +1,22 @@
+/*
+  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 upath from "upath";
+
+export function rebasePath({ baseDirectory, file }: { baseDirectory: string; file: string }): string {
+  // The initial path is relative to the current directory, so make it absolute.
+  const absolutePath = upath.resolve(file);
+
+  // Convert the absolute path so that it's relative to the baseDirectory.
+  const relativePath = upath.relative(baseDirectory, absolutePath);
+
+  // Remove any leading ./ as it won't work in a glob pattern.
+  const normalizedPath = upath.normalize(relativePath);
+
+  return normalizedPath;
+}

package/src/lib/replace-and-update-source-map.ts

@@ -0,0 +1,122 @@
+/*
+  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 type { RawSourceMap } from "source-map";
+import { SourceMapConsumer, SourceMapGenerator } from "source-map";
+
+interface ReplaceAndUpdateSourceMapOptions {
+  /**
+   * The name for the file whose contents
+   * correspond to originalSource.
+   */
+  jsFilename: string;
+  /**
+   * The sourcemap for originalSource,
+   * prior to any replacements.
+   */
+  originalMap: RawSourceMap;
+  /**
+   * The source code, prior to any
+   * replacements.
+   */
+  originalSource: string;
+  /**
+   * A string to swap in for searchString.
+   */
+  replaceString: string;
+  /**
+   * A string in originalSource to replace.
+   * Only the first occurrence will be replaced.
+   */
+  searchString: string;
+}
+
+/**
+ * Adapted from https://github.com/nsams/sourcemap-aware-replace, with modern
+ * JavaScript updates, along with additional properties copied from originalMap.
+ *
+ * @param options
+ * @returns An object containing both
+ * originalSource with the replacement applied, and the modified originalMap.
+ * @private
+ */
+export async function replaceAndUpdateSourceMap({
+  jsFilename,
+  originalMap,
+  originalSource,
+  replaceString,
+  searchString,
+}: ReplaceAndUpdateSourceMapOptions): Promise<{ map: string; source: string }> {
+  const generator = new SourceMapGenerator({
+    file: jsFilename,
+  });
+
+  const consumer = await new SourceMapConsumer(originalMap);
+
+  let pos: number;
+  let src = originalSource;
+  const replacements: { line: number; column: number }[] = [];
+  let lineNum = 0;
+  let filePos = 0;
+
+  const lines = src.split("\n");
+  for (let line of lines) {
+    lineNum++;
+    let searchPos = 0;
+    while ((pos = line.indexOf(searchString, searchPos)) !== -1) {
+      src = src.substring(0, filePos + pos) + replaceString + src.substring(filePos + pos + searchString.length);
+      line = line.substring(0, pos) + replaceString + line.substring(pos + searchString.length);
+      replacements.push({ line: lineNum, column: pos });
+      searchPos = pos + replaceString.length;
+    }
+    filePos += line.length + 1;
+  }
+
+  replacements.reverse();
+
+  consumer.eachMapping((mapping) => {
+    for (const replacement of replacements) {
+      if (replacement.line === mapping.generatedLine && mapping.generatedColumn > replacement.column) {
+        const offset = searchString.length - replaceString.length;
+        mapping.generatedColumn -= offset;
+      }
+    }
+
+    if (mapping.source) {
+      const newMapping = {
+        generated: {
+          line: mapping.generatedLine,
+          column: mapping.generatedColumn,
+        },
+        original: {
+          line: mapping.originalLine,
+          column: mapping.originalColumn,
+        },
+        source: mapping.source,
+      };
+      return generator.addMapping(newMapping);
+    }
+
+    return mapping;
+  });
+
+  consumer.destroy();
+  // JSON.parse returns any.
+  // eslint-disable-next-line  @typescript-eslint/no-unsafe-assignment
+  const updatedSourceMap: RawSourceMap = Object.assign(JSON.parse(generator.toString()), {
+    names: originalMap.names,
+    sourceRoot: originalMap.sourceRoot,
+    sources: originalMap.sources,
+    sourcesContent: originalMap.sourcesContent,
+  });
+
+  return {
+    map: JSON.stringify(updatedSourceMap),
+    source: src,
+  };
+}

package/src/lib/serwist-config-error.ts

@@ -0,0 +1,6 @@
+export class SerwistConfigError extends Error {
+  constructor({ moduleName, message }: { moduleName?: string; message?: string }) {
+    super(`Received an invalid ${moduleName ?? "Serwist"} configuration: ${message}`);
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+}

package/src/lib/transform-manifest.ts

@@ -0,0 +1,158 @@
+/*
+  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 { BasePartial, FileDetails, ManifestEntry, ManifestTransform } from "../types.js";
+import { additionalPrecacheEntriesTransform } from "./additional-precache-entries-transform.js";
+import { errors } from "./errors.js";
+import { maximumSizeTransform } from "./maximum-size-transform.js";
+import { modifyURLPrefixTransform } from "./modify-url-prefix-transform.js";
+import { noRevisionForURLsMatchingTransform } from "./no-revision-for-urls-matching-transform.js";
+
+/**
+ * A `ManifestTransform` function can be used to modify the modify the `url` or
+ * `revision` properties of some or all of the
+ * `@serwist/build.ManifestEntry` in the manifest.
+ *
+ * Deleting the `revision` property of an entry will cause
+ * the corresponding `url` to be precached without cache-busting parameters
+ * applied, which is to say, it implies that the URL itself contains
+ * proper versioning info. If the `revision` property is present, it must be
+ * set to a string.
+ *
+ * @example A transformation that prepended the origin of a CDN for any
+ * URL starting with '/assets/' could be implemented as:
+ *
+ * const cdnTransform = async (manifestEntries) => {
+ *   const manifest = manifestEntries.map(entry => {
+ *     const cdnOrigin = 'https://example.com';
+ *     if (entry.url.startsWith('/assets/')) {
+ *       entry.url = cdnOrigin + entry.url;
+ *     }
+ *     return entry;
+ *   });
+ *   return {manifest, warnings: []};
+ * };
+ *
+ * @example A transformation that nulls the revision field when the
+ * URL contains an 8-character hash surrounded by '.', indicating that it
+ * already contains revision information:
+ *
+ * const removeRevisionTransform = async (manifestEntries) => {
+ *   const manifest = manifestEntries.map(entry => {
+ *     const hashRegExp = /\.\w{8}\./;
+ *     if (entry.url.match(hashRegExp)) {
+ *       entry.revision = null;
+ *     }
+ *     return entry;
+ *   });
+ *   return {manifest, warnings: []};
+ * };
+ *
+ * @callback ManifestTransform
+ * @param manifestEntries The full
+ * array of entries, prior to the current transformation.
+ * @param compilation When used in the webpack plugins, this param
+ * will be set to the current `compilation`.
+ * @returns The array of entries with the transformation applied,
+ * and optionally, any warnings that should be reported back to the build tool.
+ */
+
+interface ManifestTransformResultWithWarnings {
+  count: number;
+  size: number;
+  manifestEntries: ManifestEntry[] | undefined;
+  warnings: string[];
+}
+export async function transformManifest({
+  additionalPrecacheEntries,
+  dontCacheBustURLsMatching,
+  fileDetails,
+  manifestTransforms,
+  maximumFileSizeToCacheInBytes,
+  modifyURLPrefix,
+  transformParam,
+  disablePrecacheManifest,
+}: BasePartial & {
+  fileDetails: FileDetails[];
+  // When this is called by the webpack plugin, transformParam will be the
+  // current webpack compilation.
+  transformParam?: unknown;
+}): Promise<ManifestTransformResultWithWarnings> {
+  if (disablePrecacheManifest) {
+    return {
+      count: 0,
+      size: 0,
+      manifestEntries: undefined,
+      warnings: [],
+    };
+  }
+
+  const allWarnings: string[] = [];
+
+  // Take the array of fileDetail objects and convert it into an array of
+  // {url, revision, size} objects, with \ replaced with /.
+  const normalizedManifest = fileDetails.map((fileDetails) => {
+    return {
+      url: fileDetails.file.replace(/\\/g, "/"),
+      revision: fileDetails.hash,
+      size: fileDetails.size,
+    };
+  });
+
+  const transformsToApply: ManifestTransform[] = [];
+
+  if (maximumFileSizeToCacheInBytes) {
+    transformsToApply.push(maximumSizeTransform(maximumFileSizeToCacheInBytes));
+  }
+
+  if (modifyURLPrefix) {
+    transformsToApply.push(modifyURLPrefixTransform(modifyURLPrefix));
+  }
+
+  if (dontCacheBustURLsMatching) {
+    transformsToApply.push(noRevisionForURLsMatchingTransform(dontCacheBustURLsMatching));
+  }
+
+  // Run any manifestTransforms functions second-to-last.
+  if (manifestTransforms) {
+    transformsToApply.push(...manifestTransforms);
+  }
+
+  // Run additionalPrecacheEntriesTransform last.
+  if (additionalPrecacheEntries) {
+    transformsToApply.push(additionalPrecacheEntriesTransform(additionalPrecacheEntries));
+  }
+
+  let transformedManifest: (ManifestEntry & { size: number })[] = normalizedManifest;
+  for (const transform of transformsToApply) {
+    const result = await transform(transformedManifest, transformParam);
+    if (!("manifest" in result)) {
+      throw new Error(errors["bad-manifest-transforms-return-value"]);
+    }
+
+    transformedManifest = result.manifest;
+    allWarnings.push(...(result.warnings || []));
+  }
+
+  // Generate some metadata about the manifest before we clear out the size
+  // properties from each entry.
+  const count = transformedManifest.length;
+  let size = 0;
+  for (const manifestEntry of transformedManifest as (ManifestEntry & { size?: number })[]) {
+    size += manifestEntry.size || 0;
+    // biome-ignore lint/performance/noDelete: I don't understand this part yet.
+    delete manifestEntry.size;
+  }
+
+  return {
+    count,
+    size,
+    manifestEntries: transformedManifest as ManifestEntry[],
+    warnings: allWarnings,
+  };
+}

package/src/lib/translate-url-to-sourcemap-paths.ts

@@ -0,0 +1,38 @@
+/*
+  Copyright 2021 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 fse from "fs-extra";
+import upath from "upath";
+
+import { errors } from "./errors.js";
+
+export function translateURLToSourcemapPaths(
+  url: string | null,
+  swSrc: string,
+  swDest: string,
+): {
+  destPath: string | undefined;
+  srcPath: string | undefined;
+  warning: string | undefined;
+} {
+  let destPath: string | undefined = undefined;
+  let srcPath: string | undefined = undefined;
+  let warning: string | undefined = undefined;
+
+  if (url && !url.startsWith("data:")) {
+    const possibleSrcPath = upath.resolve(upath.dirname(swSrc), url);
+    if (fse.existsSync(possibleSrcPath)) {
+      srcPath = possibleSrcPath;
+      destPath = upath.resolve(upath.dirname(swDest), url);
+    } else {
+      warning = `${errors["cant-find-sourcemap"]} ${possibleSrcPath}`;
+    }
+  }
+
+  return { destPath, srcPath, warning };
+}

package/src/lib/validate-next-options.ts

@@ -0,0 +1,14 @@
+import { nextInjectManifestOptions } from "../schema/next.js";
+import { validationErrorMap } from "../schema/validationErrorMap.js";
+import type { NextInjectManifestOptionsComplete } from "../types.js";
+import { SerwistConfigError } from "./serwist-config-error.js";
+
+export const validateNextInjectManifestOptions = (input: unknown): NextInjectManifestOptionsComplete => {
+  const result = nextInjectManifestOptions.safeParse(input, {
+    errorMap: validationErrorMap,
+  });
+  if (!result.success) {
+    throw new SerwistConfigError({ moduleName: "@serwist/next", message: JSON.stringify(result.error.format(), null, 2) });
+  }
+  return result.data;
+};