zilla-util 1.2.27

package/src/package.ts

@@ -0,0 +1,39 @@
+import { GenericLogger } from "./logger.js";
+
+const packageJsonUrl = async (startUrl: URL): Promise<URL | null> => {
+    let currentUrl = new URL(startUrl);
+
+    while (true) {
+        const packageUrl = new URL("package.json", currentUrl);
+        try {
+            const packageJson = await import(packageUrl.toString(), { assert: { type: "json" } });
+            if (packageJson) return packageUrl; // Found package.json
+        } catch {
+            const parentUrl = new URL("..", currentUrl);
+            if (parentUrl.toString() === currentUrl.toString()) break; // Stop if we reach the root
+            currentUrl = parentUrl; // Move up one level
+        }
+    }
+    return null; // Not found
+};
+
+export const packageVersion = async (
+    importMetaUrl: string = import.meta.url,
+    logger?: GenericLogger
+): Promise<string | undefined> => {
+    try {
+        const packageUrl = await packageJsonUrl(new URL(importMetaUrl));
+        if (!packageUrl) throw new Error("package.json not found");
+
+        const packageJson = await import(packageUrl.toString(), { assert: { type: "json" } });
+        return packageJson.version;
+    } catch (e) {
+        const msg = `packageVersion importMetaUrl=${importMetaUrl} error determining package version: error=${e}`;
+        if (logger) {
+            logger.error(msg, e);
+        } else {
+            console.error(msg);
+        }
+        return undefined;
+    }
+};

package/src/retry.ts

@@ -0,0 +1,71 @@
+import { sleep } from "./time.js";
+import { GenericLogger } from "./logger.js";
+import {safeStringify} from "./string.js";
+
+export type RetryOptions = {
+    maxAttempts?: number;
+    backoffBaseMillis?: number;
+    backoffMultiplier?: number;
+    canRetry?: (e: Error) => Promise<boolean> | boolean;
+};
+
+export const DEFAULT_RETRY_MAX_ATTEMPTS = 3;
+export const DEFAULT_RETRY_BACKOFF_BASE_MILLIS = 250;
+export const DEFAULT_RETRY_BACKOFF_MULTIPLIER = 3;
+export const DEFAULT_RETRY_CAN_RETRY_FUNC = () => true;
+
+export const DEFAULT_RETRY_OPTS: RetryOptions = {
+    maxAttempts: DEFAULT_RETRY_MAX_ATTEMPTS,
+    backoffBaseMillis: DEFAULT_RETRY_BACKOFF_BASE_MILLIS,
+    backoffMultiplier: DEFAULT_RETRY_BACKOFF_MULTIPLIER,
+    canRetry: DEFAULT_RETRY_CAN_RETRY_FUNC,
+};
+
+export const retry = async <T>(
+    fn: () => Promise<T>,
+    opts?: RetryOptions,
+    logger?: GenericLogger,
+    action?: string
+): Promise<T> => {
+    const maxAttempts = opts?.maxAttempts || DEFAULT_RETRY_MAX_ATTEMPTS;
+    const backoffBaseMillis = opts?.backoffBaseMillis || DEFAULT_RETRY_BACKOFF_BASE_MILLIS;
+    const backoffMultiplier = opts?.backoffMultiplier || DEFAULT_RETRY_BACKOFF_MULTIPLIER;
+    const canRetry = opts?.canRetry || DEFAULT_RETRY_CAN_RETRY_FUNC;
+    const prefix = logger ? (action ? `@@@ retry[${action}]:` : "retry:") : "";
+    let backoffTime = backoffBaseMillis;
+    let error;
+    if (logger && logger.isDebugEnabled()) {
+        logger.debug(`${prefix} starting with opts=${opts ? safeStringify(opts) : "undefined"}`);
+    }
+    for (let i = 0; i < maxAttempts; i++) {
+        const iPrefix = `${prefix} [${i + 1}/${maxAttempts}]:`;
+        if (i > 0) {
+            if (logger && logger.isDebugEnabled()) {
+                logger.debug(`${iPrefix} waiting for ${backoffTime} before retrying`);
+            }
+            await sleep(backoffTime);
+            backoffTime = Math.floor(backoffTime * backoffMultiplier);
+        }
+        try {
+            if (logger && logger.isDebugEnabled()) {
+                logger.debug(`${iPrefix} calling function`);
+            }
+            return await fn();
+        } catch (e) {
+            error = e;
+            if (!(await canRetry(e as Error))) {
+                if (logger && logger.isDebugEnabled()) {
+                    logger.debug(`${iPrefix} function threw error and canRetry=false, throwing e=${e}`, e as Error);
+                }
+                throw e;
+            }
+            if (logger && logger.isDebugEnabled()) {
+                logger.debug(`${iPrefix} function threw error=${e} and canRetry=true, continuing`, e as Error);
+            }
+        }
+    }
+    if (logger && logger.isDebugEnabled()) {
+        logger.debug(`${prefix} maxAttempts exceeded, throwing most recent error=${error}`, error as Error);
+    }
+    throw error;
+};

