@augment-vir/common 30.0.0 → 30.0.1

package/dist/augments/selection-set/select-collapsed.d.ts

@@ -2,10 +2,53 @@ import type { AnyObject, Values } from '@augment-vir/core';
 import { ExcludeEmpty } from '../object/empty.js';
 import { KeyCount } from '../object/key-count.js';
 import { TsRecurse, TsRecursionStart, TsRecursionTracker, TsTooMuchRecursion } from '../type/type-recursion.js';
-import { GenericSelectionSet, PickSelection, SelectionSet } from './selection-set.js';
+import { GenericSelectionSet, SelectFrom, SelectionSet } from './selection-set.js';
+/**
+ * The same as {@link selectFrom} except that the final output is collapsed until the first nested
+ * value that has more than 1 key or that is not an object.
+ *
+ * @category Selection
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {selectCollapsedFrom} from '@augment-vir/common';
+ *
+ * selectCollapsedFrom(
+ *     [
+ *         {
+ *             child: {
+ *                 grandChild: 'hi',
+ *                 grandChild2: 3,
+ *                 grandChild3: /something/,
+ *             },
+ *         },
+ *         {
+ *             child: {
+ *                 grandChild: 'hi',
+ *                 grandChild2: 4,
+ *                 grandChild3: /something/,
+ *             },
+ *         },
+ *     ],
+ *     {
+ *         child: {
+ *             grandChild2: true,
+ *         },
+ *     },
+ * );
+ * // output is `[3, 4]`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function selectCollapsedFrom<Full extends AnyObject, const Selection extends SelectionSet<NoInfer<Full>>>(originalObject: Readonly<Full>, selectionSet: Readonly<Selection>): PickCollapsedSelection<Full, Selection>;
 /**
  * Collapses a selected value to the first part of the selection that contains more than 1 key or
- * that is not an object.
+ * that is not an object. This produces the output type for {@link selectCollapsedFrom}.
+ *
+ * @category Selection
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
-export type PickCollapsedSelection<Full extends Readonly<AnyObject>, Selection extends SelectionSet<Full>, Depth extends TsRecursionTracker = TsRecursionStart> = Depth extends TsTooMuchRecursion ? 'Error: recursive object depth is too deep.' : KeyCount<ExcludeEmpty<NonNullable<PickSelection<Full, Selection, Depth>>>> extends 1 ? Selection[keyof PickSelection<Full, Selection, Depth>] extends GenericSelectionSet ? PickCollapsedSelection<NonNullable<Full[keyof PickSelection<Full, Selection, Depth>]>, Selection[keyof PickSelection<Full, Selection, Depth>], TsRecurse<Depth>> | Extract<Full[keyof PickSelection<Full, Selection, Depth>], undefined | null> : Values<PickSelection<Full, Selection, Depth>> : PickSelection<Full, Selection, Depth>;
+export type PickCollapsedSelection<Full extends Readonly<AnyObject>, Selection extends SelectionSet<Full>, Depth extends TsRecursionTracker = TsRecursionStart> = Depth extends TsTooMuchRecursion ? 'Error: recursive object depth is too deep.' : KeyCount<ExcludeEmpty<NonNullable<SelectFrom<Full, Selection, Depth>>>> extends 1 ? Selection[keyof SelectFrom<Full, Selection, Depth>] extends GenericSelectionSet ? PickCollapsedSelection<NonNullable<Full[keyof SelectFrom<Full, Selection, Depth>]>, Selection[keyof SelectFrom<Full, Selection, Depth>], TsRecurse<Depth>> | Extract<Full[keyof SelectFrom<Full, Selection, Depth>], undefined | null> : Values<SelectFrom<Full, Selection, Depth>> : SelectFrom<Full, Selection, Depth>;

package/dist/augments/selection-set/select-collapsed.js

@@ -1,6 +1,44 @@
 import { check } from '@augment-vir/assert';
-import { selectFrom } from './select-from.js';
-import { shouldPreserveInSelectionSet, } from './selection-set.js';
+import { selectFrom, shouldPreserveInSelectionSet } from './select-from.js';
+/**
+ * The same as {@link selectFrom} except that the final output is collapsed until the first nested
+ * value that has more than 1 key or that is not an object.
+ *
+ * @category Selection
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {selectCollapsedFrom} from '@augment-vir/common';
+ *
+ * selectCollapsedFrom(
+ *     [
+ *         {
+ *             child: {
+ *                 grandChild: 'hi',
+ *                 grandChild2: 3,
+ *                 grandChild3: /something/,
+ *             },
+ *         },
+ *         {
+ *             child: {
+ *                 grandChild: 'hi',
+ *                 grandChild2: 4,
+ *                 grandChild3: /something/,
+ *             },
+ *         },
+ *     ],
+ *     {
+ *         child: {
+ *             grandChild2: true,
+ *         },
+ *     },
+ * );
+ * // output is `[3, 4]`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function selectCollapsedFrom(originalObject, selectionSet) {
     const selected = selectFrom(originalObject, selectionSet);
     return collapseObject(selected, selectionSet);

package/dist/augments/selection-set/select-from.d.ts

@@ -1,3 +1,48 @@
 import type { AnyObject } from '@augment-vir/core';
-import { PickSelection, SelectionSet } from './selection-set.js';
-export declare function selectFrom<Full extends AnyObject, const Selection extends SelectionSet<NoInfer<Full>>>(originalObject: Readonly<Full>, selectionSet: Readonly<Selection>): PickSelection<Full, Selection>;
+import { SelectFrom, SelectionSet } from './selection-set.js';
+/**
+ * Determine if the given input should be preserved in the selection output, meaning it won't be
+ * recursed into.
+ *
+ * @ignore
+ */
+export declare function shouldPreserveInSelectionSet(input: unknown): boolean;
+/**
+ * Performs a SQL-like nested selection on an object, extracting the selected values.
+ *
+ * @category Selection
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {selectFrom} from '@augment-vir/common';
+ *
+ * selectFrom(
+ *     [
+ *         {
+ *             child: {
+ *                 grandChild: 'hi',
+ *                 grandChild2: 3,
+ *                 grandChild3: /something/,
+ *             },
+ *         },
+ *         {
+ *             child: {
+ *                 grandChild: 'hi',
+ *                 grandChild2: 4,
+ *                 grandChild3: /something/,
+ *             },
+ *         },
+ *     ],
+ *     {
+ *         child: {
+ *             grandChild2: true,
+ *         },
+ *     },
+ * );
+ * // output is `[{child: {grandChild2: 3}}, {child: {grandChild2: 4}}]`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function selectFrom<Full extends AnyObject, const Selection extends SelectionSet<NoInfer<Full>>>(originalObject: Readonly<Full>, selectionSet: Readonly<Selection>): SelectFrom<Full, Selection>;

package/dist/augments/selection-set/select-from.js

@@ -1,6 +1,53 @@
+import { check } from '@augment-vir/assert';
 import { mapObjectValues } from '../object/map-values.js';
 import { omitObjectKeys } from '../object/object-keys.js';
-import { shouldPreserveInSelectionSet } from './selection-set.js';
+/**
+ * Determine if the given input should be preserved in the selection output, meaning it won't be
+ * recursed into.
+ *
+ * @ignore
+ */
+export function shouldPreserveInSelectionSet(input) {
+    return check.isPrimitive(input) || input instanceof RegExp || input instanceof Promise;
+}
+/**
+ * Performs a SQL-like nested selection on an object, extracting the selected values.
+ *
+ * @category Selection
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {selectFrom} from '@augment-vir/common';
+ *
+ * selectFrom(
+ *     [
+ *         {
+ *             child: {
+ *                 grandChild: 'hi',
+ *                 grandChild2: 3,
+ *                 grandChild3: /something/,
+ *             },
+ *         },
+ *         {
+ *             child: {
+ *                 grandChild: 'hi',
+ *                 grandChild2: 4,
+ *                 grandChild3: /something/,
+ *             },
+ *         },
+ *     ],
+ *     {
+ *         child: {
+ *             grandChild2: true,
+ *         },
+ *     },
+ * );
+ * // output is `[{child: {grandChild2: 3}}, {child: {grandChild2: 4}}]`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function selectFrom(originalObject, selectionSet) {
     if (Array.isArray(originalObject)) {
         return originalObject.map((originalEntry) => selectFrom(originalEntry, selectionSet));

package/dist/augments/selection-set/selection-set.d.ts

@@ -1,18 +1,37 @@
 import type { AnyObject } from '@augment-vir/core';
 import { IsAny, IsNever, Primitive, UnionToIntersection } from 'type-fest';
 import { TsRecurse, TsRecursionStart, TsRecursionTracker, TsTooMuchRecursion } from '../type/type-recursion.js';
-export declare function shouldPreserveInSelectionSet(input: unknown): input is SelectionTypesToPreserve;
 /** All types that won't be recursed into when defining a {@link SelectionSet}. */
