@augment-vir/common 30.0.0 → 30.0.2

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

@@ -2,9 +2,52 @@ 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;
-export declare function createLoggerWithStoredLogs(options?: PartialWithUndefined<LoggerOptions> | undefined): {
+/**
+ * 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[];

package/dist/augments/log/log.js

@@ -2,6 +2,13 @@ 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  */
@@ -24,11 +31,47 @@ isRuntimeEnv(RuntimeEnv.Node)
                 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);
-export function createLoggerWithStoredLogs(options) {
+/**
+ * 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 = {
-        stdout: [],
-        stderr: [],
+        [LogOutputType.Standard]: [],
+        [LogOutputType.Error]: [],
     };
     const log = createLogger({
         stderr({ text }) {

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

@@ -2,10 +2,59 @@ 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

@@ -2,14 +2,35 @@ 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) {

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

@@ -2,6 +2,17 @@ import { MinMax } from './min-max.js';
 /**
  * Clamp's the given value to within the min and max bounds, inclusive.
  *
- * @category Number:Common
+ * @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 }: MinMax): number;
+export declare function clamp(value: number, { min, max }: Readonly<MinMax>): number;

package/dist/augments/number/clamp.js

@@ -1,7 +1,18 @@
 /**
  * Clamp's the given value to within the min and max bounds, inclusive.
  *
- * @category Number:Common
+ * @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

@@ -1,7 +1,9 @@
 /**
  * A simple type for storing 2D coordinates.
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type Coords = {
     x: number;
@@ -10,7 +12,9 @@ export type Coords = {
 /**
  * A simple type for storing 3D coordinates.
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type Coords3d = {
     x: number;

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

@@ -1 +1,8 @@
+/**
+ * A union of all single digits in base 10.
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type Digit = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;

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

@@ -1,7 +1,9 @@
 /**
  * A simple type for storing 2D dimensions.
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type Dimensions = {
     width: number;
@@ -10,7 +12,9 @@ export type Dimensions = {
 /**
  * A simple type for storing 3D dimensions.
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type Dimensions3d = {
     width: number;

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

@@ -1,11 +1,18 @@
+/**
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 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.
+ * that is not the case, values are swapped.
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function ensureMinMax({ min, max }: MinMax): MinMax;

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

@@ -1,8 +1,10 @@
 /**
  * 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.
+ * that is not the case, values are swapped.
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function ensureMinMax({ min, max }) {
     if (min > max) {

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

@@ -2,22 +2,28 @@
  * 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
+ * @category Number
+ * @category Package : @augment-vir/common
  * @returns The converted number or `NaN`.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function toNumber(input: unknown): number;
 /**
  * Converts the input into a number and throws an error if the conversion fails.
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
  * @returns The converted number
  * @throws `TypeError` if the conversion resulted in `NaN`
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function toEnsuredNumber(input: unknown): number;
 /**
  * Converts the input into a number and returns `undefined` if the conversion fails.
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
  * @returns The converted number or `undefined`.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function toMaybeNumber(input: unknown): number | undefined;

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

@@ -1,10 +1,12 @@
-import { removeCommas } from '../string/commas.js';
+import { removeCommas } from '../string/comma.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
+ * @category Number
+ * @category Package : @augment-vir/common
  * @returns The converted number or `NaN`.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function toNumber(input) {
     if (typeof input === 'number') {
@@ -20,9 +22,11 @@ export function toNumber(input) {
 /**
  * Converts the input into a number and throws an error if the conversion fails.
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
  * @returns The converted number
  * @throws `TypeError` if the conversion resulted in `NaN`
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function toEnsuredNumber(input) {
     const maybeNumber = toMaybeNumber(input);
@@ -36,8 +40,10 @@ export function toEnsuredNumber(input) {
 /**
  * Converts the input into a number and returns `undefined` if the conversion fails.
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
  * @returns The converted number or `undefined`.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function toMaybeNumber(input) {
     const numeric = toNumber(input);

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

@@ -1,3 +1,22 @@
+/**
+ * Round a value to the given number of decimal digits. If no decimal value is present, no rounding
+ * occurs.
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {round} from '@augment-vir/common';
+ *
+ * // `result1` is `5.13`
+ * const result1 = round(5.125, {digits: 2});
+ * // `result2` is `5`
+ * const result2 = round(25, {digits: 2});
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function round(value: number, { digits }: {
     digits: number;
 }): number;

package/dist/augments/number/round.js

@@ -1,3 +1,22 @@
+/**
+ * Round a value to the given number of decimal digits. If no decimal value is present, no rounding
+ * occurs.
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {round} from '@augment-vir/common';
+ *
+ * // `result1` is `5.13`
+ * const result1 = round(5.125, {digits: 2});
+ * // `result2` is `5`
+ * const result2 = round(25, {digits: 2});
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function round(value, { digits }) {
     const digitFactor = Math.pow(10, digits);
     const multiplied = value * digitFactor;

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

@@ -1 +1,18 @@
-export declare function doesRequireScientificNotation(input: number): boolean;
+/**
+ * Determines if the given number is so large that it requires scientific notation (`e`) when
+ * represented as a string.
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {requiresScientificNotation} from '@augment-vir/common';
+ *
+ * requiresScientificNotation(5); // false
+ * requiresScientificNotation(999999999999999999999); // true
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function requiresScientificNotation(input: number): boolean;

package/dist/augments/number/scientific.js

@@ -1,3 +1,20 @@
-export function doesRequireScientificNotation(input) {
+/**
+ * Determines if the given number is so large that it requires scientific notation (`e`) when
+ * represented as a string.
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {requiresScientificNotation} from '@augment-vir/common';
+ *
+ * requiresScientificNotation(5); // false
+ * requiresScientificNotation(999999999999999999999); // true
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function requiresScientificNotation(input) {
     return String(input).includes('e');
 }

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

@@ -1,8 +1,16 @@
 /**
- * This truncates a number such that is will at a max have 6 characters including suffix, decimal
- * point, or comma.
+ * The default truncation prefixes for {@link truncateNumber}.
  *
- * Default suffixes are:
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const defaultTruncationSuffixes: readonly ["k", "M", "B", "T", "P", "E", "Z", "Y"];
+/**
+ * Truncates a number such that is will at a max have 6 (customizable) characters including suffix,
+ * decimal point, or comma.
+ *
+ * Default suffixes are in {@link defaultTruncationSuffixes}:
  *
  *     'k', // thousand
  *     'M', // million
@@ -12,6 +20,19 @@
  *     'E', // exa- quintillion
  *     'Z', // zetta- sextillion
  *     'Y', // yotta- septillion
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {truncateNumber} from '@augment-vir/common';
+ *
+ * // `result` will be `'1M'`
+ * const result = truncateNumber(1_000_000);
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function truncateNumber(originalValue: Readonly<unknown>, { customSuffixes, maxLength, }?: Partial<{
     customSuffixes: ReadonlyArray<string> | undefined;

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

@@ -1,9 +1,16 @@
-import { safeMatch } from '../regexp/safe-match.js';
-import { addCommasToNumber } from '../string/commas.js';
+import { safeMatch } from '../regexp/match.js';
+import { addCommasToNumber } from '../string/comma.js';
 import { safeSplit } from '../string/split.js';
 import { toNumber } from './number-conversion.js';
-import { doesRequireScientificNotation } from './scientific.js';
-const defaultTruncationSuffixes = [
+import { requiresScientificNotation } from './scientific.js';
+/**
+ * The default truncation prefixes for {@link truncateNumber}.
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export const defaultTruncationSuffixes = [
     'k', // thousand
     'M', // million
     'B', // billion
@@ -119,10 +126,10 @@ function handleSmallNumbers(numberAsString, maxLength) {
     return undefined;
 }
 /**
- * This truncates a number such that is will at a max have 6 characters including suffix, decimal
- * point, or comma.
+ * Truncates a number such that is will at a max have 6 (customizable) characters including suffix,
+ * decimal point, or comma.
  *
- * Default suffixes are:
+ * Default suffixes are in {@link defaultTruncationSuffixes}:
  *
  *     'k', // thousand
  *     'M', // million
@@ -132,6 +139,19 @@ function handleSmallNumbers(numberAsString, maxLength) {
  *     'E', // exa- quintillion
  *     'Z', // zetta- sextillion
  *     'Y', // yotta- septillion
+ *
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {truncateNumber} from '@augment-vir/common';
+ *
+ * // `result` will be `'1M'`
+ * const result = truncateNumber(1_000_000);
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function truncateNumber(originalValue, { customSuffixes = defaultTruncationSuffixes, maxLength = 6, } = {}) {
     const inputNumber = toNumber(originalValue);
@@ -140,7 +160,7 @@ export function truncateNumber(originalValue, { customSuffixes = defaultTruncati
         return String(inputNumber);
     }
     // handle too big or too small edge cases
-    if (doesRequireScientificNotation(inputNumber)) {
+    if (requiresScientificNotation(inputNumber)) {
         return truncateScientificNotation({ input: inputNumber, maxLength });
     }
     const numberAsString = String(inputNumber);

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

@@ -1,13 +1,19 @@
 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.
+ * {@link clamp} function does), this function wraps the value around to the next bound (inclusive).
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
+ * import {wrapNumber} from '@augment-vir/common';
+ *
  * wrapNumber({min: 0, max: 100, value: 101}); // 0
+ * wrapNumber({min: 0, max: 100, value: -1}); // 100
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
-export declare function wrapNumber(value: number, minMax: MinMax): number;
+export declare function wrapNumber(value: number, minMax: Readonly<MinMax>): number;

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

@@ -1,14 +1,20 @@
 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.
+ * {@link clamp} function does), this function wraps the value around to the next bound (inclusive).
  *
- * @category Number:Common
+ * @category Number
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
+ * import {wrapNumber} from '@augment-vir/common';
+ *
  * wrapNumber({min: 0, max: 100, value: 101}); // 0
+ * wrapNumber({min: 0, max: 100, value: -1}); // 100
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function wrapNumber(value, minMax) {
     const { min, max } = ensureMinMax(minMax);