@nshiab/simple-data-analysis 5.19.8

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/dateToRCStyle.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = dateToRCStyle;
+/**
+ * Formats a date string into RC (Radio-Canada) style.
+ * @param string The date string to format.
+ * @param abrev If true, uses abbreviations for months and days.
+ * @param threeLetterMonth If true, uses three-letter abbreviations for months.
+ * @returns The formatted date string.
+ */
+function dateToRCStyle(string, abrev, threeLetterMonth) {
+    string = string
+        .replace(" h 00", " h")
+        .replace("NDT", "HAT")
+        .replace("NST", "HNT")
+        .replace("ADT", "HAA")
+        .replace("AST", "HNA")
+        .replace("CDT", "HAC")
+        .replace("CST", "HNC")
+        .replace("MDT", "HAR")
+        .replace("MST", "HNR")
+        .replace("PDT", "HAP")
+        .replace("PST", "HNP")
+        .replace("EDT", "HAE")
+        .replace("EST", "HNE")
+        .trim();
+    if (threeLetterMonth) {
+        string = string
+            .replace("January", "janv.")
+            .replace("February", "fév.")
+            .replace("March", "mar.")
+            .replace("April", "avr.")
+            .replace("May", "mai") // No dot for mai
+            .replace("June", "jui.")
+            .replace("July", "juil.")
+            .replace("August", "aoû.")
+            .replace("September", "sep.")
+            .replace("October", "oct.")
+            .replace("November", "nov.")
+            .replace("December", "déc.");
+    }
+    if (abrev) {
+        return string
+            .replace("January", "janv.")
+            .replace("February", "fév.")
+            .replace("March", "mars")
+            .replace("April", "avr.")
+            .replace("May", "mai")
+            .replace("June", "juin")
+            .replace("July", "juill.")
+            .replace("August", "août")
+            .replace("September", "sept.")
+            .replace("October", "oct.")
+            .replace("November", "nov.")
+            .replace("December", "déc.")
+            .replace("Monday", "Lun.")
+            .replace("Tuesday", "Mar.")
+            .replace("Wednesday", "Mer.")
+            .replace("Thursday", "Jeu.")
+            .replace("Friday", "Ven.")
+            .replace("Saturday", "Sam.")
+            .replace("Sunday", "Dim.");
+    }
+    else {
+        return string
+            .replace("January", "janvier")
+            .replace("February", "février")
+            .replace("March", "mars")
+            .replace("April", "avril")
+            .replace("May", "mai")
+            .replace("June", "juin")
+            .replace("July", "juillet")
+            .replace("August", "août")
+            .replace("September", "septembre")
+            .replace("October", "octobre")
+            .replace("November", "novembre")
+            .replace("December", "décembre")
+            .replace("Monday", "Lundi")
+            .replace("Tuesday", "Mardi")
+            .replace("Wednesday", "Mercredi")
+            .replace("Thursday", "Jeudi")
+            .replace("Friday", "Vendredi")
+            .replace("Saturday", "Samedi")
+            .replace("Sunday", "Dimanche");
+    }
+}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/isValidDate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Checks if a given value is a valid Date object.
+ * @param date The value to check.
+ * @returns True if the value is a valid Date object, false otherwise.
+ */
+export default function isValid(date: unknown): boolean;
+//# sourceMappingURL=isValidDate.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/isValidDate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"isValidDate.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/isValidDate.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,OAAO,CAAC,IAAI,EAAE,OAAO,WAE5C"}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/isValidDate.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = isValid;
+/**
+ * Checks if a given value is a valid Date object.
+ * @param date The value to check.
+ * @returns True if the value is a valid Date object, false otherwise.
+ */
+function isValid(date) {
+    return date instanceof Date && !isNaN(date);
+}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/transformPositionToCbcStyle.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Transforms a number position to CBC-style string (e.g., 1 -> 'first', 2 -> 'second', 11 -> '11th').
+ * @param position The number to transform.
+ * @returns The CBC-style string representation of the position.
+ */
+export declare function transformPositionToCbcStyle(position: number): string;
+//# sourceMappingURL=transformPositionToCbcStyle.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/transformPositionToCbcStyle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformPositionToCbcStyle.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/transformPositionToCbcStyle.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,2BAA2B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CA8BpE"}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/transformPositionToCbcStyle.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformPositionToCbcStyle = transformPositionToCbcStyle;
+// Utility to transform a number position to CBC-style string (e.g., 1 -> 'first', 2 -> 'second', 11 -> '11th')
+// Based on https://www.cbc.ca/news/canada/new-brunswick/fredericton-councillors-vote-to-increase-their-salaries-1.6944020
+/**
+ * Transforms a number position to CBC-style string (e.g., 1 -> 'first', 2 -> 'second', 11 -> '11th').
+ * @param position The number to transform.
+ * @returns The CBC-style string representation of the position.
+ */
+function transformPositionToCbcStyle(position) {
+    if (position < 1 || !Number.isInteger(position)) {
+        throw new Error("Input must be a positive integer.");
+    }
+    const singleDigitOrdinals = {
+        1: "first",
+        2: "second",
+        3: "third",
+        4: "fourth",
+        5: "fifth",
+        6: "sixth",
+        7: "seventh",
+        8: "eighth",
+        9: "ninth",
+    };
+    if (position >= 1 && position <= 9) {
+        return singleDigitOrdinals[position];
+    }
+    else {
+        let suffix = "th";
+        if (position % 10 === 1 && position % 100 !== 11) {
+            suffix = "st";
+        }
+        else if (position % 10 === 2 && position % 100 !== 12) {
+            suffix = "nd";
+        }
+        else if (position % 10 === 3 && position % 100 !== 13) {
+            suffix = "rd";
+        }
+        return `${position}${suffix}`;
+    }
+}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/transformPositionToRcStyle.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Returns the French ordinal for a given positive integer position.
+ * @param position The number to transform.
+ * @returns The French ordinal string representation of the position.
+ */
+export declare function transformPositionToRcStyle(position: number): string;
+//# sourceMappingURL=transformPositionToRcStyle.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/transformPositionToRcStyle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transformPositionToRcStyle.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/transformPositionToRcStyle.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAoBnE"}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/transformPositionToRcStyle.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.transformPositionToRcStyle = transformPositionToRcStyle;
+// Returns the French ordinal for a given positive integer position.
+// Returns the French ordinal for a given positive integer position.
+/**
+ * Returns the French ordinal for a given positive integer position.
+ * @param position The number to transform.
+ * @returns The French ordinal string representation of the position.
+ */
+function transformPositionToRcStyle(position) {
+    if (!Number.isInteger(position) || position < 1) {
+        throw new Error("Input must be a positive integer.");
+    }
+    const singleDigitOrdinals = {
+        1: "premier",
+        2: "deuxième",
+        3: "troisième",
+        4: "quatrième",
+        5: "cinquième",
+        6: "sixième",
+        7: "septième",
+        8: "huitième",
+        9: "neuvième",
+    };
+    if (position >= 1 && position <= 9) {
+        return singleDigitOrdinals[position];
+    }
+    else {
+        return `${position}e`;
+    }
+}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/wrapString.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Wraps a string to a specified maximum width, attempting to break at word boundaries when possible.
+ * If a single word exceeds the maximum width, it will be broken at the character boundary.
+ * This function is primarily used for preparing text to be displayed in console tables.
+ *
+ * @param str - The string to wrap.
+ * @param maxWidth - The maximum width of each line.
+ * @param wordWrap - If true, attempts to break at word boundaries. If false, breaks at character boundaries. Defaults to true.
+ * @returns The wrapped string with newline characters inserted at appropriate positions.
+ *
+ * @example
+ * ```typescript
+ * const text = "This is a very long sentence that needs to be wrapped";
+ * const wrapped = wrapString(text, 20);
+ * console.log(wrapped);
+ * // Output:
+ * // This is a very long
+ * // sentence that needs
+ * // to be wrapped
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Character-based wrapping (no word boundaries)
+ * const text = "Thisisaverylongword";
+ * const wrapped = wrapString(text, 10, false);
+ * // Output: Thisisaver / ylongword
+ * ```
+ */
+export default function wrapString(str: string, maxWidth: number, wordWrap?: boolean): string;
+//# sourceMappingURL=wrapString.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/wrapString.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapString.d.ts","sourceRoot":"","sources":["../../../../../../../../../src/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/wrapString.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,CAAC,OAAO,UAAU,UAAU,CAChC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,QAAQ,UAAO,GACd,MAAM,CAqDR"}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/helpers/wrapString.js

