@augment-vir/common 30.0.0 → 30.0.2

package/dist/augments/random/random-integer.d.ts

@@ -4,7 +4,9 @@
  *
  * This function uses cryptographically secure randomness.
  *
- * @category Random:Common
+ * @category Random
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function randomInteger({ min: rawMin, max: rawMax }: {
     min: number;

package/dist/augments/random/random-integer.js

@@ -5,7 +5,9 @@ import { ensureMinMax } from '../number/min-max.js';
  *
  * This function uses cryptographically secure randomness.
  *
- * @category Random:Common
+ * @category Random
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function randomInteger({ min: rawMin, max: rawMax }) {
     const { min, max } = ensureMinMax({ min: Math.floor(rawMin), max: Math.floor(rawMax) });

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

@@ -1,7 +1,9 @@
 /**
  * All letters allowed in {@link randomString}.
  *
- * @category Random:Common
+ * @category Random : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare const allowedRandomStringLetters: ReadonlyArray<string>;
 /**
@@ -9,6 +11,8 @@ export declare const allowedRandomStringLetters: ReadonlyArray<string>;
  *
  * This function uses cryptographically secure randomness.
  *
- * @category Random:Common
+ * @category Random
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function randomString(generatedStringLength?: number): string;

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

@@ -2,7 +2,9 @@ import { randomInteger } from './random-integer.js';
 /**
  * All letters allowed in {@link randomString}.
  *
- * @category Random:Common
+ * @category Random : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export const allowedRandomStringLetters = [
     'a',
@@ -47,7 +49,9 @@ export const allowedRandomStringLetters = [
  *
  * This function uses cryptographically secure randomness.
  *
- * @category Random:Common
+ * @category Random
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function randomString(generatedStringLength = 16) {
     let stringBuilder = '';

package/dist/augments/regexp/match.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Performs
+ * [`''.match`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/match)
+ * but falls back to an empty array if no match was found.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function safeMatch(input: string, regExp: RegExp): string[];

package/dist/augments/regexp/match.js

@@ -0,0 +1,13 @@
+/**
+ * Performs
+ * [`''.match`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/match)
+ * but falls back to an empty array if no match was found.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function safeMatch(input, regExp) {
+    const match = input.match(regExp);
+    return match ?? [];
+}

package/dist/augments/regexp/regexp-flags.d.ts

@@ -1,3 +1,56 @@
-export declare function deDupeRegExFlags(flags: string): string;
-export declare function addRegExpFlags(originalRegExp: RegExp, flags: string): RegExp;
-export declare function makeCaseInsensitiveRegExp(searchForInput: string | RegExp, caseSensitive: boolean): RegExp;
+/**
+ * Creates a new RegExp by adding the given `flags` to the original RegExp.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {addRegExpFlags} from '@augment-vir/common';
+ *
+ * addRegExpFlags(/a/i, 'gm');
+ * // output is `/a/igm`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function addRegExpFlags(originalRegExpOrString: RegExp | string, flags: string): RegExp;
+/**
+ * Creates a new RegExp with the given `flags`.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {setRegExpFlags} from '@augment-vir/common';
+ *
+ * setRegExpFlags(/a/i, 'gm');
+ * // output is `/a/gm`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function setRegExpFlags(originalRegExpOrString: RegExp | string, flags: string): RegExp;
+/**
+ * Creates a new RegExp by adding or removing the case insensitivity flag `'i'`, based on the given
+ * `caseSensitive` input. The first input can also be a string and it will be converted into a
+ * RegExp.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {setRegExpCaseSensitivity} from '@augment-vir/common';
+ *
+ * setRegExpCaseSensitivity(/abc/i, {caseSensitive: true}); // output is `/abc/`
+ * setRegExpCaseSensitivity(/abc/, {caseSensitive: false}); // output is `/abc/i`
+ * setRegExpCaseSensitivity('abc', {caseSensitive: true}); // output is `/abc/i`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function setRegExpCaseSensitivity(originalRegExpOrString: string | RegExp, { caseSensitive }: {
+    caseSensitive: boolean;
+}): RegExp;

package/dist/augments/regexp/regexp-flags.js

@@ -1,18 +1,75 @@
+import { removeDuplicateCharacters } from '../string/remove-duplicate-characters.js';
 import { escapeStringForRegExp } from './regexp-string.js';
-export function deDupeRegExFlags(flags) {
-    const deDuped = new Set(Array.from(flags.toLowerCase()));
-    return Array.from(deDuped).join('');
-}
-export function addRegExpFlags(originalRegExp, flags) {
-    return new RegExp(originalRegExp.source, deDupeRegExFlags([
-        originalRegExp.flags,
+/**
+ * Creates a new RegExp by adding the given `flags` to the original RegExp.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {addRegExpFlags} from '@augment-vir/common';
+ *
+ * addRegExpFlags(/a/i, 'gm');
+ * // output is `/a/igm`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function addRegExpFlags(originalRegExpOrString, flags) {
+    const allFlags = removeDuplicateCharacters([
+        typeof originalRegExpOrString === 'string' ? '' : originalRegExpOrString.flags,
         flags,
-    ].join('')));
+    ]
+        .join('')
+        .toLowerCase());
+    return setRegExpFlags(originalRegExpOrString, allFlags);
+}
+/**
+ * Creates a new RegExp with the given `flags`.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {setRegExpFlags} from '@augment-vir/common';
+ *
+ * setRegExpFlags(/a/i, 'gm');
+ * // output is `/a/gm`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function setRegExpFlags(originalRegExpOrString, flags) {
+    const allFlags = removeDuplicateCharacters(flags);
+    if (typeof originalRegExpOrString === 'string') {
+        return new RegExp(escapeStringForRegExp(originalRegExpOrString), allFlags);
+    }
+    else {
+        return new RegExp(originalRegExpOrString.source, allFlags);
+    }
 }
-export function makeCaseInsensitiveRegExp(searchForInput, caseSensitive) {
-    const regExpFlags = `g${!caseSensitive && typeof searchForInput === 'string' ? 'i' : ''}`;
-    const searchFor = searchForInput instanceof RegExp
-        ? new RegExp(searchForInput.source, deDupeRegExFlags(`${searchForInput.flags}${regExpFlags}`))
-        : new RegExp(escapeStringForRegExp(searchForInput), regExpFlags);
-    return searchFor;
+/**
+ * Creates a new RegExp by adding or removing the case insensitivity flag `'i'`, based on the given
+ * `caseSensitive` input. The first input can also be a string and it will be converted into a
+ * RegExp.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {setRegExpCaseSensitivity} from '@augment-vir/common';
+ *
+ * setRegExpCaseSensitivity(/abc/i, {caseSensitive: true}); // output is `/abc/`
+ * setRegExpCaseSensitivity(/abc/, {caseSensitive: false}); // output is `/abc/i`
+ * setRegExpCaseSensitivity('abc', {caseSensitive: true}); // output is `/abc/i`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function setRegExpCaseSensitivity(originalRegExpOrString, { caseSensitive }) {
+    const caseSensitivityFlag = caseSensitive ? '' : 'i';
+    return addRegExpFlags(originalRegExpOrString, caseSensitivityFlag);
 }

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

@@ -1,5 +1,9 @@
 /**
  * Escapes characters from the given string so that it can be used within a RegExp without being
  * parsed as RegExp syntax.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function escapeStringForRegExp(input: string): string;

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

@@ -1,7 +1,11 @@
 /**
  * Escapes characters from the given string so that it can be used within a RegExp without being
  * parsed as RegExp syntax.
+ *
+ * @category RegExp
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function escapeStringForRegExp(input) {
-    return input.replace(/[\^$\\.*+?()[\]{}|]/g, String.raw `\$&`);
+    return input.replaceAll(/[\^$\\.*+?()[\]{}|]/g, String.raw `\$&`);
 }

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;