@serwist/utils 10.0.0-preview.1 → 10.0.0-preview.11

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+import { nonNullable } from "./nonNullable.js";
+import { parallel } from "./parallel.js";
+export { nonNullable, parallel };
+export { isAbsolute, resolveBasePath, slash, toUnix } from "./paths.js";
+export type * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC;AACjC,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AACxE,mBAAmB,YAAY,CAAC"}

package/dist/index.js

@@ -26,8 +26,18 @@ const parallel = async (limit, array, func)=>{
     return results;
 };
 
+const slash = (str)=>{
+    return str.replace(/\\/g, "/");
+};
 const toUnix = (p)=>{
-    return p.replace(/\\/g, "/").replace(/(?<!^)\/+/g, "/");
+    return slash(p).replace(/(?<!^)\/+/g, "/");
+};
+const resolveBasePath = (base)=>{
+    if (isAbsolute(base)) return base;
+    return !base.startsWith("/") && !base.startsWith("./") ? `/${base}` : base;
+};
+const isAbsolute = (url)=>{
+    return url.match(/^(?:[a-z]+:)?\/\//i);
 };
 
-export { nonNullable, parallel, toUnix };
+export { isAbsolute, nonNullable, parallel, resolveBasePath, slash, toUnix };

package/dist/index.node.d.ts

@@ -0,0 +1,7 @@
+export { errors } from "./node/errors.js";
+export { getCompositeDetails, getFileHash, getFileSize } from "./node/fs.js";
+export { getStringDetails, getStringHash } from "./node/hash.js";
+export type { Logger, LoggerOptions, LogLevel, LogOptions, LogType } from "./node/log.js";
+export { createLogger, LogLevels } from "./node/log.js";
+export { resolveEntry } from "./node/paths.js";
+//# sourceMappingURL=index.node.d.ts.map

package/dist/index.node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.node.d.ts","sourceRoot":"","sources":["../src/index.node.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC1C,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC7E,OAAO,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACjE,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,QAAQ,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC"}

package/dist/index.node.js

@@ -0,0 +1,202 @@
+import { oneLine } from 'common-tags';
+import crypto from 'node:crypto';
+import fs, { readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { red, yellow, cyan } from 'kolorist';
+import path from 'node:path';
+
+const errors = {
+    "unable-to-get-rootdir": "Unable to get the root directory of your web app.",
+    "no-extension": oneLine`Unable to detect a usable extension for a file in your web
+    app directory.`,
+    "invalid-file-manifest-name": oneLine`The File Manifest Name must have at least one
+    character.`,
+    "unable-to-get-file-manifest-name": "Unable to get a file manifest name.",
+    "invalid-sw-dest": `The 'swDest' value must be a valid path.`,
+    "unable-to-get-sw-name": "Unable to get a service worker file name.",
+    "unable-to-get-save-config": oneLine`An error occurred when asking to save details
+    in a config file.`,
+    "unable-to-get-file-hash": oneLine`An error occurred when attempting to create a
+    file hash.`,
+    "unable-to-get-file-size": oneLine`An error occurred when attempting to get a file
+    size.`,
+    "unable-to-glob-files": "An error occurred when globbing for files.",
+    "unable-to-make-manifest-directory": oneLine`Unable to make output directory for
+    file manifest.`,
+    "read-manifest-template-failure": "Unable to read template for file manifest",
+    "populating-manifest-tmpl-failed": oneLine`An error occurred when populating the
+    file manifest template.`,
+    "manifest-file-write-failure": "Unable to write the file manifest.",
+    "unable-to-make-sw-directory": oneLine`Unable to make the directories to output
+    the service worker path.`,
+    "sw-write-failure": "Unable to write the service worker file.",
+    "sw-write-failure-directory": oneLine`Unable to write the service worker file;
+    'swDest' should be a full path to the file, not a path to a directory.`,
+    "unable-to-copy-serwist-libraries": oneLine`One or more of the Serwist libraries
+    could not be copied over to the destination directory: `,
+    "invalid-glob-directory": oneLine`The supplied globDirectory must be a path as a
+    string.`,
+    "invalid-dont-cache-bust": oneLine`The supplied 'dontCacheBustURLsMatching'
+    parameter must be a RegExp.`,
+    "invalid-exclude-files": "The excluded files should be an array of strings.",
+    "invalid-get-manifest-entries-input": oneLine`The input to
+    'getFileManifestEntries()' must be an object.`,
+    "invalid-manifest-path": oneLine`The supplied manifest path is not a string with
+    at least one character.`,
+    "invalid-manifest-entries": oneLine`The manifest entries must be an array of
+    strings or JavaScript objects containing a url parameter.`,
+    "invalid-manifest-format": oneLine`The value of the 'format' option passed to
+    generateFileManifest() must be either 'iife' (the default) or 'es'.`,
+    "invalid-static-file-globs": oneLine`The 'globPatterns' value must be an array
+    of strings.`,
+    "invalid-templated-urls": oneLine`The 'templatedURLs' value should be an object
+    that maps URLs to either a string, or to an array of glob patterns.`,
+    "templated-url-matches-glob": oneLine`One of the 'templatedURLs' URLs is already
+    being tracked via 'globPatterns': `,
+    "invalid-glob-ignores": oneLine`The 'globIgnores' parameter must be an array of
+    glob pattern strings.`,
+    "manifest-entry-bad-url": oneLine`The generated manifest contains an entry without
+    a URL string. This is likely an error with @serwist/build.`,
+    "modify-url-prefix-bad-prefixes": oneLine`The 'modifyURLPrefix' parameter must be
+    an object with string key value pairs.`,
+    "invalid-inject-manifest-arg": oneLine`The input to 'injectManifest()' must be an
+    object.`,
+    "injection-point-not-found": oneLine`Unable to find a place to inject the manifest.
+    Please ensure that your service worker file contains the following: `,
+    "multiple-injection-points": oneLine`Please ensure that your 'swSrc' file contains
+    only one match for the following: `,
+    "useless-glob-pattern": oneLine`One of the glob patterns doesn't match any files.
+    Please remove or fix the following: `,
+    "bad-template-urls-asset": oneLine`There was an issue using one of the provided
+    'templatedURLs'.`,
+    "invalid-generate-file-manifest-arg": oneLine`The input to generateFileManifest()
+    must be an Object.`,
+    "invalid-sw-src": `The 'swSrc' file can't be read.`,
+    "same-src-and-dest": oneLine`Unable to find a place to inject the manifest. This is
+    likely because swSrc and swDest are configured to the same file.
+    Please ensure that your swSrc file contains the following:`,
+    "no-module-name": oneLine`You must provide a moduleName parameter when calling
+    getModuleURL().`,
+    "bad-manifest-transforms-return-value": oneLine`The return value from a
+    manifestTransform should be an object with 'manifest' and optionally
+    'warnings' properties.`,
+    "string-entry-warning": oneLine`Some items were passed to additionalPrecacheEntries
+    without revisioning info. This is generally NOT safe. Learn more at
+    https://bit.ly/wb-precache.`,
+    "cant-find-sourcemap": oneLine`The swSrc file refers to a sourcemap that can't be
+    opened:`,
+    "manifest-transforms": oneLine`When using manifestTransforms, you must provide
+    an array of functions.`
+};
+
+const getStringHash = (input)=>{
+    const md5 = crypto.createHash("md5");
+    md5.update(input);
+    return md5.digest("hex");
+};
+const getStringDetails = (url, str)=>({
+        file: url,
+        hash: getStringHash(str),
+        size: str.length
+    });
+
+const getFileHash = (file)=>{
+    try {
+        return getStringHash(fs.readFileSync(file));
+    } catch (err) {
+        throw new Error(`${errors["unable-to-get-file-hash"]} '${err instanceof Error && err.message ? err.message : ""}'`);
+    }
+};
+const getFileSize = (file)=>{
+    try {
+        const stat = fs.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 : ""}'`);
+    }
+};
+const getCompositeDetails = (compositeURL, dependencyDetails)=>{
+    let totalSize = 0;
+    let compositeHash = "";
+    for (const fileDetails of dependencyDetails){
+        totalSize += fileDetails.size;
+        compositeHash += fileDetails.hash === null ? "" : fileDetails.hash;
+    }
+    const md5 = crypto.createHash("md5");
+    md5.update(compositeHash);
+    const hashOfHashes = md5.digest("hex");
+    return {
+        file: compositeURL,
+        hash: hashOfHashes,
+        size: totalSize
+    };
+};
+
+const LogLevels = {
+    silent: 0,
+    error: 1,
+    warn: 2,
+    info: 3
+};
+const require = createRequire(import.meta.url);
+const createLogger = (level = "info", options = {})=>{
+    const { prefix: _prefix = "serwist", showVersion = true, allowClearScreen = true } = options;
+    const packageJson = showVersion ? JSON.parse(readFileSync(require.resolve("@serwist/utils/package.json"), "utf-8")) : null;
+    const prefix = `${_prefix}${showVersion ? ` v${packageJson.version}` : ""}`;
+    const thresh = LogLevels[level];
+    const canClearScreen = allowClearScreen && process.stdout.isTTY && !process.env.CI;
+    const clear = canClearScreen ? console.clear : ()=>{};
+    const output = (type, msg, options = {})=>{
+        if (thresh >= LogLevels[type]) {
+            const method = type === "info" ? "log" : type;
+            if (options.clear) clear();
+            let tag = type === "error" ? red(prefix) : type === "warn" ? yellow(prefix) : cyan(prefix);
+            console[method](`${options.skipLine ? "\n" : ""}${tag} ${msg}`);
+        }
+    };
+    const warnedMessages = new Set();
+    return {
+        info (msg, opts) {
+            output("info", msg, opts);
+        },
+        warn (msg, opts) {
+            output("warn", msg, opts);
+        },
+        warnOnce (msg, opts) {
+            if (warnedMessages.has(msg)) return;
+            output("warn", msg, opts);
+            warnedMessages.add(msg);
+        },
+        error (msg, opts) {
+            output("error", msg, opts);
+        },
+        clearScreen (type) {
+            if (thresh >= LogLevels[type]) {
+                clear();
+            }
+        }
+    };
+};
+
+const resolveEntry = (entry)=>{
+    if (fs.existsSync(entry)) {
+        const stats = fs.statSync(entry);
+        if (stats.isDirectory()) {
+            return resolveEntry(path.join(entry, "index"));
+        }
+        return entry;
+    }
+    const dir = path.dirname(entry);
+    if (fs.existsSync(dir)) {
+        const base = path.basename(entry);
+        const files = fs.readdirSync(dir);
+        const found = files.find((file)=>file.replace(/\.[^.]+$/, "") === base);
+        if (found) return path.join(dir, found);
+    }
+    return null;
+};
+
+export { LogLevels, createLogger, errors, getCompositeDetails, getFileHash, getFileSize, getStringDetails, getStringHash, resolveEntry };

package/dist/node/errors.d.ts

@@ -0,0 +1,47 @@
+export declare const errors: {
+    "unable-to-get-rootdir": string;
+    "no-extension": string;
+    "invalid-file-manifest-name": string;
+    "unable-to-get-file-manifest-name": string;
+    "invalid-sw-dest": string;
+    "unable-to-get-sw-name": string;
+    "unable-to-get-save-config": string;
+    "unable-to-get-file-hash": string;
+    "unable-to-get-file-size": string;
+    "unable-to-glob-files": string;
+    "unable-to-make-manifest-directory": string;
+    "read-manifest-template-failure": string;
+    "populating-manifest-tmpl-failed": string;
+    "manifest-file-write-failure": string;
+    "unable-to-make-sw-directory": string;
+    "sw-write-failure": string;
+    "sw-write-failure-directory": string;
+    "unable-to-copy-serwist-libraries": string;
+    "invalid-glob-directory": string;
+    "invalid-dont-cache-bust": string;
+    "invalid-exclude-files": string;
+    "invalid-get-manifest-entries-input": string;
+    "invalid-manifest-path": string;
+    "invalid-manifest-entries": string;
+    "invalid-manifest-format": string;
+    "invalid-static-file-globs": string;
+    "invalid-templated-urls": string;
+    "templated-url-matches-glob": string;
+    "invalid-glob-ignores": string;
+    "manifest-entry-bad-url": string;
+    "modify-url-prefix-bad-prefixes": string;
+    "invalid-inject-manifest-arg": string;
+    "injection-point-not-found": string;
+    "multiple-injection-points": string;
+    "useless-glob-pattern": string;
+    "bad-template-urls-asset": string;
+    "invalid-generate-file-manifest-arg": string;
+    "invalid-sw-src": string;
+    "same-src-and-dest": string;
+    "no-module-name": string;
+    "bad-manifest-transforms-return-value": string;
+    "string-entry-warning": string;
+    "cant-find-sourcemap": string;
+    "manifest-transforms": string;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/node/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/node/errors.ts"],"names":[],"mappings":"AASA,eAAO,MAAM,MAAM;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkFlB,CAAC"}

package/dist/node/fs.d.ts

@@ -0,0 +1,6 @@
+import fs from "node:fs";
+import type { FileDetails } from "../types.js";
+export declare const getFileHash: (file: fs.PathOrFileDescriptor) => string;
+export declare const getFileSize: (file: string) => number | null;
+export declare const getCompositeDetails: (compositeURL: string, dependencyDetails: FileDetails[]) => FileDetails;
+//# sourceMappingURL=fs.d.ts.map

package/dist/node/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/node/fs.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAI/C,eAAO,MAAM,WAAW,GAAI,MAAM,EAAE,CAAC,oBAAoB,WAMxD,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,MAAM,MAAM,KAAG,MAAM,GAAG,IAUnD,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAAI,cAAc,MAAM,EAAE,mBAAmB,WAAW,EAAE,KAAG,WAkB5F,CAAC"}

package/dist/node/hash.d.ts

@@ -0,0 +1,5 @@
+import crypto from "node:crypto";
+import type { FileDetails } from "../types.js";
+export declare const getStringHash: (input: crypto.BinaryLike) => string;
+export declare const getStringDetails: (url: string, str: string) => FileDetails;
+//# sourceMappingURL=hash.d.ts.map

package/dist/node/hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.d.ts","sourceRoot":"","sources":["../../src/node/hash.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,eAAO,MAAM,aAAa,GAAI,OAAO,MAAM,CAAC,UAAU,KAAG,MAIxD,CAAC;AAEF,eAAO,MAAM,gBAAgB,GAAI,KAAK,MAAM,EAAE,KAAK,MAAM,KAAG,WAI1D,CAAC"}

package/dist/node/log.d.ts

@@ -0,0 +1,21 @@
+export type LogType = "error" | "warn" | "info";
+export type LogLevel = LogType | "silent";
+export interface LogOptions {
+    clear?: boolean;
+    skipLine?: boolean;
+}
+export declare const LogLevels: Record<LogLevel, number>;
+export interface LoggerOptions {
+    prefix?: string;
+    showVersion?: boolean;
+    allowClearScreen?: boolean;
+}
+export interface Logger {
+    info(msg: string, options?: LogOptions): void;
+    warn(msg: string, options?: LogOptions): void;
+    warnOnce(msg: string, options?: LogOptions): void;
+    error(msg: string, options?: LogOptions): void;
+    clearScreen(type: LogType): void;
+}
+export declare const createLogger: (level?: LogLevel, options?: LoggerOptions) => Logger;
+//# sourceMappingURL=log.d.ts.map

package/dist/node/log.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"log.d.ts","sourceRoot":"","sources":["../../src/node/log.ts"],"names":[],"mappings":"AAIA,MAAM,MAAM,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,CAAC;AAChD,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAC1C,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AACD,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,QAAQ,EAAE,MAAM,CAK9C,CAAC;AAEF,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,MAAM,WAAW,MAAM;IACrB,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9C,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9C,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAClD,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/C,WAAW,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CAClC;AAID,eAAO,MAAM,YAAY,GAAI,QAAO,QAAiB,EAAE,UAAS,aAAkB,KAAG,MAqCpF,CAAC"}

package/dist/node/paths.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Resolves a file path without extension. Also handles `/index` if the path
+ * actually points to a directory.
+ * @param ctx
+ * @param api
+ * @returns
+ */
+export declare const resolveEntry: (entry: string) => string | null;
+//# sourceMappingURL=paths.d.ts.map

package/dist/node/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/node/paths.ts"],"names":[],"mappings":"AAKA;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,KAAG,MAAM,GAAG,IAqBrD,CAAC"}

package/dist/nonNullable.d.ts

@@ -0,0 +1,2 @@
+export declare const nonNullable: <T>(value: T) => value is NonNullable<T>;
+//# sourceMappingURL=nonNullable.d.ts.map

package/dist/nonNullable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"nonNullable.d.ts","sourceRoot":"","sources":["../src/nonNullable.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,GAAI,CAAC,EAAE,OAAO,CAAC,KAAG,KAAK,IAAI,WAAW,CAAC,CAAC,CAA0C,CAAC"}

package/dist/parallel.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Executes many async functions in parallel. Returns the
+ * results from all functions as an array. Does not handle
+ * any error.
+ */
+export declare const parallel: <T, K>(limit: number, array: readonly T[], func: (item: T) => Promise<K>) => Promise<K[]>;
+//# sourceMappingURL=parallel.d.ts.map

package/dist/parallel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parallel.d.ts","sourceRoot":"","sources":["../src/parallel.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,eAAO,MAAM,QAAQ,GAAU,CAAC,EAAE,CAAC,EAAE,OAAO,MAAM,EAAE,OAAO,SAAS,CAAC,EAAE,EAAE,MAAM,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC,CAAC,CAAC,KAAG,OAAO,CAAC,CAAC,EAAE,CA4BnH,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,5 @@
+export declare const slash: (str: string) => string;
+export declare const toUnix: (p: string) => string;
+export declare const resolveBasePath: (base: string) => string;
+export declare const isAbsolute: (url: string) => RegExpMatchArray | null;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,KAAK,GAAI,KAAK,MAAM,WAEhC,CAAC;AAEF,eAAO,MAAM,MAAM,GAAI,GAAG,MAAM,WAE/B,CAAC;AAEF,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,WAG3C,CAAC;AAEF,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,4BAErC,CAAC"}

package/dist/types.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Makes certain fields in a object type required
+ *
+ * @example
+ *     interface A {
+ *         a?: string;
+ *         b?: string;
+ *         c?: string;
+ *     }
+ *     type B = RequiredFields<A, "b" | "c">;
+ *     const b: B = {
+ *         b: "hehe",
+ *         c: "hehe",
+ *     }; //valid
+ *     const b: B = { a: "hehe" }; //invalid
+ *     const c: B = { a: "hehe", b: "hehe" }; //invalid
+ */
+export type Require<T, U extends keyof T> = T & Required<Pick<T, U>>;
+/**
+ * Makes certain fields in a object type optional
+ *
+ * @example
+ *     interface A {
+ *         a: string;
+ *         b: string;
+ *         c: string;
+ *     }
+ *     type B = Optional<A, "b" | "c">;
+ *     const b: B = { a: "hehe" }; //valid
+ *     const b: B = {}; //invalid
+ */
+export type Optional<T, U extends keyof T> = Omit<T, U> & Partial<Pick<T, U>>;
+/**
+ * Makes an object type's hover overlay more readable
+ *
+ * @example
+ *
+ * interface A {
+ *   b: string;
+ *   c: boolean;
+ * }
+ *
+ * interface B {
+ *   c: number;
+ * }
+ *
+ * type D = A | B; // Displayed as is written
+ *
+ * type C = Prettify<A | B>; // { b: string; c: boolean; } | { c: number; }
+ */
+export type Prettify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export interface FileDetails {
+    file: string;
+    hash: string | null;
+    size: number;
+}
+export type MaybePromise<T> = T | Promise<T>;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,MAAM,OAAO,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAErE;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,EAAE,CAAC,SAAS,MAAM,CAAC,IAAI,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAE9E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,QAAQ,CAAC,CAAC,IAAI;KACvB,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;CACrB,GAAG,EAAE,CAAC;AAEP,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,10 +1,12 @@
 {
   "name": "@serwist/utils",
-  "version": "10.0.0-preview.1",
+  "version": "10.0.0-preview.11",
   "type": "module",
+  "sideEffects": false,
   "description": "This module contains internal utilities used by Serwist packages.",
   "files": [
-    "src"
+    "src",
+    "dist"
   ],
   "keywords": [
     "serwist",
@@ -19,22 +21,39 @@
   "homepage": "https://serwist.pages.dev",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "node": {
+      "*": [
+        "./dist/index.node.d.ts"
+      ]
+    }
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./node": {
+      "types": "./dist/index.node.d.ts",
+      "default": "./dist/index.node.js"
+    },
     "./package.json": "./package.json"
   },
+  "dependencies": {
+    "common-tags": "1.8.2",
+    "kolorist": "1.8.0"
+  },
   "devDependencies": {
-    "rollup": "4.34.8",
-    "typescript": "5.7.3",
-    "@serwist/configs": "10.0.0-preview.1"
+    "@types/common-tags": "1.8.4",
+    "rollup": "4.45.1",
+    "typescript": "5.8.3",
+    "@serwist/configs": "10.0.0-preview.11"
   },
   "scripts": {
     "build": "rimraf dist && NODE_ENV=production rollup --config rollup.config.js",
     "dev": "rollup --config rollup.config.js --watch",
     "lint": "biome lint ./src",
+    "qcheck": "biome check ./src",
     "typecheck": "tsc"
   }
 }