package/src/string.ts

@@ -0,0 +1,338 @@
+import { ZillaClock } from "./time.js";
+import { GenericLogger } from "./logger.js";
+import GraphemeSplitter from "grapheme-splitter";
+
+export const capitalize = (s?: string): string =>
+    s && s.length > 0 ? s.substring(0, 1).toUpperCase() + s.substring(1) : "";
+
+export const uncapitalize = (s?: string): string =>
+    s && s.length > 0 ? s.substring(0, 1).toLowerCase() + s.substring(1) : "";
+
+export const basefilename = (s: string): string => {
+    if (!s) return s; // return null/undefined as-is
+
+    // drop trailing slashes
+    while (s.endsWith("/")) {
+        s = s.substring(0, s.length - 1);
+    }
+    const i = s ? s.lastIndexOf("/") : -1;
+    return i === -1 ? s : s.substring(i + 1);
+};
+
+export const ext = (s: string): string => {
+    if (!s) return s; // return null/undefined/no-dot files as-is
+    const dot = s.lastIndexOf(".");
+    return dot === -1 || dot === s.length - 1 ? "" : s.substring(dot + 1);
+};
+
+export const basefilenameWithoutExt = (s: string): string => {
+    s = basefilename(s);
+    if (!s) return s; // return null/undefined as-is
+
+    // drop trailing dots
+    while (s.endsWith(".")) {
+        s = s.substring(0, s.length - 1);
+    }
+    const i = s ? s.lastIndexOf(".") : -1;
+    return i === -1 ? s : s.substring(0, i);
+};
+
+export const dateAsYYYYMMDD = (date: Date): string =>
+    `${date.getFullYear()}-${(date.getMonth() + 1).toString().padStart(2, "0")}-${date
+        .getDate()
+        .toString()
+        .padStart(2, "0")}`;
+
+export const dateAsUTCYYYYMMDD = (date: Date): string =>
+    `${date.getUTCFullYear()}-${(date.getUTCMonth() + 1).toString().padStart(2, "0")}-${date
+        .getUTCDate()
+        .toString()
+        .padStart(2, "0")}`;
+
+export const nextDateAsYYYYMMDD = (d: string): string => {
+    const dt = new Date(`${d}T00:00:00Z`); // UTC midnight of current day
+    dt.setUTCDate(dt.getUTCDate() + 1); // +1 calendar day
+    return dt.toISOString().slice(0, 10); // back to YYYY‑MM‑DD
+};
+
+export const dateAsYYYYMMDDHHmmSS = (date: Date): string =>
+    `${date.getFullYear()}${(date.getMonth() + 1).toString().padStart(2, "0")}${date
+        .getDate()
+        .toString()
+        .padStart(2, "0")}-${("" + date.getHours()).padStart(2, "0")}${("" + date.getMinutes()).padStart(2, "0")}${(
+        "" + date.getSeconds()
+    ).padStart(2, "0")}`;
+
+export const timestampAsYYYYMMDD = (timestamp: number): string => dateAsYYYYMMDD(new Date(timestamp));
+export const timestampAsUTCYYYYMMDD = (timestamp: number): string => dateAsUTCYYYYMMDD(new Date(timestamp));
+export const timestampAsYYYYMMDDHHmmSS = (timestamp: number): string => dateAsYYYYMMDDHHmmSS(new Date(timestamp));
+
+export const nowAsYYYYMMDD = (): string => timestampAsYYYYMMDD(Date.now());
+export const nowAsYYYYMMDDHHmmSS = (): string => timestampAsYYYYMMDDHHmmSS(Date.now());
+
+export const sluggize = (name: string, replaceChar = "_"): string => {
+    replaceChar ||= "_";
+    return name
+        .trim()
+        .replace(new RegExp(`[^A-Z\\d${replaceChar}]+`, "gi"), replaceChar)
+        .replace(/[\s_-]+/g, replaceChar)
+        .replace(new RegExp(`[${replaceChar}]+`, "gi"), replaceChar)
+        .replace(new RegExp(`^[${replaceChar}]+`, "gi"), "")
+        .replace(new RegExp(`[${replaceChar}]+$`, "gi"), "")
+        .toLowerCase();
+};
+
+export const hyphenate = (name: string): string => sluggize(name, "-");
+
+const generateRandomValues = (count: number): Uint8Array => {
+    if (globalThis && globalThis.crypto && globalThis.crypto.getRandomValues) {
+        return globalThis.crypto.getRandomValues(new Uint8Array(count));
+    } else {
+        const arr = new Uint8Array(count);
+        for (let i = 0; i < count; i++) {
+            arr[i] = (Math.random() * 256) | 0;
+        }
+        return arr;
+    }
+};
+
+export const uuidv4 = (squeezed?: boolean): string => {
+    const arr = generateRandomValues(16);
+
+    // Per 4.4, set bits for version and clock_seq_hi_and_reserved
+    arr[6] = (arr[6] & 0x0f) | 0x40;
+    arr[8] = (arr[8] & 0x3f) | 0x80;
+
+    // Join it all together
+    const pad = (n: string) => (n.length < 2 ? "0" + n : n);
+    const uuid = Array.from(arr)
+        .map((b) => pad(b.toString(16)))
+        .join("");
+
+    return squeezed
+        ? uuid
+        : `${uuid.slice(0, 8)}-${uuid.slice(8, 12)}-${uuid.slice(12, 16)}-${uuid.slice(16, 20)}-${uuid.slice(20)}`;
+};
+
+export const camel2kebab = (camelCaseString: string): string =>
+    camelCaseString.replace(/([a-z0-9]|(?=[A-Z]))([A-Z])/g, "$1-$2").toLowerCase();
+
+export const camel2snake = (camelCaseString: string): string =>
+    camelCaseString.replace(/([a-z0-9]|(?=[A-Z]))([A-Z])/g, "$1_$2").toLowerCase();
+
+export const kebab2camel = (kebabCaseString: string): string =>
+    kebabCaseString
+        .toLowerCase()
+        .replace(/([-_][a-z])/g, (group) => group.toUpperCase().replace("-", "").replace("_", ""));
+
+export const snake2camel = kebab2camel;
+
+export const hasUpperCase = (str: string): boolean => /[A-Z]/.test(str);
+
+export const startsWithPrefix = (s: string, prefixes: string[]): boolean =>
+    prefixes.some((prefix) => s.startsWith(prefix));
+
+export const endsWithSuffix = (s: string, suffixes: string[]): boolean => suffixes.some((suffix) => s.endsWith(suffix));
+
+export const randomDigit = (min?: number, max?: number): number => {
+    min = typeof min === "number" && min >= 0 && ((max && min <= max) || typeof max !== "number") ? min : 0;
+    max = typeof max === "number" && max <= 9 && max >= min ? max : 9;
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+};
+
+export const randomDigits = (n: number, min?: number, max?: number): string =>
+    Array.from({ length: n }, () => `${randomDigit(min, max)}`).join("");
+
+export const isOnlyDigits = (s: string): boolean => /^\d+$/.test(s);
+
+export const BASE62_CHARS = "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ";
+export const BASE62_CHARS_WITHOUT_SIMILAR_CHARS = "23456789ABCEFGHJKLMNPRSTUVWXYZ";
+export const VOWEL_CHARS = "AEOIUaeoiu";
+export const DIGIT_CHARS = "0123456789";
+export const VOWEL_AND_DIGIT_CHARS = VOWEL_CHARS + DIGIT_CHARS;
+
+// "safeToken" means safe in two ways:
+// 1. It's web-safe, using only characters than can appear un-encoded in URLs
+// 2. It's curse-word safe: after 2 consecutive letters, the next char will be a vowel or digit
+export const _randomSafeToken = (n: number, CHARS: string): string => {
+    let result = "";
+    const allowedSet = new Set(CHARS);
+    const vowelsAndDigits = [...VOWEL_AND_DIGIT_CHARS].filter((char) => allowedSet.has(char)).join("");
+
+    for (let i = 0; i < n; i++) {
+        let newChar = CHARS[Math.floor(Math.random() * CHARS.length)];
+
+        // If we have at least 2 characters and they're all alphabetic
+        if (
+            result.length >= 2 &&
+            isNaN(Number(result.charAt(result.length - 1))) &&
+            isNaN(Number(result.charAt(result.length - 2)))
+        ) {
+            // ensure next character is a vowel or a digit
+            newChar = vowelsAndDigits[Math.floor(Math.random() * vowelsAndDigits.length)];
+        }
+
+        result += newChar;
+    }
+
+    return result;
+};
+export const randomSafeToken = (n: number): string => _randomSafeToken(n, BASE62_CHARS);
+
+export const randomSuperSafeToken = (n: number): string => _randomSafeToken(n, BASE62_CHARS_WITHOUT_SIMILAR_CHARS);
+
+export const epochToHttpDate = (epoch?: number, clock?: ZillaClock): string =>
+    new Date(epoch ? epoch : clock ? clock.now() : Date.now()).toUTCString();
+
+export const sortWords = (words: string[], dict: string[]): string[] =>
+    words.sort(
+        (a: string, b: string) =>
+            dict.indexOf(a) - dict.indexOf(b) || dict.length + words.indexOf(a) - (dict.length + words.indexOf(b))
+    );
+
+export const trimSpaces = (str: string): string => str.trim().replace(/\s+/g, " ");
+
+export const trimNonalphanumeric = (str: string): string => str.replace(/[^a-zA-Z0-9]/g, "");
+
+const commonUnicodeRanges = [
+    [0x0000, 0x007f], // Basic Latin (ASCII)
+    [0x0080, 0x00ff], // Latin-1 Supplement
+    [0x0100, 0x017f], // Latin Extended-A
+    [0x0370, 0x03ff], // Greek and Coptic
+    [0x0400, 0x04ff], // Cyrillic
+    [0x0530, 0x058f], // Armenian
+    [0x0590, 0x05ff], // Hebrew
+    [0x0600, 0x06ff], // Arabic
+    [0x0900, 0x097f], // Devanagari
+    [0xac00, 0xd7af], // Hangul Syllables
+    [0x4e00, 0x9fff], // CJK Unified Ideographs
+];
+
+const createUnifiedRange = (ranges: number[][]): number[] => {
+    const unifiedRange = [];
+    for (const [start, end] of ranges) {
+        for (let i = start; i <= end; i++) {
+            unifiedRange.push(i);
+        }
+    }
+    return unifiedRange;
+};
+
+const unifiedUnicodeRange = createUnifiedRange(commonUnicodeRanges);
+
+export const getRandomCodePoint = (): number => {
+    const randomIndex = Math.floor(Math.random() * unifiedUnicodeRange.length);
+    return unifiedUnicodeRange[randomIndex];
+};
+
+export const generateRandomString = (length: number): string => {
+    return Array.from({ length }, () => String.fromCodePoint(getRandomCodePoint())).join("");
+};
+
+export const sortObj = (o: Record<string, unknown>): Record<string, unknown> =>
+    Object.keys(o)
+        .sort()
+        .reduce((acc, key) => {
+            acc[key] =
+                typeof o[key] === "object" && o[key] !== null && !Array.isArray(o[key])
+                    ? sortObj(o[key] as Record<string, unknown>)
+                    : o[key];
+            return acc;
+        }, {} as Record<string, unknown>);
+
+export const sortedStringify = (obj: Record<string, unknown>): string => JSON.stringify(sortObj(obj));
+
+export const jsonHeader = () => ({ "Content-Type": "application/json" });
+
+export const ANSI = {
+    RESET: "\x1b[0m",
+    BOLD: "\x1b[1m",
+    DIM: "\x1b[2m",
+    UNDERLINE: "\x1b[4m",
+    BLINK: "\x1b[5m",
+    INVERSE: "\x1b[7m",
+    HIDDEN: "\x1b[8m",
+
+    // Foreground Colors
+    BLACK: "\x1b[30m",
+    RED: "\x1b[31m",
+    GREEN: "\x1b[32m",
+    YELLOW: "\x1b[33m",
+    BLUE: "\x1b[34m",
+    MAGENTA: "\x1b[35m",
+    CYAN: "\x1b[36m",
+    WHITE: "\x1b[37m",
+
+    // Bright Foreground Colors
+    BRIGHT_BLACK: "\x1b[90m",
+    BRIGHT_RED: "\x1b[91m",
+    BRIGHT_GREEN: "\x1b[92m",
+    BRIGHT_YELLOW: "\x1b[93m",
+    BRIGHT_BLUE: "\x1b[94m",
+    BRIGHT_MAGENTA: "\x1b[95m",
+    BRIGHT_CYAN: "\x1b[96m",
+    BRIGHT_WHITE: "\x1b[97m",
+};
+
+export const CSS = {
+    RESET: "color: inherit;",
+    BOLD: "font-weight: bold;",
+    DIM: "opacity: 0.7;",
+    UNDERLINE: "text-decoration: underline;",
+    // for BLINK to work, add the CSS below to some global CSS file that the browser will load:
+    // @keyframes blink { 50% { opacity: 0; } }
+    // If the CSS isn't defined, BLINK text will still appear, it just won't blink
+    BLINK: "animation: blink 1s step-start infinite;",
+    INVERSE: "filter: invert(100%);",
+    HIDDEN: "visibility: hidden;",
+
+    // Foreground Colors
+    BLACK: "color: black;",
+    RED: "color: red;",
+    GREEN: "color: green;",
+    YELLOW: "color: goldenrod;",
+    BLUE: "color: blue;",
+    MAGENTA: "color: purple;",
+    CYAN: "color: cyan;",
+    WHITE: "color: white;",
+
+    // Bright Foreground Colors
+    BRIGHT_BLACK: "color: gray;",
+    BRIGHT_RED: "color: lightcoral;",
+    BRIGHT_GREEN: "color: lightgreen;",
+    BRIGHT_YELLOW: "color: yellow;",
+    BRIGHT_BLUE: "color: lightskyblue;",
+    BRIGHT_MAGENTA: "color: violet;",
+    BRIGHT_CYAN: "color: lightcyan;",
+    BRIGHT_WHITE: "color: white;",
+};
+
+export const REGEX_ARRAY_OF_STRINGS = /^\[\s*(?:"[^"]*"\s*(?:,\s*"[^"]*"\s*)*)?]$/;
+export const REGEX_ARRAY_OF_BOOLEANS = /^\[\s*(?:true|false)(\s*,\s*(?:true|false))*\s*]$/;
+export const REGEX_ARRAY_OF_INTEGERS = /^\[\s*-?\d+(\s*,\s*-?\d+)*\s*]$/;
+export const REGEX_ARRAY_OF_FLOATS = /^\[\s*-?\d+(\.\d+)?([eE][-+]?\d+)?(\s*,\s*-?\d+(\.\d+)?([eE][-+]?\d+)?)*\s*]$/;
+
+export const safeStringify = (obj: unknown, logger?: GenericLogger): string => {
+    const seen: WeakSet<object> = new WeakSet();
+    return JSON.stringify(obj, (_key, val) => {
+        if (typeof val === "object" && val !== null) {
+            if (seen.has(val)) {
+                if (logger && logger.isDebugEnabled()) {
+                    logger.debug(
+                        `safeStringify: detected circular reference in obj: ${obj}${
+                            obj?.constructor?.name ? ` [constructor=${obj.constructor.name}]` : ""
+                        }`
+                    );
+                }
+                return "[Circular]";
+            }
+            seen.add(val);
+        }
+        return val;
+    });
+};
+
+export const splitter = new GraphemeSplitter();
+
+export const countVisibleChars = (data: Uint8Array | string): number =>
+    splitter.countGraphemes(typeof data === "string" ? data : new TextDecoder("utf-8").decode(data));

