@augment-vir/common 29.2.0 → 30.0.0

package/dist/augments/json/jsonify.js

@@ -0,0 +1,4 @@
+import JSON5 from 'json5';
+export function jsonify(input) {
+    return JSON5.parse(JSON5.stringify(input));
+}

package/dist/augments/log/log-colors.d.ts

@@ -0,0 +1,23 @@
+export declare enum LogOutputType {
+    Standard = "stdout",
+    Error = "stderr"
+}
+export declare enum LogColorKey {
+    Bold = "bold",
+    Error = "error",
+    Faint = "faint",
+    Info = "info",
+    Mutate = "mutate",
+    NormalWeight = "normalWeight",
+    Plain = "plain",
+    Reset = "reset",
+    Success = "success",
+    Warning = "warning"
+}
+export type LogColorConfig = Readonly<Record<LogColorKey, {
+    /** Either an array of CSS property assignments */
+    colors: string[];
+    logType: LogOutputType;
+}>>;
+export declare const logColors: Readonly<Record<LogColorKey, string>>;
+export declare const defaultLogColorConfig: LogColorConfig;

package/dist/augments/log/log-colors.js

@@ -0,0 +1,116 @@
+import { forEachEnv, RuntimeEnv } from '@augment-vir/core';
+export var LogOutputType;
+(function (LogOutputType) {
+    LogOutputType["Standard"] = "stdout";
+    LogOutputType["Error"] = "stderr";
+})(LogOutputType || (LogOutputType = {}));
+export var LogColorKey;
+(function (LogColorKey) {
+    LogColorKey["Bold"] = "bold";
+    LogColorKey["Error"] = "error";
+    LogColorKey["Faint"] = "faint";
+    LogColorKey["Info"] = "info";
+    LogColorKey["Mutate"] = "mutate";
+    LogColorKey["NormalWeight"] = "normalWeight";
+    LogColorKey["Plain"] = "plain";
+    LogColorKey["Reset"] = "reset";
+    LogColorKey["Success"] = "success";
+    LogColorKey["Warning"] = "warning";
+})(LogColorKey || (LogColorKey = {}));
+async function determineDefaultLogColors() {
+    return await forEachEnv({
+        /** We calculate coverage in web, so the node code will never run in coverage tests. */
+        /* node:coverage disable  */
+        async [RuntimeEnv.Node]() {
+            const styles = (await import('ansi-styles')).default;
+            return {
+                [LogColorKey.Bold]: styles.bold.open,
+                [LogColorKey.Error]: styles.red.open,
+                [LogColorKey.Faint]: styles.gray.open,
+                [LogColorKey.Info]: styles.cyan.open,
+                [LogColorKey.Mutate]: styles.magenta.open,
+                [LogColorKey.NormalWeight]: '\x1b[22m',
+                [LogColorKey.Plain]: '',
+                [LogColorKey.Reset]: styles.reset.open,
+                [LogColorKey.Success]: styles.green.open,
+                [LogColorKey.Warning]: styles.yellow.open,
+            };
+        },
+        /* node:coverage enable  */
+        [RuntimeEnv.Web]() {
+            return Promise.resolve({
+                [LogColorKey.Bold]: 'font-weight: bold',
+                [LogColorKey.Error]: 'color: red',
+                [LogColorKey.Faint]: 'color: grey',
+                [LogColorKey.Info]: 'color: teal',
+                [LogColorKey.Mutate]: 'color: magenta',
+                [LogColorKey.NormalWeight]: '',
+                [LogColorKey.Plain]: '',
+                [LogColorKey.Reset]: '',
+                [LogColorKey.Success]: 'color: green',
+                [LogColorKey.Warning]: 'color: orange',
+            });
+        },
+    });
+}
+export const logColors = await determineDefaultLogColors();
+export const defaultLogColorConfig = {
+    [LogColorKey.Bold]: {
+        colors: [
+            logColors.bold,
+        ],
+        logType: LogOutputType.Standard,
+    },
+    [LogColorKey.Faint]: {
+        colors: [
+            logColors.faint,
+        ],
+        logType: LogOutputType.Standard,
+    },
+    [LogColorKey.Info]: {
+        colors: [
+            logColors.info,
+        ],
+        logType: LogOutputType.Standard,
+    },
+    [LogColorKey.Mutate]: {
+        colors: [
+            logColors.mutate,
+            logColors.bold,
+        ],
+        logType: LogOutputType.Standard,
+    },
+    [LogColorKey.NormalWeight]: {
+        colors: [
+            logColors.normalWeight,
+        ],
+        logType: LogOutputType.Standard,
+    },
+    [LogColorKey.Plain]: { colors: [], logType: LogOutputType.Standard },
+    [LogColorKey.Reset]: {
+        colors: [
+            logColors.reset,
+        ],
+        logType: LogOutputType.Standard,
+    },
+    [LogColorKey.Success]: {
+        colors: [
+            logColors.success,
+            logColors.bold,
+        ],
+        logType: LogOutputType.Standard,
+    },
+    [LogColorKey.Error]: {
+        colors: [
+            logColors.error,
+            logColors.bold,
+        ],
+        logType: LogOutputType.Error,
+    },
+    [LogColorKey.Warning]: {
+        colors: [
+            logColors.warning,
+        ],
+        logType: LogOutputType.Error,
+    },
+};