-export type SelectionTypesToPreserve = Primitive | RegExp | Promise<any>;
-/** A generic selection set without specific keys. */
+type SelectionTypesToPreserve = Primitive | RegExp | Promise<any>;
+/**
+ * A generic selection set without specific keys. Useful for type parameter baselines.
+ *
+ * @category Selection
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type GenericSelectionSet = {
     [Key in PropertyKey]: unknown;
 };
-/** Masks an object value with the given {@link SelectionSet}. */
-export type PickSelection<Full extends Readonly<AnyObject>, Selection extends SelectionSet<Full>, Depth extends TsRecursionTracker = TsRecursionStart> = Depth extends TsTooMuchRecursion ? ['Error: recursive object depth is too deep.'] : Full extends ReadonlyArray<infer Element extends any> ? (PickSelection<Extract<Element, AnyObject>, Selection, TsRecurse<Depth>> | Exclude<Element, AnyObject>)[] : {
-    -readonly [Key in keyof Selection as Selection[Key] extends false ? never : Key extends keyof Full ? Key : never]: (Selection[Key] extends GenericSelectionSet ? PickSelection<NonNullable<Extract<Full[Key], AnyObject>>, Selection[Key], TsRecurse<Depth>> : Full[Key]) | Exclude<Full[Key], AnyObject>;
+/**
+ * Performs a SQL-like nested selection on an object, extracting the selected values. This produces
+ * the output type for `selectFrom`.
+ *
+ * @category Selection
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type SelectFrom<Full extends Readonly<AnyObject>, Selection extends SelectionSet<Full>, Depth extends TsRecursionTracker = TsRecursionStart> = Depth extends TsTooMuchRecursion ? ['Error: recursive object depth is too deep.'] : Full extends ReadonlyArray<infer Element extends any> ? (SelectFrom<Extract<Element, AnyObject>, Selection, TsRecurse<Depth>> | Exclude<Element, AnyObject>)[] : {
+    -readonly [Key in keyof Selection as Selection[Key] extends false ? never : Key extends keyof Full ? Key : never]: (Selection[Key] extends GenericSelectionSet ? SelectFrom<NonNullable<Extract<Full[Key], AnyObject>>, Selection[Key], TsRecurse<Depth>> : Full[Key]) | Exclude<Full[Key], AnyObject>;
 };
-/** Defines a selection set for the given object. */
+/**
+ * Defines a selection set for a given object type. This is used in {@link SelectFrom}.
+ *
+ * @category Selection
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type SelectionSet<Full extends Readonly<AnyObject>, Depth extends TsRecursionTracker = TsRecursionStart> = IsAny<Full> extends true ? any : Depth extends TsTooMuchRecursion ? boolean : Full extends ReadonlyArray<infer FullChild extends AnyObject> ? SelectionSet<FullChild, TsRecurse<Depth>> : Partial<{
     [Key in keyof Full]: IsNever<Exclude<Full[Key], SelectionTypesToPreserve>> extends true ? boolean : UnionToIntersection<SelectionSet<NonNullable<Required<Full>[Key]>, TsRecurse<Depth>>> | boolean;
 }>;
+export {};

package/dist/augments/selection-set/selection-set.js

@@ -1,4 +1 @@
-import { check } from '@augment-vir/assert';
-export function shouldPreserveInSelectionSet(input) {
-    return check.isPrimitive(input) || input instanceof RegExp || input instanceof Promise;
-}
+export {};

package/dist/augments/string/casing/capitalization.d.ts

@@ -1,3 +1,17 @@
 import { CasingOptions } from './casing.js';
-export declare function maybeCapitalize(input: string, casingOptions: Partial<CasingOptions>): string;
+/**
+ * Capitalize the first letter of the input _only if_ the given options specifies doing so.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function maybeCapitalize(input: string, casingOptions: Pick<CasingOptions, 'capitalizeFirstLetter'>): string;
+/**
+ * Capitalize the first letter of the input.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function capitalizeFirstLetter<InputGeneric extends string>(input: InputGeneric): Capitalize<InputGeneric>;

package/dist/augments/string/casing/capitalization.js

@@ -1,6 +1,20 @@
+/**
+ * Capitalize the first letter of the input _only if_ the given options specifies doing so.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function maybeCapitalize(input, casingOptions) {
     return casingOptions.capitalizeFirstLetter ? capitalizeFirstLetter(input) : input;
 }
+/**
+ * Capitalize the first letter of the input.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function capitalizeFirstLetter(input) {
     if (!input.length) {
         return '';

package/dist/augments/string/casing/casing.d.ts

@@ -1,20 +1,62 @@
 import { PartialWithUndefined } from '@augment-vir/core';
+/**
+ * Options for casing functions in `@augment-vir/common`.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type CasingOptions = {
+    /**
+     * Capitalize the first letter of the string.
+     *
+     * @default false
+     */
     capitalizeFirstLetter: boolean;
 };