@@ -0,0 +1,82 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = wrapString;
+/**
+ * Wraps a string to a specified maximum width, attempting to break at word boundaries when possible.
+ * If a single word exceeds the maximum width, it will be broken at the character boundary.
+ * This function is primarily used for preparing text to be displayed in console tables.
+ *
+ * @param str - The string to wrap.
+ * @param maxWidth - The maximum width of each line.
+ * @param wordWrap - If true, attempts to break at word boundaries. If false, breaks at character boundaries. Defaults to true.
+ * @returns The wrapped string with newline characters inserted at appropriate positions.
+ *
+ * @example
+ * ```typescript
+ * const text = "This is a very long sentence that needs to be wrapped";
+ * const wrapped = wrapString(text, 20);
+ * console.log(wrapped);
+ * // Output:
+ * // This is a very long
+ * // sentence that needs
+ * // to be wrapped
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Character-based wrapping (no word boundaries)
+ * const text = "Thisisaverylongword";
+ * const wrapped = wrapString(text, 10, false);
+ * // Output: Thisisaver / ylongword
+ * ```
+ */
+function wrapString(str, maxWidth, wordWrap = true) {
+    if (str.length <= maxWidth) {
+        return str;
+    }
+    if (!wordWrap) {
+        // Simple character-based wrapping
+        const lines = [];
+        for (let i = 0; i < str.length; i += maxWidth) {
+            lines.push(str.slice(i, i + maxWidth));
+        }
+        return lines.join("\n");
+    }
+    // Word-aware wrapping
+    const lines = [];
+    let currentLine = "";
+    const words = str.split(/(\s+)/); // Split but keep whitespace
+    for (const word of words) {
+        // If adding this word would exceed maxWidth
+        if (currentLine.length + word.length > maxWidth) {
+            // If current line is not empty, save it
+            if (currentLine.length > 0) {
+                lines.push(currentLine.trimEnd());
+                currentLine = "";
+            }
+            // If the word itself is longer than maxWidth, break it
+            if (word.length > maxWidth) {
+                for (let i = 0; i < word.length; i += maxWidth) {
+                    const chunk = word.slice(i, i + maxWidth);
+                    if (i + maxWidth < word.length) {
+                        lines.push(chunk);
+                    }
+                    else {
+                        currentLine = chunk;
+                    }
+                }
+            }
+            else {
+                currentLine = word;
+            }
+        }
+        else {
+            currentLine += word;
+        }
+    }
+    // Add any remaining text
+    if (currentLine.length > 0) {
+        lines.push(currentLine.trimEnd());
+    }
+    return lines.join("\n");
+}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/normalizeString.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Normalizes a string by converting it to lowercase, stripping accents, punctuation (optional), and trimming whitespace.
+ *
+ * @param string The string to be normalized.
+ * @param options An optional object with options.
+ * @param options.stripPunctuation If true, punctuation and underscores will be stripped. Defaults to true.
+ *
+ * @returns A new string with characters in lowercase, without accents, without punctuation (if specified), with single spaces between words, and without leading or trailing whitespace.
+ *
+ * @example
+ * ```ts
+ * // Basic usage (strips punctuation by default)
+ * const normalized = normalizeString("Évènement!  de  test");
+ * console.log(normalized); // "evenement de test"
+ * ```
+ * @example
+ * ```ts
+ * // Keeping punctuation
+ * const normalized = normalizeString("Évènement!", { stripPunctuation: false });
+ * console.log(normalized); // "evenement!"
+ * ```
+ * @example
+ * ```ts
+ * // With accents, punctuation, and uppercase
+ * const normalized = normalizeString("¡Niño!");
+ * console.log(normalized); // "nino"
+ * ```
+ * @example
+ * ```ts
+ * // Handling multiple types of whitespace and symbols
+ * const normalized = normalizeString("Hello,  World!\t100%");
+ * console.log(normalized); // "hello world 100"
+ * ```
+ * @example
+ * ```ts
+ * // Stripping hyphens and underscores
+ * const normalized = normalizeString("multi-word_example");
+ * console.log(normalized); // "multiwordexample"
+ * ```
+ * @example
+ * ```ts
+ * // Handling emails (strips @ and .)
+ * const normalized = normalizeString("email@example.com");
+ * console.log(normalized); // "emailexamplecom"
+ * ```
+ * @category Formatting
+ */
+export default function normalizeString(string: string, options?: {
+    stripPunctuation?: boolean;
+}): string;
+//# sourceMappingURL=normalizeString.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/normalizeString.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalizeString.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/normalizeString.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8CG;AACH,MAAM,CAAC,OAAO,UAAU,eAAe,CACrC,MAAM,EAAE,MAAM,EACd,OAAO,GAAE;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAO,GAC3C,MAAM,CAeR"}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/normalizeString.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = normalizeString;
+/**
+ * Normalizes a string by converting it to lowercase, stripping accents, punctuation (optional), and trimming whitespace.
+ *
+ * @param string The string to be normalized.
+ * @param options An optional object with options.
+ * @param options.stripPunctuation If true, punctuation and underscores will be stripped. Defaults to true.
+ *
+ * @returns A new string with characters in lowercase, without accents, without punctuation (if specified), with single spaces between words, and without leading or trailing whitespace.
+ *
+ * @example
+ * ```ts
+ * // Basic usage (strips punctuation by default)
+ * const normalized = normalizeString("Évènement!  de  test");
+ * console.log(normalized); // "evenement de test"
+ * ```
+ * @example
+ * ```ts
+ * // Keeping punctuation
+ * const normalized = normalizeString("Évènement!", { stripPunctuation: false });
+ * console.log(normalized); // "evenement!"
+ * ```
+ * @example
+ * ```ts
+ * // With accents, punctuation, and uppercase
+ * const normalized = normalizeString("¡Niño!");
+ * console.log(normalized); // "nino"
+ * ```
+ * @example
+ * ```ts
+ * // Handling multiple types of whitespace and symbols
+ * const normalized = normalizeString("Hello,  World!\t100%");
+ * console.log(normalized); // "hello world 100"
+ * ```
+ * @example
+ * ```ts
+ * // Stripping hyphens and underscores
+ * const normalized = normalizeString("multi-word_example");
+ * console.log(normalized); // "multiwordexample"
+ * ```
+ * @example
+ * ```ts
+ * // Handling emails (strips @ and .)
+ * const normalized = normalizeString("email@example.com");
+ * console.log(normalized); // "emailexamplecom"
+ * ```
+ * @category Formatting
+ */
+function normalizeString(string, options = {}) {
+    const { stripPunctuation = true } = options;
+    let normalized = string
+        .normalize("NFD")
+        .replace(/[\u0300-\u036f]/g, "");
+    if (stripPunctuation) {
+        normalized = normalized.replace(/[^\w\s]|_/g, "");
+    }
+    return normalized
+        .replace(/\s+/g, " ")
+        .toLowerCase()
+        .trim();
+}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/prettyDuration.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Formats a duration into a human-readable string, breaking it down into years, months, days, hours, minutes, seconds, and milliseconds. This function is useful for displaying elapsed time in a user-friendly format, such as for performance logging, task completion times, or general time tracking.
+ *
+ * The function can calculate the duration from a given start time to the current time, or between a specified start and end time. It provides options for logging the output directly to the console and adding custom prefixes or suffixes to the formatted string. Note that for simplicity, months are approximated as 30 days and years as 365 days.
+ *
+ * @param start - The starting point of the duration. This can be a `Date` object or a Unix timestamp (number of milliseconds since epoch).
+ * @param options - Optional settings to customize the duration formatting and output.
+ *   @param options.log - If `true`, the formatted duration string will be logged to the console. Defaults to `false`.
+ *   @param options.end - The ending point of the duration. This can be a `Date` object or a Unix timestamp. If omitted, the current time (`Date.now()`) will be used as the end point.
+ *   @param options.prefix - A string to prepend to the formatted duration string (e.g., "Elapsed time: ").
+ *   @param options.suffix - A string to append to the formatted duration string (e.g., " (Task completed)").
+ * @returns A human-readable string representing the duration.
+ *
+ * @example
+ * ```ts
+ * // A starting Date somewhere in your code.
+ * const startDate = new Date(); // or Date.now()
+ *
+ * // When you want to know the elapsed duration, pass the start date.
+ * const duration = prettyDuration(startDate);
+ * console.log(duration); // Returns something like "22 days, 6 h, 3 min, 15 sec, 3 ms"
+ * ```
+ * @example
+ * ```ts
+ * // If you want to console.log it directly, set the `log` option to `true`.
+ * // This will print the duration to the console and also return the string.
+ * const startDateForLog = new Date();
+ * // ... some operations ...
+ * prettyDuration(startDateForLog, { log: true });
+ * ```
+ * @example
+ * ```ts
+ * // You can also use a prefix and/or suffix for the output string.
+ * const startDateWithPrefixSuffix = new Date();
+ * // ... some operations ...
+ * prettyDuration(startDateWithPrefixSuffix, { log: true, prefix: "Elapsed time: ", suffix: " (Main function)" });
+ * // Returns and logs something like "Total duration: 3 min, 15 sec, 3 ms (Main function)"
+ * ```
+ * @example
+ * ```ts
+ * // If you want to format the duration between two specific dates, use the `end` option.
+ * const start = new Date("2024-01-01T17:00:00");
+ * const end = new Date("2024-01-23T23:03:15");
+ * const specificDuration = prettyDuration(start, { end });
+ * console.log(specificDuration); // Returns "22 days, 6 h, 3 min, 15 sec, 0 ms"
+ * ```
+ * @category Formatting
+ */
+export default function prettyDuration(start: Date | number, options?: {
+    log?: boolean;
+    end?: Date | number;
+    prefix?: string;
+    suffix?: string;
+}): string;
+//# sourceMappingURL=prettyDuration.d.ts.map

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/prettyDuration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prettyDuration.d.ts","sourceRoot":"","sources":["../../../../../../../../src/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/prettyDuration.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,MAAM,CAAC,OAAO,UAAU,cAAc,CACpC,KAAK,EAAE,IAAI,GAAG,MAAM,EACpB,OAAO,GAAE;IACP,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,GAAG,CAAC,EAAE,IAAI,GAAG,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACZ,GACL,MAAM,CAuGR"}