package/src/subst.ts

@@ -0,0 +1,41 @@
+export type StringXformFunction = (args?: string[]) => string;
+
+export type StringXformContext = Record<string, string | StringXformFunction | undefined | null>;
+
+export const ERR_UNKNOWN_SUBST_CONTEXT_VAR = "Unknown context variable";
+
+export const substContext = (obj: unknown, context: StringXformContext, opts?: { strict: boolean }): unknown => {
+    const transformString = (str: string): string => {
+        return str.replace(/{{(.*?)}}/g, (_, key) => {
+            const parts: string[] = key
+                .trim()
+                .split(/\s+/)
+                .filter((s: string) => s.length > 0)
+                .map((s: string) => s.trim());
+            const k = parts[0];
+            const args = parts.length > 1 ? parts.slice(1) : [];
+
+            const subst = context[k];
+
+            if (typeof subst === "string") return subst;
+            if (typeof subst === "function") {
+                return subst(args);
+            }
+            if (!opts || opts?.strict !== false) throw new Error(`${ERR_UNKNOWN_SUBST_CONTEXT_VAR} var=${k}`);
+            return `??${k}`;
+        });
+    };
+
+    const transform = (item: unknown): unknown => {
+        if (typeof item === "string") {
+            return transformString(item);
+        } else if (Array.isArray(item)) {
+            return item.map(transform);
+        } else if (item && typeof item === "object") {
+            return Object.fromEntries(Object.entries(item).map(([k, v]) => [k, transform(v)]));
+        }
+        return item;
+    };
+
+    return transform(obj);
+};