+/**
+ * Default options for {@link CasingOptions}.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare const defaultCasingOptions: Required<CasingOptions>;
-export declare enum StringCaseEnum {
+/**
+ * The different string cases.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare enum StringCase {
     Upper = "upper",
     Lower = "lower"
 }
-/** Indicates whether the given string has different lower and upper case variants. */
+/**
+ * Indicates whether the given string has different lower and upper case variants. (Some strings
+ * don't, such as all numbers or `'√'`.)
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function hasCase(input: string): boolean;
+/**
+ * Options for {@link isCase}.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export type IsCaseOptions = {
     /**
-     * Fail on characters that don't have different upper and lower case versions (such as
-     * punctuation, like `'.'` or symbols, like `'√'`).
+     * Set to `true` to fail on characters that don't have different upper and lower case versions
+     * (such as punctuation, like `'.'` or symbols, like `'√'`).
+     *
+     * @default false
      */
-    failOnNoCaseCharacters: boolean;
+    rejectNoCaseCharacters: boolean;
 };
 /**
  * Checks if the given string is exclusively of the specific case.
@@ -22,6 +64,10 @@ export type IsCaseOptions = {
  * Note that some characters have no casing, such as punctuation (they have no difference between
  * upper and lower casings). By default, those letters always return `true` for this function,
  * regardless of which `caseType` is provided. To instead return `false` for any such characters,
- * pass in an options object and set blockNoCaseCharacters to true.
+ * pass in an options object and set `rejectNoCaseCharacters` to true.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
-export declare function isCase(input: string, caseType: StringCaseEnum, options?: PartialWithUndefined<IsCaseOptions>): boolean;
+export declare function isCase(input: string, caseType: StringCase, options?: PartialWithUndefined<IsCaseOptions>): boolean;

package/dist/augments/string/casing/casing.js

@@ -1,12 +1,33 @@
+/**
+ * Default options for {@link CasingOptions}.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export const defaultCasingOptions = {
     capitalizeFirstLetter: false,
 };
-export var StringCaseEnum;
-(function (StringCaseEnum) {
-    StringCaseEnum["Upper"] = "upper";
-    StringCaseEnum["Lower"] = "lower";
-})(StringCaseEnum || (StringCaseEnum = {}));
-/** Indicates whether the given string has different lower and upper case variants. */
+/**
+ * The different string cases.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export var StringCase;
+(function (StringCase) {
+    StringCase["Upper"] = "upper";
+    StringCase["Lower"] = "lower";
+})(StringCase || (StringCase = {}));
+/**
+ * Indicates whether the given string has different lower and upper case variants. (Some strings
+ * don't, such as all numbers or `'√'`.)
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function hasCase(input) {
     return input.toLowerCase() !== input.toUpperCase();
 }
@@ -16,23 +37,27 @@ export function hasCase(input) {
  * Note that some characters have no casing, such as punctuation (they have no difference between
  * upper and lower casings). By default, those letters always return `true` for this function,
  * regardless of which `caseType` is provided. To instead return `false` for any such characters,
- * pass in an options object and set blockNoCaseCharacters to true.
+ * pass in an options object and set `rejectNoCaseCharacters` to true.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function isCase(input, caseType, options) {
-    if (!input && options?.failOnNoCaseCharacters) {
+    if (!input && options?.rejectNoCaseCharacters) {
         return false;
     }
     for (const letter of input) {
         if (!hasCase(letter)) {
-            if (options?.failOnNoCaseCharacters) {
+            if (options?.rejectNoCaseCharacters) {
                 return false;
             }
             else {
                 continue;
             }
         }
-        else if ((caseType === StringCaseEnum.Upper && letter !== letter.toUpperCase()) ||
-            (caseType === StringCaseEnum.Lower && letter !== letter.toLowerCase())) {
+        else if ((caseType === StringCase.Upper && letter !== letter.toUpperCase()) ||
+            (caseType === StringCase.Lower && letter !== letter.toLowerCase())) {
             return false;
         }
     }

package/dist/augments/string/casing/kebab-and-camel.d.ts

@@ -1,3 +1,17 @@
 import { CasingOptions } from './casing.js';
+/**
+ * Converts a kebab-case string to CamelCase.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function kebabCaseToCamelCase(rawKebabCase: string, casingOptions?: Partial<CasingOptions> | undefined): string;
+/**
+ * Converts a CamelCase string to kebab-case.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function camelCaseToKebabCase(rawCamelCase: string): string;

package/dist/augments/string/casing/kebab-and-camel.js

@@ -1,6 +1,14 @@
+import { mergeDefinedProperties } from '../../object/merge-defined-properties.js';
 import { maybeCapitalize } from './capitalization.js';
-import { defaultCasingOptions, isCase, StringCaseEnum } from './casing.js';
-export function kebabCaseToCamelCase(rawKebabCase, casingOptions = defaultCasingOptions) {
+import { defaultCasingOptions, isCase, StringCase } from './casing.js';
+/**
+ * Converts a kebab-case string to CamelCase.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function kebabCaseToCamelCase(rawKebabCase, casingOptions = {}) {
     const kebabCase = rawKebabCase.toLowerCase();
     if (!kebabCase.length) {
         return '';
@@ -17,16 +25,23 @@ export function kebabCaseToCamelCase(rawKebabCase, casingOptions = defaultCasing
             return '';
         }
     });
-    return maybeCapitalize(camelCase, casingOptions);
+    return maybeCapitalize(camelCase, mergeDefinedProperties(defaultCasingOptions, casingOptions));
 }
+/**
+ * Converts a CamelCase string to kebab-case.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function camelCaseToKebabCase(rawCamelCase) {
     const kebabCase = rawCamelCase
         .split('')
         .reduce((accum, currentLetter, index, originalString) => {
         const previousLetter = index > 0 ? originalString[index - 1] || '' : '';
         const nextLetter = index < originalString.length - 1 ? originalString[index + 1] || '' : '';
-        const possibleWordBoundary = isCase(previousLetter, StringCaseEnum.Lower, { failOnNoCaseCharacters: true }) ||
-            isCase(nextLetter, StringCaseEnum.Lower, { failOnNoCaseCharacters: true });
+        const possibleWordBoundary = isCase(previousLetter, StringCase.Lower, { rejectNoCaseCharacters: true }) ||
+            isCase(nextLetter, StringCase.Lower, { rejectNoCaseCharacters: true });
         if (currentLetter === currentLetter.toLowerCase() ||
             index === 0 ||
             !possibleWordBoundary) {

package/dist/augments/string/comma.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Removes all commas from the given string.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function removeCommas(input: string): string;
+/**
+ * Convert the given number into a string, then add commas like a normal number would have.
+ *
+ * @category String
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {addCommasToNumber} from '@augment-vir/common';
+ *
+ * addCommasToNumber(1000123.456);
+ * // output is `'1,000,123.456'`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function addCommasToNumber(input: number | string): string;

package/dist/augments/string/{commas.js → comma.js}

@@ -1,12 +1,31 @@
-import { safeMatch } from '../regexp/safe-match.js';
+import { safeMatch } from '../regexp/match.js';
 /**
  * Removes all commas from the given string.
  *
- * @category String:Common
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function removeCommas(input) {
     return input.replace(/,/g, '');
 }
+/**
+ * Convert the given number into a string, then add commas like a normal number would have.
+ *
+ * @category String
+ * @category Number
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {addCommasToNumber} from '@augment-vir/common';
+ *
+ * addCommasToNumber(1000123.456);
+ * // output is `'1,000,123.456'`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function addCommasToNumber(input) {
     if (typeof input === 'string' && isNaN(Number(input))) {
         return 'NaN';

package/dist/augments/string/join.d.ts

@@ -3,8 +3,19 @@
  * item in the list. If the array has a length < 2, the conjunction is not added. If the list is
  * only of length 2, then no commas are added.
  *
- * @param list Array of items to be converted into strings. Works best if these are simply strings
- *   to begin with.
- * @param conjunction Defaults to 'and'. The conjunction to be used before the final element.
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
-export declare function joinWithFinalConjunction(list: ReadonlyArray<any>, conjunction?: string): string;
+export declare function joinWithFinalConjunction(
+/**
+ * Array of items to be converted into strings. Works best if these are simply strings to begin
+ * with.
+ */
+list: ReadonlyArray<any>, 
+/**
+ * The conjunction to be used before the final element.
+ *
+ * @default 'and'
+ */
+conjunction?: string): string;

package/dist/augments/string/join.js

@@ -3,11 +3,22 @@
  * item in the list. If the array has a length < 2, the conjunction is not added. If the list is
  * only of length 2, then no commas are added.
  *
- * @param list Array of items to be converted into strings. Works best if these are simply strings
- *   to begin with.
- * @param conjunction Defaults to 'and'. The conjunction to be used before the final element.
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
-export function joinWithFinalConjunction(list, conjunction = 'and') {
+export function joinWithFinalConjunction(
+/**
+ * Array of items to be converted into strings. Works best if these are simply strings to begin
+ * with.
+ */
+list, 
+/**
+ * The conjunction to be used before the final element.
+ *
+ * @default 'and'
+ */
+conjunction = 'and') {
     if (list.length < 2) {
         /**
          * If there are not multiple things in the list to join, just turn the list into a string