@augment-vir/common 30.0.0 → 30.0.2

package/dist/augments/function/if-truthy.d.ts

@@ -0,0 +1,28 @@
+import { type Falsy, type Truthy } from '@augment-vir/assert';
+/**
+ * Checks an input for truthiness then calls the respective callback, returning the callback's
+ * output.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {ifTruthy} from '@augment-vir/common';
+ *
+ * const result1 = ifTruthy(
+ *     true,
+ *     () => 1,
+ *     () => 2,
+ * ); // result1 is `1`
+ * const result2 = ifTruthy(
+ *     false,
+ *     () => 1,
+ *     () => 2,
+ * ); // result2 is `2`
+ * ```
+ *
+ * @returns The called callback's output.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function ifTruthy<const InputType, IfTruthyType, IfFalsyType>(checkThis: InputType, ifTruthyCallback: (truthyInput: Truthy<InputType>) => IfTruthyType, ifFalsyCallback: (truthyInput: Falsy<InputType>) => IfFalsyType): IfTruthyType | IfFalsyType;

package/dist/augments/function/if-truthy.js

@@ -0,0 +1,35 @@
+import { check } from '@augment-vir/assert';
+/**
+ * Checks an input for truthiness then calls the respective callback, returning the callback's
+ * output.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {ifTruthy} from '@augment-vir/common';
+ *
+ * const result1 = ifTruthy(
+ *     true,
+ *     () => 1,
+ *     () => 2,
+ * ); // result1 is `1`
+ * const result2 = ifTruthy(
+ *     false,
+ *     () => 1,
+ *     () => 2,
+ * ); // result2 is `2`
+ * ```
+ *
+ * @returns The called callback's output.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function ifTruthy(checkThis, ifTruthyCallback, ifFalsyCallback) {
+    if (check.isTruthy(checkThis)) {
+        return ifTruthyCallback(checkThis);
+    }
+    else {
+        return ifFalsyCallback(checkThis);
+    }
+}

package/dist/augments/function/wrap-in-try.d.ts

@@ -1,13 +1,21 @@
 import { type NoInputsFunction, type PartialWithUndefined } from '@augment-vir/core';
+/**
+ * Options for {@link wrapInTry}.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type WrapInTryOptions<FallbackValue> = PartialWithUndefined<{
     /**
-     * A callback that is passed the error. The output of this callback is returned by `wrapInTry`.
-     * This takes precedence over the other two options.
+     * Call this function if the callback passed to {@link wrapInTry} throws an error. The thrown
+     * error is passed to this function. If a `fallbackValue` option is also provided, it will be
+     * ignored.
      */
     handleError: (error: unknown) => FallbackValue;
     /**
-     * Fallback to this value if the callback passed to `wrapInTry` throws an error. Takes
-     * precedence over `returnError`.
+     * Fallback to this value if the callback passed to {@link wrapInTry} throws an error. This will
+     * be ignored if a `handleError` option is also set.
      */
     fallbackValue: FallbackValue;
 }>;

package/dist/augments/function/wrap-in-try.js

@@ -1,5 +1,69 @@
 import { check } from '@augment-vir/assert';
 import { ensureError, } from '@augment-vir/core';