package/src/time.ts

@@ -0,0 +1,105 @@
+import { uuidv4 } from "./string.js";
+import { GenericLogger } from "./logger.js";
+
+export type ZillaNowFunc = () => number;
+
+const DEFAULT_NOW_FUNC: ZillaNowFunc = () => Date.now();
+
+export type ZillaClock = {
+    now: ZillaNowFunc;
+};
+
+export const DEFAULT_CLOCK: ZillaClock = {
+    now: DEFAULT_NOW_FUNC,
+};
+
+export type ZillaClockSource = () => ZillaClock;
+
+export const DEFAULT_CLOCK_SOURCE: ZillaClockSource = () => DEFAULT_CLOCK;
+
+export class MockClock {
+    private time: number;
+    private start: number;
+    private logger?: GenericLogger;
+    private name: string;
+    constructor(startTime?: number, logger?: GenericLogger, name?: string) {
+        this.start = Date.now();
+        this.time = typeof startTime === "number" && startTime > 0 ? startTime : Date.now();
+        this.logger = logger;
+        this.name = name ? name : `MockClock-${uuidv4()}`;
+    }
+    now(): number {
+        if (this.logger && this.logger.isTraceEnabled()) {
+            this.logger.trace(`MockClock ID=${this.name} RETURNING now=${this.time}`);
+        }
+        return this.time + (Date.now() - this.start);
+    }
+    setTime(time: number) {
+        if (this.logger && this.logger.isTraceEnabled()) {
+            this.logger.trace(`MockClock ID=${this.name} SET-TIME now=${this.time} setting-to=${time}`);
+        }
+        this.time = time;
+        if (this.logger && this.logger.isTraceEnabled()) {
+            this.logger.trace(`MockClock ID=${this.name} SET-TIME now=${this.time}`);
+        }
+    }
+    advance(timeDelta: number): void {
+        if (this.logger && this.logger.isTraceEnabled()) {
+            this.logger.trace(`MockClock ID=${this.name} ADVANCING now=${this.time} timeDelta=${timeDelta}`);
+        }
+        this.time += timeDelta;
+        if (this.logger && this.logger.isTraceEnabled()) {
+            this.logger.trace(`MockClock ID=${this.name} ADVANCED now=${this.time}`);
+        }
+    }
+}
+export const mockClock = (startTime: number = 0): ZillaClock => new MockClock(startTime);
+
+// adapted from https://stackoverflow.com/a/39914235
+export const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+export const DEFAULT_NAP_CHECK = 1000;
+
+const _nap =
+    (resolve: (v?: unknown) => void, clock: ZillaClock, alarm: NapAlarm, ms: number, check: number) => async () => {
+        try {
+            alarm.wake = false;
+            const start = clock.now();
+            while (!alarm.wake && clock.now() - start < ms) {
+                await sleep(check);
+            }
+        } finally {
+            resolve();
+        }
+    };
+
+export type NapAlarm = {
+    wake?: boolean;
+};
+
+export const nap = (clock: ZillaClock, alarm: NapAlarm, ms: number, check?: number) =>
+    new Promise((r) => _nap(r, clock, alarm, ms, check || DEFAULT_NAP_CHECK)());
+
+export const parseSimpleTime = (t: string): number => {
+    const match: RegExpExecArray | null = /^(\d+(\.\d+)?)([smhd])?$/.exec(t);
+    if (!match) throw new Error(`Invalid time format: ${t}`);
+    const value: number = Number(match[1]);
+    const unit: string | undefined = match[3];
+    switch (unit) {
+        case "s":
+            return value * 1000;
+        case "m":
+            return value * 60 * 1000;
+        case "h":
+            return value * 3600 * 1000;
+        case "d":
+            return value * 24 * 3600 * 1000;
+        default:
+            return value;
+    }
+};
+
+export const delay = async (duration?: number | string) => {
+    if (!duration) return;
+    await sleep(typeof duration === "number" ? duration : parseSimpleTime(duration));
+};