package/dist/augments/log/log-string.d.ts

@@ -0,0 +1,14 @@
+import { LogColorKey, type LogColorConfig } from './log-colors.js';
+import { LogWriterParams } from './log-writer.js';
+export type LoggerOptions = {
+    colorConfig: LogColorConfig;
+    omitColors: boolean;
+};
+export type ToLogStringParams = {
+    colorKey: LogColorKey;
+    args: ReadonlyArray<any>;
+    options: Readonly<LoggerOptions>;
+};
+type ToLogString = (params: Readonly<ToLogStringParams>) => LogWriterParams;
+export declare const toLogString: ToLogString;
+export {};

package/dist/augments/log/log-string.js

@@ -0,0 +1,66 @@
+import { check } from '@augment-vir/assert';
+import { forEachEnv, RuntimeEnv, stringify } from '@augment-vir/core';
+import { filterMap } from '../array/filter.js';
+import { removeSuffix } from '../string/suffix.js';
+import { LogColorKey } from './log-colors.js';
+async function createToLogString() {
+    return await forEachEnv({
+        /** We calculate coverage in web, so the node code will never run in coverage tests. */
+        /* node:coverage disable  */
+        async [RuntimeEnv.Node]() {
+            const { inspect } = await import('node:util');
+            return ({ args, colorKey, options }) => {
+                const argStrings = args.map((arg) => {
+                    if (typeof arg === 'string') {
+                        return arg;
+                    }
+                    else {
+                        return inspect(arg);
+                    }
+                });
+                const colorsString = options.omitColors
+                    ? ''
+                    : options.colorConfig[colorKey].colors.join('');
+                const text = [
+                    colorsString,
+                    argStrings.join('\n'),
+                    options.omitColors
+                        ? ''
+                        : options.colorConfig[LogColorKey.Reset].colors.join(''),
+                ].join('');
+                return { text, css: undefined };
+            };
+        },
+        /**
+         * We have no way to test color output in the browser console so this block is ignored in
+         * coverage as well.
+         */
+        [RuntimeEnv.Web]() {
+            return ({ args, colorKey, options }) => {
+                const css = options.omitColors
+                    ? undefined
+                    : filterMap(options.colorConfig[colorKey].colors, (cssString) => removeSuffix({
+                        value: cssString,
+                        suffix: ';',
+                    }), check.isTruthy).join('; ');
+                const argStrings = args.map((arg) => {
+                    if (typeof arg === 'string') {
+                        return arg;
+                    }
+                    else {
+                        return stringify(arg);
+                    }
+                });
+                const text = [
+                    argStrings.join('\n'),
+                    options.omitColors
+                        ? ''
+                        : options.colorConfig[LogColorKey.Reset].colors.join(''),
+                ].join('');
+                return { text, css };
+            };
+        },
+        /* node:coverage enable  */
+    });
+}
+export const toLogString = await createToLogString();