+/**
+ * Calls the callback and returns its output. If the callback throws an error, it is handled in the
+ * following ways:
+ *
+ * - If a `handleError` function is provided in `options`, it is passed the thrown error. The output
+ *   of `handleError` is returned by `wrapInTry`.
+ * - If a `fallbackValue` is provided, it is returned by `wrapInTry`. The thrown error is ignored.
+ * - If no options are provided, the thrown error is returned by `wrapInTry`.
+ *
+ * @category Function
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {wrapInTry} from '@augment-vir/common';
+ *
+ * // `result1` will be `'success'`.
+ * const result1 = wrapInTry(
+ *     () => {
+ *         return 'success';
+ *     },
+ *     {
+ *         fallbackValue: 'failure',
+ *     },
+ * );
+ * // `result2` will be `'failure'`.
+ * const result2 = wrapInTry(
+ *     () => {
+ *         throw new Error();
+ *         return 'success';
+ *     },
+ *     {
+ *         fallbackValue: 'failure',
+ *     },
+ * );
+ * // `result3` will be `'failure also'`.
+ * const result3 = wrapInTry(
+ *     () => {
+ *         throw new Error();
+ *         return 'success';
+ *     },
+ *     {
+ *         handleError() {
+ *             return 'failure also';
+ *         },
+ *     },
+ * );
+ * // `result4` will be `'failure also'`.
+ * const result4 = wrapInTry(
+ *     () => {
+ *         throw new Error();
+ *         return 'success';
+ *     },
+ *     {
+ *         handleError() {
+ *             return 'failure also';
+ *         },
+ *         fallbackValue: 'ignored',
+ *     },
+ * );
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function wrapInTry(callback, options = {}) {
     try {
         const value = callback();

package/dist/augments/json/append-json.d.ts

@@ -1,5 +1,5 @@
 import type { JsonCompatibleArray, JsonCompatibleObject, JsonCompatibleValue } from './json-compatible.js';
-export declare function appendJson(...entries: ReadonlyArray<JsonCompatibleObject | undefined>): JsonCompatibleObject;
-export declare function appendJson(...entries: ReadonlyArray<JsonCompatibleArray | undefined>): JsonCompatibleArray;
-export declare function appendJson(...entries: ReadonlyArray<JsonCompatibleObject | JsonCompatibleArray | undefined>): JsonCompatibleObject | JsonCompatibleArray;
+import { JsonCompatiblePrimitive } from './json-compatible.js';
+export declare function appendJson(entry: JsonCompatibleArray | JsonCompatiblePrimitive, ...entries: ReadonlyArray<JsonCompatibleValue | undefined>): JsonCompatibleArray;
+export declare function appendJson(entry: JsonCompatibleObject, ...entries: ReadonlyArray<JsonCompatibleObject | JsonCompatibleArray | undefined>): JsonCompatibleObject;
 export declare function appendJson(...entries: ReadonlyArray<JsonCompatibleValue | undefined>): JsonCompatibleObject | JsonCompatibleArray;

package/dist/augments/json/append-json.js

@@ -1,5 +1,38 @@
 import { check } from '@augment-vir/assert';
 import { copyThroughJson } from './copy-through-json.js';
+/**
+ * Appends all provided JSON values together. `undefined` values will be ignored. The first value
+ * determines whether the output will be an object or an array. Any value appended to an array will
+ * work just fine, but primitives append to an object will likely behave unexpectedly. Arrays
+ * appended to arrays will be flattened (but only by one level).
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {appendJson} from '@augment-vir/common';
+ *
+ * // `result1` will be `{a: 'q', b: 'b'}`
+ * const result1 = appendJson({a: 'a'}, {b: 'b'}, {a: 'q'});
+ * // `result2` will be `[{a: 'a'}, {b: 'b'}, {a: 'q'}, 'r']`
+ * const result2 = appendJson([{a: 'a'}], {b: 'b'}, {a: 'q'}, 'r');
+ * // `result3` will be `['a', ['b', 'c'], 'd', 'e']`
+ * const result3 = appendJson(
+ *     ['a'],
+ *     [
+ *         [
+ *             'b',
+ *             'c',
+ *         ],
+ *     ],
+ *     ['d'],
+ *     'e',
+ * );
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function appendJson(...rawEntries) {
     const entries = rawEntries.filter(check.isTruthy);
     if (!check.isLengthAtLeast(entries, 1)) {

package/dist/augments/json/copy-through-json.d.ts

@@ -1,3 +1,34 @@
 import { Jsonify, Writable } from 'type-fest';
-/** The input here must be serializable otherwise the output will not match the input. */
+/**
+ * Deeply copy an object through JSON. This is the fastest deep copy, but the input must already be
+ * JSON serializable otherwise the copy will not match the original.
+ *
+ * @category JSON : Common
+ * @category Copy
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {copyThroughJson} from '@augment-vir/common';
+ *
+ * // `copy1` will be `{a: 'a', b: 'b'}`
+ * const copy1 = copyThroughJson({a: 'a', b: 'b'});
+ * // `copy2` will be `{map: {}, b: 'b'}`
+ * const copy2 = copyThroughJson({
+ *     map: new Map([
+ *         [
+ *             'q',
+ *             'r',
+ *         ],
+ *         [
+ *             's',
+ *             't',
+ *         ],
+ *     ]),
+ *     b: 'b',
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function copyThroughJson<const T>(input: T): Writable<Jsonify<T>>;

package/dist/augments/json/copy-through-json.js

@@ -1,4 +1,35 @@
-/** The input here must be serializable otherwise the output will not match the input. */
+/**
+ * Deeply copy an object through JSON. This is the fastest deep copy, but the input must already be
+ * JSON serializable otherwise the copy will not match the original.
+ *
+ * @category JSON : Common
+ * @category Copy
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {copyThroughJson} from '@augment-vir/common';
+ *
+ * // `copy1` will be `{a: 'a', b: 'b'}`
+ * const copy1 = copyThroughJson({a: 'a', b: 'b'});
+ * // `copy2` will be `{map: {}, b: 'b'}`
+ * const copy2 = copyThroughJson({
+ *     map: new Map([
+ *         [
+ *             'q',
+ *             'r',
+ *         ],
+ *         [
+ *             's',
+ *             't',
+ *         ],
+ *     ]),
+ *     b: 'b',
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function copyThroughJson(input) {
     try {
         return JSON.parse(JSON.stringify(input));

package/dist/augments/json/json-compatible.d.ts

@@ -1,22 +1,50 @@
 import { Jsonify, Primitive } from 'type-fest';
 /**
  * These are similar in purpose, name, and structure to type-fest's JsonValue types but these are
- * permissive. The goal here is to allow any types that do not get serialized into just empty
+ * more permissive. The goal here is to allow any types that do not get serialized into just empty
  * objects. (For example, JSON.stringify(new Map()) returns "{}", so we don't want to allow that
  * type.)
  */