package/src/url.ts

@@ -0,0 +1,92 @@
+export type CanonicalizedUrl = {
+    original: string;
+    normalized: string;
+    redirectChain: string[];
+    landing: string;
+    canonical: string;
+};
+
+const tracking: Set<string> = new Set([
+    "ref",
+    "ref_src",
+    "gclsrc",
+    "fbp",
+    "fbc",
+    "irclickid",
+    "hsCtaTracking",
+    "pi_opt_in",
+    "visitor_id",
+    "mc_cid",
+    "mc_eid",
+]);
+
+const trackingRegexes: RegExp[] = [
+    /^[a-z_]+clid$/,
+    /^[a-z_]+clkid$/,
+    /^[a-z_]+click_?id$/,
+    /^utm_[a-z_]+$/,
+    /^__utm(?:a|b|c|z|v)$/,
+    /^_hs(?:enc|mi)$/,
+    /^mkt_[a-z_]+$/,
+    /^pk_[a-z]+$/,
+];
+
+export const normalizeUrl = (input: string): string => {
+    try {
+        return new URL(input).toString();
+    } catch {
+        return input;
+    }
+};
+
+export const canonicalizeUrl = async (url: string): Promise<CanonicalizedUrl> => {
+    const original: string = url.trim();
+
+    const u: URL = new URL(original);
+    u.protocol = u.protocol.toLowerCase();
+    u.hostname = u.hostname.toLowerCase();
+    if ((u.protocol === "http:" && u.port === "80") || (u.protocol === "https:" && u.port === "443")) u.port = "";
+    u.pathname = u.pathname.replace(/\/{2,}/g, "/").replace(/%7E/gi, "~");
+
+    const kept: [string, string][] = Array.from(u.searchParams.entries()).filter(
+        ([k]) => !tracking.has(k.toLowerCase()) && !trackingRegexes.find((r) => r.test(k.toLowerCase()))
+    );
+    kept.sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    u.search = kept.length ? `?${new URLSearchParams(kept).toString()}` : "";
+
+    const normalized: string = u.toString();
+
+    const redirectChain: string[] = [];
+    const maxRedirects: number = 5;
+    let landing: string = normalized;
+    try {
+        let cur: string = normalized;
+        for (let n: number = 0; n < maxRedirects; n += 1) {
+            const r: Response = await fetch(cur, { method: "HEAD", redirect: "manual" });
+            const loc: string | null = r.status >= 300 && r.status < 400 ? r.headers.get("location") : null;
+            if (!loc) break;
+            cur = new URL(loc, cur).toString();
+            redirectChain.push(cur);
+        }
+        if (redirectChain.length) landing = redirectChain[redirectChain.length - 1];
+    } catch {
+        landing = normalized;
+    }
+
+    let canonical: string = landing;
+    try {
+        const res: Response = await fetch(landing, { method: "GET", redirect: "follow" });
+        if (res.headers.get("content-type")?.includes("text/html")) {
+            const html: string = await res.text();
+            const found: string | undefined =
+                html.match(/<link[^>]*rel=["']canonical["'][^>]*href=["']([^"']+)["']/i)?.[1] ??
+                html.match(/<meta[^>]*property=["']og:url["'][^>]*content=["']([^"']+)["']/i)?.[1] ??
+                html.match(/<meta[^>]*property=["']twitter:url["'][^>]*content=["']([^"']+)["']/i)?.[1];
+            if (found) canonical = new URL(found, landing).toString();
+        }
+    } catch {
+        /* ignore */
+    }
+
+    return { original, normalized, redirectChain, landing, canonical };
+};