package/dist/augments/log/log-writer.d.ts

@@ -0,0 +1,8 @@
+import { type LogOutputType } from './log-colors.js';
+export type LogWriterParams = {
+    text: string;
+    /** Typically this is only relevant in a browser console. */
+    css: string | undefined;
+};
+export type LogWriter = (params: Readonly<LogWriterParams>) => void;
+export type LogWriters = Record<LogOutputType, LogWriter>;

package/dist/augments/log/log.d.ts

@@ -0,0 +1,13 @@
+import { type PartialWithUndefined } from '@augment-vir/core';
+import { LoggerOptions } from './log-string.js';
+import { LogWriters } from './log-writer.js';
+import { type Logger } from './logger.js';
+export declare const defaultLogWriters: LogWriters;
+export declare const log: Logger;
+export declare function createLoggerWithStoredLogs(options?: PartialWithUndefined<LoggerOptions> | undefined): {
+    log: Logger;
+    logs: {
+        stdout: string[];
+        stderr: string[];
+    };
+};

package/dist/augments/log/log.js

@@ -0,0 +1,42 @@
+import { isRuntimeEnv, RuntimeEnv } from '@augment-vir/core';
+import { addPrefix } from '../string/prefix.js';
+import { LogOutputType } from './log-colors.js';
+import { createLogger } from './logger.js';
+export const defaultLogWriters = 
+/** We calculate coverage in web, so the node code will never run in coverage tests. */
+/* node:coverage disable  */
+isRuntimeEnv(RuntimeEnv.Node)
+    ? {
+        [LogOutputType.Error]({ text }) {
+            process.stderr.write(text + '\n');
+        },
+        [LogOutputType.Standard]({ text }) {
+            process.stdout.write(text + '\n');
+        },
+    }
+    : /* node:coverage enable  */
+        {
+            [LogOutputType.Error]({ text, css }) {
+                console.error(addPrefix({ value: text, prefix: '%c' }), css);
+            },
+            [LogOutputType.Standard]({ text, css }) {
+                // eslint-disable-next-line no-console
+                console.log(addPrefix({ value: text, prefix: '%c' }), css);
+            },
+        };
+export const log = createLogger(defaultLogWriters);
+export function createLoggerWithStoredLogs(options) {
+    const logs = {
+        stdout: [],
+        stderr: [],
+    };
+    const log = createLogger({
+        stderr({ text }) {
+            logs.stderr.push(text);
+        },
+        stdout({ text }) {
+            logs.stdout.push(text);
+        },
+    }, options);
+    return { log, logs };
+}

package/dist/augments/log/logger.d.ts

@@ -0,0 +1,11 @@
+import type { PartialWithUndefined } from '@augment-vir/core';
+import { LogColorKey } from './log-colors.js';
+import { type LoggerOptions } from './log-string.js';
+import { type LogWriters } from './log-writer.js';
+export type LoggerLogs = Readonly<Record<LogColorKey, (...args: ReadonlyArray<unknown>) => void>>;
+export type Logger = LoggerLogs & {
+    if: (condition: boolean) => LoggerLogs;
+};
+export declare const defaultLoggerOptions: LoggerOptions;
+export declare const emptyLog: Logger;
+export declare function createLogger(logWriters: LogWriters, optionsOverride?: PartialWithUndefined<LoggerOptions> | undefined): Logger;

package/dist/augments/log/logger.js