package/src/index.node.ts

@@ -0,0 +1,6 @@
+export { errors } from "./node/errors.js";
+export { getCompositeDetails, getFileHash, getFileSize } from "./node/fs.js";
+export { getStringDetails, getStringHash } from "./node/hash.js";
+export type { Logger, LoggerOptions, LogLevel, LogOptions, LogType } from "./node/log.js";
+export { createLogger, LogLevels } from "./node/log.js";
+export { resolveEntry } from "./node/paths.js";

package/src/index.ts

@@ -1,7 +1,6 @@
 import { nonNullable } from "./nonNullable.js";
 import { parallel } from "./parallel.js";
-import { toUnix } from "./toUnix.js";
-
-export { nonNullable, parallel, toUnix };
 
+export { nonNullable, parallel };
+export { isAbsolute, resolveBasePath, slash, toUnix } from "./paths.js";
 export type * from "./types.js";

package/src/node/errors.ts

@@ -0,0 +1,92 @@
+/*
+  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 { oneLine as ol } from "common-tags";
+
+export const errors = {
+  "unable-to-get-rootdir": "Unable to get the root directory of your web app.",
+  "no-extension": ol`Unable to detect a usable extension for a file in your web
+    app directory.`,
+  "invalid-file-manifest-name": ol`The File Manifest Name must have at least one
+    character.`,
+  "unable-to-get-file-manifest-name": "Unable to get a file manifest name.",
+  "invalid-sw-dest": `The 'swDest' value must be a valid path.`,
+  "unable-to-get-sw-name": "Unable to get a service worker file name.",
+  "unable-to-get-save-config": ol`An error occurred when asking to save details
+    in a config file.`,
+  "unable-to-get-file-hash": ol`An error occurred when attempting to create a
+    file hash.`,
+  "unable-to-get-file-size": ol`An error occurred when attempting to get a file
+    size.`,
+  "unable-to-glob-files": "An error occurred when globbing for files.",
+  "unable-to-make-manifest-directory": ol`Unable to make output directory for
+    file manifest.`,
+  "read-manifest-template-failure": "Unable to read template for file manifest",
+  "populating-manifest-tmpl-failed": ol`An error occurred when populating the
+    file manifest template.`,
+  "manifest-file-write-failure": "Unable to write the file manifest.",
+  "unable-to-make-sw-directory": ol`Unable to make the directories to output
+    the service worker path.`,
+  "sw-write-failure": "Unable to write the service worker file.",
+  "sw-write-failure-directory": ol`Unable to write the service worker file;
+    'swDest' should be a full path to the file, not a path to a directory.`,
+  "unable-to-copy-serwist-libraries": ol`One or more of the Serwist libraries
+    could not be copied over to the destination directory: `,
+  "invalid-glob-directory": ol`The supplied globDirectory must be a path as a
+    string.`,
+  "invalid-dont-cache-bust": ol`The supplied 'dontCacheBustURLsMatching'
+    parameter must be a RegExp.`,
+  "invalid-exclude-files": "The excluded files should be an array of strings.",
+  "invalid-get-manifest-entries-input": ol`The input to
+    'getFileManifestEntries()' must be an object.`,
+  "invalid-manifest-path": ol`The supplied manifest path is not a string with
+    at least one character.`,
+  "invalid-manifest-entries": ol`The manifest entries must be an array of
+    strings or JavaScript objects containing a url parameter.`,
+  "invalid-manifest-format": ol`The value of the 'format' option passed to
+    generateFileManifest() must be either 'iife' (the default) or 'es'.`,
+  "invalid-static-file-globs": ol`The 'globPatterns' value must be an array
+    of strings.`,
+  "invalid-templated-urls": ol`The 'templatedURLs' value should be an object
+    that maps URLs to either a string, or to an array of glob patterns.`,
+  "templated-url-matches-glob": ol`One of the 'templatedURLs' URLs is already
+    being tracked via 'globPatterns': `,
+  "invalid-glob-ignores": ol`The 'globIgnores' parameter must be an array of
+    glob pattern strings.`,
+  "manifest-entry-bad-url": ol`The generated manifest contains an entry without
+    a URL string. This is likely an error with @serwist/build.`,
+  "modify-url-prefix-bad-prefixes": ol`The 'modifyURLPrefix' parameter must be
+    an object with string key value pairs.`,
+  "invalid-inject-manifest-arg": ol`The input to 'injectManifest()' must be an
+    object.`,
+  "injection-point-not-found": ol`Unable to find a place to inject the manifest.
+    Please ensure that your service worker file contains the following: `,
+  "multiple-injection-points": ol`Please ensure that your 'swSrc' file contains
+    only one match for the following: `,
+  "useless-glob-pattern": ol`One of the glob patterns doesn't match any files.
+    Please remove or fix the following: `,
+  "bad-template-urls-asset": ol`There was an issue using one of the provided
+    'templatedURLs'.`,
+  "invalid-generate-file-manifest-arg": ol`The input to generateFileManifest()
+    must be an Object.`,
+  "invalid-sw-src": `The 'swSrc' file can't be read.`,
+  "same-src-and-dest": ol`Unable to find a place to inject the manifest. This is
+    likely because swSrc and swDest are configured to the same file.
+    Please ensure that your swSrc file contains the following:`,
+  "no-module-name": ol`You must provide a moduleName parameter when calling
+    getModuleURL().`,
+  "bad-manifest-transforms-return-value": ol`The return value from a
+    manifestTransform should be an object with 'manifest' and optionally
+    'warnings' properties.`,
+  "string-entry-warning": ol`Some items were passed to additionalPrecacheEntries
+    without revisioning info. This is generally NOT safe. Learn more at
+    https://bit.ly/wb-precache.`,
+  "cant-find-sourcemap": ol`The swSrc file refers to a sourcemap that can't be
+    opened:`,
+  "manifest-transforms": ol`When using manifestTransforms, you must provide
+    an array of functions.`,
+};

package/src/node/fs.ts

@@ -0,0 +1,45 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import type { FileDetails } from "../types.js";
+import { errors } from "./errors.js";
+import { getStringHash } from "./hash.js";
+
+export const getFileHash = (file: fs.PathOrFileDescriptor) => {
+  try {
+    return getStringHash(fs.readFileSync(file));
+  } catch (err) {
+    throw new Error(`${errors["unable-to-get-file-hash"]} '${err instanceof Error && err.message ? err.message : ""}'`);
+  }
+};
+
+export const getFileSize = (file: string): number | null => {
+  try {
+    const stat = fs.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 : ""}'`);
+  }
+};
+
+export const getCompositeDetails = (compositeURL: string, dependencyDetails: FileDetails[]): FileDetails => {
+  let totalSize = 0;
+  let compositeHash = "";
+
+  for (const fileDetails of dependencyDetails) {
+    totalSize += fileDetails.size;
+    compositeHash += fileDetails.hash === null ? "" : fileDetails.hash;
+  }
+
+  const md5 = crypto.createHash("md5");
+  md5.update(compositeHash);
+  const hashOfHashes = md5.digest("hex");
+
+  return {
+    file: compositeURL,
+    hash: hashOfHashes,
+    size: totalSize,
+  };
+};

package/src/node/hash.ts

@@ -0,0 +1,14 @@
+import crypto from "node:crypto";
+import type { FileDetails } from "../types.js";
+
+export const getStringHash = (input: crypto.BinaryLike): string => {
+  const md5 = crypto.createHash("md5");
+  md5.update(input);
+  return md5.digest("hex");
+};
+
+export const getStringDetails = (url: string, str: string): FileDetails => ({
+  file: url,
+  hash: getStringHash(str),
+  size: str.length,
+});

package/src/node/log.ts

@@ -0,0 +1,71 @@
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { cyan, red, yellow } from "kolorist";
+
+export type LogType = "error" | "warn" | "info";
+export type LogLevel = LogType | "silent";
+export interface LogOptions {
+  clear?: boolean;
+  skipLine?: boolean;
+}
+export const LogLevels: Record<LogLevel, number> = {
+  silent: 0,
+  error: 1,
+  warn: 2,
+  info: 3,
+};
+
+export interface LoggerOptions {
+  prefix?: string;
+  showVersion?: boolean;
+  allowClearScreen?: boolean;
+}
+
+export interface Logger {
+  info(msg: string, options?: LogOptions): void;
+  warn(msg: string, options?: LogOptions): void;
+  warnOnce(msg: string, options?: LogOptions): void;
+  error(msg: string, options?: LogOptions): void;
+  clearScreen(type: LogType): void;
+}
+
+const require = createRequire(import.meta.url);
+
+export const createLogger = (level: LogLevel = "info", options: LoggerOptions = {}): Logger => {
+  const { prefix: _prefix = "serwist", showVersion = true, allowClearScreen = true } = options;
+  const packageJson = showVersion ? JSON.parse(readFileSync(require.resolve("@serwist/utils/package.json"), "utf-8")) : null;
+  const prefix = `${_prefix}${showVersion ? ` v${packageJson.version}` : ""}`;
+  const thresh = LogLevels[level];
+  const canClearScreen = allowClearScreen && process.stdout.isTTY && !process.env.CI;
+  const clear = canClearScreen ? console.clear : () => {};
+  const output = (type: LogType, msg: string, options: LogOptions = {}) => {
+    if (thresh >= LogLevels[type]) {
+      const method = type === "info" ? "log" : type;
+      if (options.clear) clear();
+      let tag = type === "error" ? red(prefix) : type === "warn" ? yellow(prefix) : cyan(prefix);
+      console[method](`${options.skipLine ? "\n" : ""}${tag} ${msg}`);
+    }
+  };
+  const warnedMessages = new Set<string>();
+  return {
+    info(msg, opts) {
+      output("info", msg, opts);
+    },
+    warn(msg, opts) {
+      output("warn", msg, opts);
+    },
+    warnOnce(msg, opts) {
+      if (warnedMessages.has(msg)) return;
+      output("warn", msg, opts);
+      warnedMessages.add(msg);
+    },
+    error(msg, opts) {
+      output("error", msg, opts);
+    },
+    clearScreen(type) {
+      if (thresh >= LogLevels[type]) {
+        clear();
+      }
+    },
+  } satisfies Logger;
+};

package/src/node/paths.ts

@@ -0,0 +1,34 @@
+import fs from "node:fs";
+import path from "node:path";
+
+// Source: https://github.com/sveltejs/kit/blob/6419d3eaa7bf1b0a756b28f06a73f71fe042de0a/packages/kit/src/utils/filesystem.js
+// License: MIT
+/**
+ * Resolves a file path without extension. Also handles `/index` if the path
+ * actually points to a directory.
+ * @param ctx
+ * @param api
+ * @returns
+ */
+export const resolveEntry = (entry: string): string | null => {
+  if (fs.existsSync(entry)) {
+    const stats = fs.statSync(entry);
+    if (stats.isDirectory()) {
+      return resolveEntry(path.join(entry, "index"));
+    }
+
+    return entry;
+  }
+  const dir = path.dirname(entry);
+
+  if (fs.existsSync(dir)) {
+    const base = path.basename(entry);
+    const files = fs.readdirSync(dir);
+
+    const found = files.find((file) => file.replace(/\.[^.]+$/, "") === base);
+
+    if (found) return path.join(dir, found);
+  }
+
+  return null;
+};

package/src/paths.ts

@@ -0,0 +1,16 @@
+export const slash = (str: string) => {
+  return str.replace(/\\/g, "/");
+};
+
+export const toUnix = (p: string) => {
+  return slash(p).replace(/(?<!^)\/+/g, "/");
+};
+
+export const resolveBasePath = (base: string) => {
+  if (isAbsolute(base)) return base;
+  return !base.startsWith("/") && !base.startsWith("./") ? `/${base}` : base;
+};
+
+export const isAbsolute = (url: string) => {
+  return url.match(/^(?:[a-z]+:)?\/\//i);
+};

package/src/types.ts

@@ -53,3 +53,11 @@ export type Optional<T, U extends keyof T> = Omit<T, U> & Partial<Pick<T, U>>;
 export type Prettify<T> = {
   [K in keyof T]: T[K];
 } & {};
+
+export interface FileDetails {
+  file: string;
+  hash: string | null;
+  size: number;
+}
+
+export type MaybePromise<T> = T | Promise<T>;

package/src/toUnix.ts

@@ -1,3 +0,0 @@
-export const toUnix = (p: string) => {
-  return p.replace(/\\/g, "/").replace(/(?<!^)\/+/g, "/");
-};