-export type JsonCompatiblePrimitiveValue = Jsonify<Primitive> | undefined;
+/**
+ * All primitives that are allowed in JSON.
+ *
+ * Note that while `undefined` is allowed here, it will be behave slightly differently than the
+ * others.
+ *
+ * - `JSON.stringify(undefined)` will output `undefined`, not a string.
+ * - `JSON.stringify({a: null, b: undefined})` will output `'{"a": null}'`, omitting the `b` key
+ *   entirely.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type JsonCompatiblePrimitive = Jsonify<Primitive> | undefined;
+/**
+ * An object that only contains JSON compatible values.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type JsonCompatibleObject = Partial<{
     readonly [key: string | number]: JsonCompatibleValue | Readonly<JsonCompatibleValue>;
 }> | Partial<{
     [key: string | number]: JsonCompatibleValue | Readonly<JsonCompatibleValue>;
 }>;
-export type JsonCompatibleArray = JsonCompatibleValue[]
 /**
- * This weird readonly with object syntax for an array type is so that TypeScript doesn't
- * complain about JsonCompatibleArray circularly referencing itself
+ * An array that only contains JSON compatible values.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type JsonCompatibleArray = JsonCompatibleValue[] | ReadonlyArray<JsonCompatibleValue>;
+/**
+ * Any JSON compatible value.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
- | ({
-    readonly [P in number]: JsonCompatibleValue;
-} & ReadonlyArray<any>);
-export type JsonCompatibleValue = JsonCompatiblePrimitiveValue | JsonCompatibleObject | JsonCompatibleArray;
+export type JsonCompatibleValue = JsonCompatiblePrimitive | JsonCompatibleObject | JsonCompatibleArray;

package/dist/augments/json/jsonify.d.ts

@@ -1,2 +1,31 @@
 import { Jsonify } from 'type-fest';
-export declare function jsonify<T>(input: T): Jsonify<T>;
+/**
+ * Creates a JSON compatible version of the value given. Under the hood this is actually the same as
+ * {@link copyThroughJson}.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {jsonify} from '@augment-vir/common';
+ *
+ * // `result` is `{b: 'b'}`
+ * const result = jsonify({
+ *     map: new Map([
+ *         [
+ *             'q',
+ *             'r',
+ *         ],
+ *         [
+ *             's',
+ *             't',
+ *         ],
+ *     ]),
+ *     b: 'b',
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function jsonify<T>(value: T): Jsonify<T>;

package/dist/augments/json/jsonify.js

@@ -1,4 +1,33 @@
 import JSON5 from 'json5';
-export function jsonify(input) {
-    return JSON5.parse(JSON5.stringify(input));
+/**
+ * Creates a JSON compatible version of the value given. Under the hood this is actually the same as
+ * {@link copyThroughJson}.
+ *
+ * @category JSON : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {jsonify} from '@augment-vir/common';
+ *
+ * // `result` is `{b: 'b'}`
+ * const result = jsonify({
+ *     map: new Map([
+ *         [
+ *             'q',
+ *             'r',
+ *         ],
+ *         [
+ *             's',
+ *             't',
+ *         ],
+ *     ]),
+ *     b: 'b',
+ * });
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function jsonify(value) {
+    return JSON5.parse(JSON5.stringify(value));
 }

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

@@ -1,9 +1,28 @@
+/**
+ * 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",
@@ -14,10 +33,32 @@ export declare enum LogColorKey {
     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

@@ -1,12 +1,31 @@
-import { forEachEnv, RuntimeEnv } from '@augment-vir/core';
+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";
@@ -18,13 +37,14 @@ export var LogColorKey;
     LogColorKey["Warning"] = "warning";
 })(LogColorKey || (LogColorKey = {}));
 async function determineDefaultLogColors() {
-    return await forEachEnv({
+    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,
@@ -40,6 +60,7 @@ async function determineDefaultLogColors() {
         [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',
@@ -53,7 +74,21 @@ async function determineDefaultLogColors() {
         },
     });
 }
+/**
+ * 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: [
@@ -61,6 +96,12 @@ export const defaultLogColorConfig = {
         ],
         logType: LogOutputType.Standard,
     },
+    [LogColorKey.Debug]: {
+        colors: [
+            logColors.debug,
+        ],
+        logType: LogOutputType.Standard,
+    },
     [LogColorKey.Faint]: {
         colors: [
             logColors.faint,

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

@@ -1,14 +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

@@ -1,10 +1,10 @@
 import { check } from '@augment-vir/assert';
-import { forEachEnv, RuntimeEnv, stringify } from '@augment-vir/core';
+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 forEachEnv({
+    return await perEnv({
         /** We calculate coverage in web, so the node code will never run in coverage tests. */
         /* node:coverage disable  */
         async [RuntimeEnv.Node]() {
@@ -63,4 +63,11 @@ async function createToLogString() {
         /* 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

@@ -1,8 +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>;