@@ -0,0 +1,38 @@
+import { mapEnumToObject } from '../object/map-enum.js';
+import { mergeDefinedProperties } from '../object/merge-defined-properties.js';
+import { defaultLogColorConfig, LogColorKey, LogOutputType } from './log-colors.js';
+import { toLogString } from './log-string.js';
+export const defaultLoggerOptions = {
+    colorConfig: defaultLogColorConfig,
+    omitColors: false,
+};
+export const emptyLog = createLogger({
+    [LogOutputType.Error]() { },
+    [LogOutputType.Standard]() { },
+});
+export function createLogger(logWriters, optionsOverride) {
+    const options = mergeDefinedProperties(defaultLoggerOptions, optionsOverride);
+    function writeLog(params) {
+        logWriters[options.colorConfig[params.colorKey].logType](toLogString({
+            ...params,
+            options,
+        }));
+    }
+    const loggerLogs = mapEnumToObject(LogColorKey, (colorKey) => {
+        return (...args) => writeLog({
+            args,
+            colorKey,
+        });
+    });
+    return {
+        ...loggerLogs,
+        if(condition) {
+            if (condition) {
+                return loggerLogs;
+            }
+            else {
+                return emptyLog;
+            }
+        },
+    };
+}

package/dist/augments/number/clamp.d.ts

@@ -0,0 +1,7 @@
+import { MinMax } from './min-max.js';
+/**
+ * Clamp's the given value to within the min and max bounds, inclusive.
+ *
+ * @category Number:Common
+ */
+export declare function clamp(value: number, { min, max }: MinMax): number;

package/dist/augments/number/clamp.js

@@ -0,0 +1,8 @@
+/**
+ * Clamp's the given value to within the min and max bounds, inclusive.
+ *
+ * @category Number:Common
+ */
+export function clamp(value, { min, max }) {
+    return Math.min(Math.max(value, min), max);
+}

package/dist/augments/number/coords.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A simple type for storing 2D coordinates.
+ *
+ * @category Number:Common
+ */
+export type Coords = {
+    x: number;
+    y: number;
+};
+/**
+ * A simple type for storing 3D coordinates.
+ *
+ * @category Number:Common
+ */
+export type Coords3d = {
+    x: number;
+    y: number;
+    z: number;
+};

package/dist/augments/number/digit.d.ts

@@ -0,0 +1 @@
+export type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;

package/dist/augments/number/dimensions.d.ts

@@ -0,0 +1,19 @@
+/**
+ * A simple type for storing 2D dimensions.
+ *
+ * @category Number:Common
+ */
+export type Dimensions = {
+    width: number;
+    height: number;
+};
+/**
+ * A simple type for storing 3D dimensions.
+ *
+ * @category Number:Common
+ */
+export type Dimensions3d = {
+    width: number;
+    height: number;
+    depth: number;
+};

package/dist/augments/number/min-max.d.ts

@@ -0,0 +1,11 @@
+export type MinMax = {
+    min: number;
+    max: number;
+};
+/**
+ * Given a min and max, ensures that they are in correct order. Meaning, min is less than max. If
+ * that is not the case, the returned value is the given min and max values swapped.
+ *
+ * @category Number:Common
+ */
+export declare function ensureMinMax({ min, max }: MinMax): MinMax;

package/dist/augments/number/min-max.js

@@ -0,0 +1,14 @@
+/**
+ * Given a min and max, ensures that they are in correct order. Meaning, min is less than max. If
+ * that is not the case, the returned value is the given min and max values swapped.
+ *
+ * @category Number:Common
+ */
+export function ensureMinMax({ min, max }) {
+    if (min > max) {
+        return { min: max, max: min };
+    }
+    else {
+        return { min, max };
+    }
+}

