@augment-vir/common 29.3.0 → 30.0.1

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

@@ -0,0 +1,64 @@
+/**
+ * Supported log output types.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare enum LogOutputType {
+    /** Logged to stdout if the current environment supports it, or just `console.log`. */
+    Standard = "stdout",
+    /** Logged to stderr if the current environment supports it, or just `console.error`. */
+    Error = "stderr"
+}
+/**
+ * Standardized color keys for logging. If you want to use customized colors, use
+ * [ansi-styles](https://www.npmjs.com/package/ansi-styles) in Node.js or [custom
+ * CSS](https://developer.mozilla.org/docs/Web/API/console#styling_console_output) in browsers.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare enum LogColorKey {
+    Bold = "bold",
+    Debug = "debug",
+    Error = "error",
+    Faint = "faint",
+    Info = "info",
+    Mutate = "mutate",
+    NormalWeight = "normalWeight",
+    Plain = "plain",
+    Reset = "reset",
+    Success = "success",
+    Warning = "warning"
+}
+/**
+ * Configuration for creating a logger. This is not required, as a default configuration is built-in
+ * already.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type LogColorConfig = Readonly<Record<LogColorKey, {
+    /** Either an array of CSS property assignments */
+    colors: string[];
+    logType: LogOutputType;
+}>>;
+/**
+ * Mapping of color keys to the current color string.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const logColors: Readonly<Record<LogColorKey, string>>;
+/**
+ * Default implementation of {@link LogColorConfig}.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const defaultLogColorConfig: LogColorConfig;

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

@@ -0,0 +1,157 @@
+import { perEnv, RuntimeEnv } from '@augment-vir/core';
+/**
+ * Supported log output types.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export var LogOutputType;
+(function (LogOutputType) {
+    /** Logged to stdout if the current environment supports it, or just `console.log`. */
+    LogOutputType["Standard"] = "stdout";
+    /** Logged to stderr if the current environment supports it, or just `console.error`. */
+    LogOutputType["Error"] = "stderr";
+})(LogOutputType || (LogOutputType = {}));
+/**
+ * Standardized color keys for logging. If you want to use customized colors, use
+ * [ansi-styles](https://www.npmjs.com/package/ansi-styles) in Node.js or [custom
+ * CSS](https://developer.mozilla.org/docs/Web/API/console#styling_console_output) in browsers.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export var LogColorKey;
+(function (LogColorKey) {
+    LogColorKey["Bold"] = "bold";
+    LogColorKey["Debug"] = "debug";
+    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 perEnv({
+        /** 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.Debug]: styles.blueBright.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.Debug]: 'color: blue',
+                [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',
+            });
+        },
+    });
+}
+/**
+ * Mapping of color keys to the current color string.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export const logColors = await determineDefaultLogColors();
+/**
+ * Default implementation of {@link LogColorConfig}.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export const defaultLogColorConfig = {
+    [LogColorKey.Bold]: {
+        colors: [
+            logColors.bold,
+        ],
+        logType: LogOutputType.Standard,
+    },
+    [LogColorKey.Debug]: {
+        colors: [
+            logColors.debug,
+        ],
+        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,35 @@
+import { LogColorKey, type LogColorConfig } from './log-colors.js';
+import { LogWriterParams } from './log-writer.js';
+/**
+ * Options for a custom Logger.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type LoggerOptions = {
+    colorConfig: LogColorConfig;
+    omitColors: boolean;
+};
+/**
+ * Parameters for {@link toLogString}.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type ToLogStringParams = {
+    colorKey: LogColorKey;
+    args: ReadonlyArray<any>;
+    options: Readonly<LoggerOptions>;
+};
+type ToLogString = (params: Readonly<ToLogStringParams>) => LogWriterParams;
+/**
+ * Converts log arguments into a single {@link LogWriterParams}.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const toLogString: ToLogString;
+export {};

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

@@ -0,0 +1,73 @@
+import { check } from '@augment-vir/assert';
+import { perEnv, 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 perEnv({
+        /** 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  */
+    });
+}
+/**
+ * Converts log arguments into a single {@link LogWriterParams}.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export const toLogString = await createToLogString();

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

@@ -0,0 +1,30 @@
+import { type LogOutputType } from './log-colors.js';
+/**
+ * Params for {@link LogWriter}
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type LogWriterParams = {
+    text: string;
+    /** Typically this is only relevant in a browser console. */
+    css: string | undefined;
+};
+/**
+ * The final step in writing a log. This will actually perform the logging of text to the console.
+ * CSS will be applied if this is called within a browser.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type LogWriter = (params: Readonly<LogWriterParams>) => void;
+/**
+ * A log writer for each log output type.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type LogWriters = Record<LogOutputType, LogWriter>;

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

@@ -0,0 +1,56 @@
+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';
+/**
+ * Default implementation of {@link LogWriters} that is dependent on the current runtime environment.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const defaultLogWriters: LogWriters;
+/**
+ * The default `log`. Use this in place of `console` methods for styled outputs in both Node.js and
+ * the browser.
+ *
+ * @category Log
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {log} from '@augment-vir/common';
+ *
+ * log.info('hi');
+ * log.error('failure');
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const log: Logger;
+/**
+ * Creates a custom logger that doesn't actually log but stores the logs into a object for later
+ * usage. This is particularly useful in tests.
+ *
+ * @category Log
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {createArrayLogger} from '@augment-vir/common';
+ *
+ * const {log, logs} = createArrayLogger();
+ *
+ * log.info('hi');
+ * // `logs[LogOutputType.Standard]` is now `['hi']`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function createArrayLogger(options?: PartialWithUndefined<LoggerOptions> | undefined): {
+    log: Logger;
+    logs: {
+        stdout: string[];
+        stderr: string[];
+    };
+};

package/dist/augments/log/log.js

@@ -0,0 +1,85 @@
+import { isRuntimeEnv, RuntimeEnv } from '@augment-vir/core';
+import { addPrefix } from '../string/prefix.js';
+import { LogOutputType } from './log-colors.js';
+import { createLogger } from './logger.js';
+/**
+ * Default implementation of {@link LogWriters} that is dependent on the current runtime environment.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+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);
+            },
+        };
+/**
+ * The default `log`. Use this in place of `console` methods for styled outputs in both Node.js and
+ * the browser.
+ *
+ * @category Log
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {log} from '@augment-vir/common';
+ *
+ * log.info('hi');
+ * log.error('failure');
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export const log = createLogger(defaultLogWriters);
+/**
+ * Creates a custom logger that doesn't actually log but stores the logs into a object for later
+ * usage. This is particularly useful in tests.
+ *
+ * @category Log
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {createArrayLogger} from '@augment-vir/common';
+ *
+ * const {log, logs} = createArrayLogger();
+ *
+ * log.info('hi');
+ * // `logs[LogOutputType.Standard]` is now `['hi']`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function createArrayLogger(options) {
+    const logs = {
+        [LogOutputType.Standard]: [],
+        [LogOutputType.Error]: [],
+    };
+    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,60 @@
+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';
+/**
+ * The base `log` methods.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type LoggerLogs = Readonly<Record<LogColorKey, (...args: ReadonlyArray<unknown>) => void>>;
+/**
+ * Type for the `log` export.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type Logger = LoggerLogs & {
+    /**
+     * Only logs if the given condition is `true`.
+     *
+     * @example
+     *
+     * ```ts
+     * import {log} from '@augment-vir/common';
+     *
+     * // this will log
+     * log.if(true).info('hi');
+     * // this will not log
+     * log.if(false).info('hi');
+     * ```
+     */
+    if: (condition: boolean) => LoggerLogs;
+};
+/**
+ * Default implementation of {@link LoggerOptions}.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const defaultLoggerOptions: LoggerOptions;
+/**
+ * A default {@link Logger} that simply does nothing.
+ *
+ * @category Log
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const emptyLog: Logger;
+/**
+ * Creates a custom {@link Logger}.
+ *
+ * @category Log
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function createLogger(logWriters: LogWriters, optionsOverride?: PartialWithUndefined<LoggerOptions> | undefined): Logger;

package/dist/augments/log/logger.js

@@ -0,0 +1,59 @@
+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';
+/**
+ * Default implementation of {@link LoggerOptions}.
+ *
+ * @category Log : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export const defaultLoggerOptions = {
+    colorConfig: defaultLogColorConfig,
+    omitColors: false,
+};
+/**
+ * A default {@link Logger} that simply does nothing.
+ *
+ * @category Log
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export const emptyLog = createLogger({
+    [LogOutputType.Error]() { },
+    [LogOutputType.Standard]() { },
+});
+/**
+ * Creates a custom {@link Logger}.
+ *
+ * @category Log
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+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,18 @@
+import { MinMax } from './min-max.js';
+/**
+ * Clamp's the given value to within the min and max bounds, inclusive.
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {clamp} from '@augment-vir/common';
+ *
+ * // `result` will be `40`
+ * const result = clamp(42, {min: 30, max: 40});
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function clamp(value: number, { min, max }: Readonly<MinMax>): number;

package/dist/augments/number/clamp.js

@@ -0,0 +1,19 @@
+/**
+ * Clamp's the given value to within the min and max bounds, inclusive.
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {clamp} from '@augment-vir/common';
+ *
+ * // `result` will be `40`
+ * const result = clamp(42, {min: 30, max: 40});
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/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,23 @@
+/**
+ * A simple type for storing 2D coordinates.
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type Coords = {
+    x: number;
+    y: number;
+};
+/**
+ * A simple type for storing 3D coordinates.
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type Coords3d = {
+    x: number;
+    y: number;
+    z: number;
+};