package/script/deps/jsr.io/@nshiab/journalism-format/1.1.5/src/format/prettyDuration.js

@@ -0,0 +1,148 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = prettyDuration;
+/**
+ * Formats a duration into a human-readable string, breaking it down into years, months, days, hours, minutes, seconds, and milliseconds. This function is useful for displaying elapsed time in a user-friendly format, such as for performance logging, task completion times, or general time tracking.
+ *
+ * The function can calculate the duration from a given start time to the current time, or between a specified start and end time. It provides options for logging the output directly to the console and adding custom prefixes or suffixes to the formatted string. Note that for simplicity, months are approximated as 30 days and years as 365 days.
+ *
+ * @param start - The starting point of the duration. This can be a `Date` object or a Unix timestamp (number of milliseconds since epoch).
+ * @param options - Optional settings to customize the duration formatting and output.
+ *   @param options.log - If `true`, the formatted duration string will be logged to the console. Defaults to `false`.
+ *   @param options.end - The ending point of the duration. This can be a `Date` object or a Unix timestamp. If omitted, the current time (`Date.now()`) will be used as the end point.
+ *   @param options.prefix - A string to prepend to the formatted duration string (e.g., "Elapsed time: ").
+ *   @param options.suffix - A string to append to the formatted duration string (e.g., " (Task completed)").
+ * @returns A human-readable string representing the duration.
+ *
+ * @example
+ * ```ts
+ * // A starting Date somewhere in your code.
+ * const startDate = new Date(); // or Date.now()
+ *
+ * // When you want to know the elapsed duration, pass the start date.
+ * const duration = prettyDuration(startDate);
+ * console.log(duration); // Returns something like "22 days, 6 h, 3 min, 15 sec, 3 ms"
+ * ```
+ * @example
+ * ```ts
+ * // If you want to console.log it directly, set the `log` option to `true`.
+ * // This will print the duration to the console and also return the string.
+ * const startDateForLog = new Date();
+ * // ... some operations ...
+ * prettyDuration(startDateForLog, { log: true });
+ * ```
+ * @example
+ * ```ts
+ * // You can also use a prefix and/or suffix for the output string.
+ * const startDateWithPrefixSuffix = new Date();
+ * // ... some operations ...
+ * prettyDuration(startDateWithPrefixSuffix, { log: true, prefix: "Elapsed time: ", suffix: " (Main function)" });
+ * // Returns and logs something like "Total duration: 3 min, 15 sec, 3 ms (Main function)"
+ * ```
+ * @example
+ * ```ts
+ * // If you want to format the duration between two specific dates, use the `end` option.
+ * const start = new Date("2024-01-01T17:00:00");
+ * const end = new Date("2024-01-23T23:03:15");
+ * const specificDuration = prettyDuration(start, { end });
+ * console.log(specificDuration); // Returns "22 days, 6 h, 3 min, 15 sec, 0 ms"
+ * ```
+ * @category Formatting
+ */
+function prettyDuration(start, options = {}) {
+    if (start instanceof Date) {
+        start = start.getTime();
+    }
+    let end;
+    if (options.end instanceof Date) {
+        end = options.end.getTime();
+    }
+    else if (typeof options.end === "number") {
+        end = options.end;
+    }
+    else {
+        end = Date.now();
+    }
+    const differenceInMs = end - start;
+    let prettyDuration = "";
+    if (differenceInMs < 1000) {
+        // Less than a second
+        prettyDuration = `${differenceInMs} ms`;
+    }
+    else if (differenceInMs < 60_000) {
+        // Less than a minute
+        const sec = Math.floor(differenceInMs / 1000);
+        const ms = differenceInMs % 1000;
+        prettyDuration = `${sec} sec, ${ms} ms`;
+    }
+    else if (differenceInMs < 3_600_000) {
+        // Less than an hour
+        const min = Math.floor(differenceInMs / 60_000);
+        const remainingMs = differenceInMs % 60_000;
+        const sec = Math.floor(remainingMs / 1000);
+        const ms = remainingMs % 1000;
+        prettyDuration = `${min} min, ${sec} sec, ${ms} ms`;
+    }
+    else if (differenceInMs < 86_400_000) {
+        // Less than a day
+        const hours = Math.floor(differenceInMs / 3_600_000);
+        const remainingMsAfterHours = differenceInMs % 3_600_000;
+        const min = Math.floor(remainingMsAfterHours / 60_000);
+        const remainingMsAfterMinutes = remainingMsAfterHours % 60_000;
+        const sec = Math.floor(remainingMsAfterMinutes / 1000);
+        const ms = remainingMsAfterMinutes % 1000;
+        prettyDuration = `${hours} h, ${min} min, ${sec} sec, ${ms} ms`;
+    }
+    else if (differenceInMs < 2_592_000_000) {
+        // Less than a month
+        const days = Math.floor(differenceInMs / 86_400_000);
+        const remainingMsAfterDays = differenceInMs % 86_400_000;
+        const hours = Math.floor(remainingMsAfterDays / 3_600_000);
+        const remainingMsAfterHours = remainingMsAfterDays % 3_600_000;
+        const min = Math.floor(remainingMsAfterHours / 60_000);
+        const remainingMsAfterMin = remainingMsAfterHours % 60_000;
+        const sec = Math.floor(remainingMsAfterMin / 1000);
+        const ms = remainingMsAfterMin % 1000;
+        prettyDuration = `${days} ${days <= 1 ? "day" : "days"}, ${hours} h, ${min} min, ${sec} sec, ${ms} ms`;
+    }
+    else if (differenceInMs < 31_536_000_000) {
+        // Less than a year
+        const months = Math.floor(differenceInMs / 2_592_000_000);
+        const remainingMsAfterMonths = differenceInMs % 2_592_000_000;
+        const days = Math.floor(remainingMsAfterMonths / 86_400_000);
+        const remainingMsAfterDays = differenceInMs % 86_400_000;
+        const hours = Math.floor(remainingMsAfterDays / 3_600_000);
+        const remainingMsAfterHours = remainingMsAfterDays % 3_600_000;
+        const min = Math.floor(remainingMsAfterHours / 60_000);
+        const remainingMsAfterMin = remainingMsAfterHours % 60_000;
+        const sec = Math.floor(remainingMsAfterMin / 1000);
+        const ms = remainingMsAfterMin % 1000;
+        prettyDuration = `${months} ${months <= 1 ? "month" : "months"}, ${days} ${days <= 1 ? "day" : "days"}, ${hours} h, ${min} min, ${sec} sec, ${ms} ms`;
+    }
+    else {
+        // More than a year
+        const years = Math.floor(differenceInMs / 31_536_000_000);
+        const remainingMsAfterYears = differenceInMs % 31_536_000_000;
+        const months = Math.floor(remainingMsAfterYears / 2_592_000_000);
+        const remainingMsAfterMonths = differenceInMs % 2_592_000_000;
+        const days = Math.floor(remainingMsAfterMonths / 86_400_000);
+        const remainingMsAfterDays = differenceInMs % 86_400_000;
+        const hours = Math.floor(remainingMsAfterDays / 3_600_000);
+        const remainingMsAfterHours = remainingMsAfterDays % 3_600_000;
+        const min = Math.floor(remainingMsAfterHours / 60_000);
+        const remainingMsAfterMin = remainingMsAfterHours % 60_000;
+        const sec = Math.floor(remainingMsAfterMin / 1000);
+        const ms = remainingMsAfterMin % 1000;
+        prettyDuration = `${years} ${years <= 1 ? "year" : "years"}, ${months} ${months <= 1 ? "month" : "months"}, ${days} ${days <= 1 ? "day" : "days"}, ${hours} h, ${min} min, ${sec} sec, ${ms} ms`;
+    }
+    if (typeof options.prefix === "string") {
+        prettyDuration = `${options.prefix}${prettyDuration}`;
+    }
+    if (typeof options.suffix === "string") {
+        prettyDuration = `${prettyDuration}${options.suffix}`;
+    }
+    if (options.log === true) {
+        console.log(prettyDuration);
+    }
+    return prettyDuration;
+}