package/dist/augments/number/number-conversion.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Converts the input into a number and returns `NaN` if the conversion fails. This handles more
+ * edge cases than just plain `Number(input)`.
+ *
+ * @category Number:Common
+ * @returns The converted number or `NaN`.
+ */
+export declare function toNumber(input: unknown): number;
+/**
+ * Converts the input into a number and throws an error if the conversion fails.
+ *
+ * @category Number:Common
+ * @returns The converted number
+ * @throws `TypeError` if the conversion resulted in `NaN`
+ */
+export declare function toEnsuredNumber(input: unknown): number;
+/**
+ * Converts the input into a number and returns `undefined` if the conversion fails.
+ *
+ * @category Number:Common
+ * @returns The converted number or `undefined`.
+ */
+export declare function toMaybeNumber(input: unknown): number | undefined;

package/dist/augments/number/number-conversion.js

@@ -0,0 +1,50 @@
+import { removeCommas } from '../string/commas.js';
+/**
+ * Converts the input into a number and returns `NaN` if the conversion fails. This handles more
+ * edge cases than just plain `Number(input)`.
+ *
+ * @category Number:Common
+ * @returns The converted number or `NaN`.
+ */
+export function toNumber(input) {
+    if (typeof input === 'number') {
+        return input;
+    }
+    else if (typeof input === 'string') {
+        return Number(removeCommas(input));
+    }
+    else {
+        return Number(input);
+    }
+}
+/**
+ * Converts the input into a number and throws an error if the conversion fails.
+ *
+ * @category Number:Common
+ * @returns The converted number
+ * @throws `TypeError` if the conversion resulted in `NaN`
+ */
+export function toEnsuredNumber(input) {
+    const maybeNumber = toMaybeNumber(input);
+    if (maybeNumber == undefined) {
+        throw new TypeError(`Cannot convert to a number: ${String(input)}`);
+    }
+    else {
+        return maybeNumber;
+    }
+}
+/**
+ * Converts the input into a number and returns `undefined` if the conversion fails.
+ *
+ * @category Number:Common
+ * @returns The converted number or `undefined`.
+ */
+export function toMaybeNumber(input) {
+    const numeric = toNumber(input);
+    if (isNaN(numeric)) {
+        return undefined;
+    }
+    else {
+        return numeric;
+    }
+}

package/dist/augments/number/round.d.ts

@@ -0,0 +1,3 @@
+export declare function round(value: number, { digits }: {
+    digits: number;
+}): number;

package/dist/augments/number/round.js

@@ -0,0 +1,5 @@
+export function round(value, { digits }) {
+    const digitFactor = Math.pow(10, digits);
+    const multiplied = value * digitFactor;
+    return Number((Math.round(multiplied) / digitFactor).toFixed(digits));
+}

package/dist/augments/number/scientific.d.ts

@@ -0,0 +1 @@
+export declare function doesRequireScientificNotation(input: number): boolean;

package/dist/augments/number/scientific.js

@@ -0,0 +1,3 @@
+export function doesRequireScientificNotation(input) {
+    return String(input).includes('e');
+}

package/dist/{esm/augments → augments/number}/truncate-number.js

@@ -1,6 +1,8 @@
-import { addCommasToNumber, convertIntoNumber, doesRequireScientificNotation } from './common-number';
-import { typedSplit } from './common-string';
-import { safeMatch } from './regexp';
+import { safeMatch } from '../regexp/safe-match.js';
+import { addCommasToNumber } from '../string/commas.js';
+import { safeSplit } from '../string/split.js';
+import { toNumber } from './number-conversion.js';
+import { doesRequireScientificNotation } from './scientific.js';
 const defaultTruncationSuffixes = [
     'k', // thousand
     'M', // million
@@ -32,23 +34,22 @@ function combineBeforeAndAfterDot({ beforeDot, afterDot = '', maxLength, }) {
     return beforeDot;
 }
 function truncateBigNumber(numberAsString, suffixes, maxLength) {
-    const [beforeDot, afterDot,] = typedSplit(numberAsString, '.');
+    const [beforeDot, afterDot,] = safeSplit(numberAsString, '.');
     const withCommas = addCommasToNumber(beforeDot);
     const truncationDepth = safeMatch(withCommas, /,/g).length;
     const suffix = suffixes[truncationDepth - 1];
-    const [beforeComma, afterComma,] = typedSplit(withCommas, ',');
+    const [beforeComma, afterComma,] = safeSplit(withCommas, ',');
     const trailing = [
         afterComma,
         afterDot,
     ].join('');
     if (beforeComma.length + 1 > maxLength) {
         // will look like 0.9M
-        const minimumString = [
+        return [
             '0.',
             beforeComma[0],
             suffixes[truncationDepth],
         ].join('');
-        return minimumString;
     }
     else {
         const combined = combineBeforeAndAfterDot({
@@ -65,15 +66,16 @@ function truncateBigNumber(numberAsString, suffixes, maxLength) {
 const minScientificNotationLength = '1e+'.length;
 function truncateScientificNotation({ input, maxLength, }) {
     const valueString = String(input);
-    const [beforeExponent, rawExponent,] = typedSplit(valueString, 'e');
-    const exponent = rawExponent.replace(/^[\-\+]/, '');
+    const [beforeExponent, rawExponent,] = safeSplit(valueString, 'e');
+    const exponent = rawExponent.replace(/^[-+]/, '');
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
     const plusOrMinus = rawExponent[0];
     const eSuffix = [
         'e',
         plusOrMinus,
         exponent,
     ].join('');
-    const [beforeDot, afterDot,] = typedSplit(beforeExponent, '.');
+    const [beforeDot, afterDot,] = safeSplit(beforeExponent, '.');
     const minLength = exponent.length + minScientificNotationLength;
     if (minLength === maxLength) {
         // this will look like "4e+4" or "5e-234"
@@ -105,7 +107,7 @@ function truncateScientificNotation({ input, maxLength, }) {
     }
 }
 function handleSmallNumbers(numberAsString, maxLength) {
-    const [beforeDot, afterDot,] = typedSplit(addCommasToNumber(numberAsString), '.');
+    const [beforeDot, afterDot,] = safeSplit(addCommasToNumber(numberAsString), '.');
     if (beforeDot.length <= maxLength) {
         return combineBeforeAndAfterDot({
             beforeDot,
@@ -132,7 +134,7 @@ function handleSmallNumbers(numberAsString, maxLength) {
  *     'Y', // yotta- septillion
  */
 export function truncateNumber(originalValue, { customSuffixes = defaultTruncationSuffixes, maxLength = 6, } = {}) {
-    const inputNumber = convertIntoNumber(originalValue);
+    const inputNumber = toNumber(originalValue);
     // handle edge cases
     if (isNaN(inputNumber) || inputNumber === Infinity) {
         return String(inputNumber);

package/dist/augments/number/wrap-number.d.ts

@@ -0,0 +1,13 @@
+import { MinMax } from './min-max.js';
+/**
+ * If the given value is outside the given min/max bounds, instead of clamping the number (as the
+ * `clamp` function does), this function wraps the value around to the next bound.
+ *
+ * @category Number:Common
+ * @example
+ *
+ * ```ts
+ * wrapNumber({min: 0, max: 100, value: 101}); // 0
+ * ```
+ */
+export declare function wrapNumber(value: number, minMax: MinMax): number;

package/dist/augments/number/wrap-number.js

@@ -0,0 +1,22 @@
+import { ensureMinMax } from './min-max.js';
+/**
+ * If the given value is outside the given min/max bounds, instead of clamping the number (as the
+ * `clamp` function does), this function wraps the value around to the next bound.
+ *
+ * @category Number:Common
+ * @example
+ *
+ * ```ts
+ * wrapNumber({min: 0, max: 100, value: 101}); // 0
+ * ```
+ */
+export function wrapNumber(value, minMax) {
+    const { min, max } = ensureMinMax(minMax);
+    if (value > max) {
+        return min;
+    }
+    else if (value < min) {
+        return max;
+    }
+    return value;
+}