@augment-vir/common 29.3.0 → 30.0.1

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

@@ -0,0 +1,57 @@
+import { mergeDefinedProperties } from '../../object/merge-defined-properties.js';
+import { maybeCapitalize } from './capitalization.js';
+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 '';
+    }
+    const camelCase = kebabCase
+        .replace(/^-+/, '')
+        .replace(/-{2,}/g, '-')
+        .replace(/-(?:.|$)/g, (dashMatch) => {
+        const letter = dashMatch[1];
+        if (letter) {
+            return letter.toUpperCase();
+        }
+        else {
+            return '';
+        }
+    });
+    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, StringCase.Lower, { rejectNoCaseCharacters: true }) ||
+            isCase(nextLetter, StringCase.Lower, { rejectNoCaseCharacters: true });
+        if (currentLetter === currentLetter.toLowerCase() ||
+            index === 0 ||
+            !possibleWordBoundary) {
+            accum += currentLetter;
+        }
+        else {
+            accum += `-${currentLetter.toLowerCase()}`;
+        }
+        return accum;
+    }, '')
+        .toLowerCase();
+    return kebabCase;
+}

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/comma.js

@@ -0,0 +1,48 @@
+import { safeMatch } from '../regexp/match.js';
+/**
+ * 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 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';
+    }
+    const numericValue = Number(input);
+    const isNegative = numericValue < 0;
+    const stringValue = String(Math.abs(numericValue));
+    const [digits = '', decimalValues,] = stringValue.split('.');
+    const decimalString = decimalValues ? `.${decimalValues}` : '';
+    const separated = safeMatch(digits.split('').reverse().join(''), /.{1,3}/g)
+        .reverse()
+        .map((entry) => entry.split('').reverse().join(''));
+    const valueWithCommas = separated.join(',');
+    const negativeMarker = isNegative ? '-' : '';
+    return [
+        negativeMarker,
+        valueWithCommas,
+        decimalString,
+    ].join('');
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Join elements into a string with commas separating each value. Add a conjunction before the final
+ * 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.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+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

@@ -0,0 +1,34 @@
+/**
+ * Join elements into a string with commas separating each value. Add a conjunction before the final
+ * 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.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+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
+         * for an empty list, this will be '', for a single item list, this will just be the first
+         * item as a string.
+         */
+        return list.join('');
+    }
+    /** When there are only two items in the list, we don't want any commas. */
+    const commaSep = list.length > 2 ? ', ' : ' ';
+    const commaJoined = list.slice(0, -1).join(commaSep);
+    return `${commaJoined}${commaSep}${conjunction} ${list[list.length - 1]}`;
+}

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

@@ -0,0 +1,30 @@
+/**
+ * Generic string type but with the given prefix prepended to it.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type WithPrefix<Prefix extends string> = `${Prefix}${string}`;
+/**
+ * Adds a prefix to a string if it does not already exist.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function addPrefix<const Prefix extends string>({ value, prefix, }: {
+    value: unknown;
+    prefix: Prefix;
+}): WithPrefix<Prefix>;
+/**
+ * Removes a prefix from a string if it exists.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function removePrefix<const Prefix extends string>({ value, prefix, }: {
+    value: string;
+    prefix: Prefix;
+}): string;

package/dist/augments/string/prefix.js

@@ -0,0 +1,30 @@
+/**
+ * Adds a prefix to a string if it does not already exist.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function addPrefix({ value, prefix, }) {
+    if (String(value).startsWith(prefix)) {
+        return String(value);
+    }
+    else {
+        return `${prefix}${String(value)}`;
+    }
+}
+/**
+ * Removes a prefix from a string if it exists.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function removePrefix({ value, prefix, }) {
+    if (value.startsWith(prefix)) {
+        return value.slice(prefix.length);
+    }
+    else {
+        return value;
+    }
+}

package/dist/augments/string/remove-duplicate-characters.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Removes duplicate characters from any number of strings.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {removeDuplicateCharacters} from '@augment-vir/common';
+ *
+ * removeDuplicateCharacters('aAaBc', 'QrsAa');
+ * // output is `'aABcQrs'`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function removeDuplicateCharacters(...values: ReadonlyArray<string>): string;

package/dist/augments/string/remove-duplicate-characters.js

@@ -0,0 +1,22 @@
+import { removeDuplicates } from '../array/remove-duplicates.js';
+/**
+ * Removes duplicate characters from any number of strings.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {removeDuplicateCharacters} from '@augment-vir/common';
+ *
+ * removeDuplicateCharacters('aAaBc', 'QrsAa');
+ * // output is `'aABcQrs'`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function removeDuplicateCharacters(...values) {
+    const combined = values.join('');
+    const deDuped = removeDuplicates(Array.from(combined));
+    return Array.from(deDuped).join('');
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Replaces whatever substring is at the given index in the original string with the new string.
+ * Optionally, provide a length of the substring to get replaced.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {replaceStringAtIndex} from '@augment-vir/common';
+ *
+ * replaceStringAtIndex('eat the waffles', 4, 'his'); // outputs `'eat his waffles'`
+ * replaceStringAtIndex('eat the waffles', 4, 'my', 3); // outputs `'eat my waffles'`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function replaceStringAtIndex(originalString: string, start: number, newString: string, length?: number): string;

package/dist/augments/string/replace.js

@@ -0,0 +1,22 @@
+/**
+ * Replaces whatever substring is at the given index in the original string with the new string.
+ * Optionally, provide a length of the substring to get replaced.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {replaceStringAtIndex} from '@augment-vir/common';
+ *
+ * replaceStringAtIndex('eat the waffles', 4, 'his'); // outputs `'eat his waffles'`
+ * replaceStringAtIndex('eat the waffles', 4, 'my', 3); // outputs `'eat my waffles'`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function replaceStringAtIndex(originalString, start, newString, length = newString.length) {
+    const before = originalString.slice(0, Math.max(0, start));
+    const after = originalString.slice(Math.max(0, start + length));
+    return `${before}${newString}${after}`;
+}

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

@@ -0,0 +1,31 @@
+import type { AtLeastTuple } from '@augment-vir/core';
+/**
+ * Same as *
+ * [`''.split`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/split)
+ * but includes the split delimiter in the output array.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {splitIncludeSplit} from '@augment-vir/common';
+ *
+ * splitIncludeSplit('1,2,3', ',', {caseSensitive: false}); // outputs `['1', ',', '2', ',', '3']`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function splitIncludeSplit(original: string, splitDelimiter: string | RegExp, { caseSensitive }: {
+    caseSensitive: boolean;
+}): readonly string[];
+/**
+ * Same as
+ * [`''.split`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/split)
+ * but typed better: it always returns an array with at least one string.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function safeSplit(input: string, splitString: string): AtLeastTuple<string, 1>;

package/dist/augments/string/split.js

@@ -0,0 +1,53 @@
+import { setRegExpCaseSensitivity } from '../regexp/regexp-flags.js';
+import { findSubstringIndexes } from './substring-index.js';
+/**
+ * Same as *
+ * [`''.split`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/split)
+ * but includes the split delimiter in the output array.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {splitIncludeSplit} from '@augment-vir/common';
+ *
+ * splitIncludeSplit('1,2,3', ',', {caseSensitive: false}); // outputs `['1', ',', '2', ',', '3']`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function splitIncludeSplit(original, splitDelimiter, { caseSensitive }) {
+    const indexLengths = findSubstringIndexes({
+        searchIn: original,
+        searchFor: splitDelimiter,
+        caseSensitive,
+        includeLength: true,
+    });
+    const splitter = setRegExpCaseSensitivity(splitDelimiter, { caseSensitive });
+    const splits = original.split(splitter);
+    return splits.reduce((accum, current, index) => {
+        // this will be undefined on the last index
+        const splitterLength = indexLengths[index];
+        const includeCurrent = accum.concat(current);
+        if (splitterLength) {
+            const splitterMatch = original.slice(splitterLength.index, splitterLength.index + splitterLength.length);
+            return includeCurrent.concat(splitterMatch);
+        }
+        else {
+            return includeCurrent;
+        }
+    }, []);
+}
+/**
+ * Same as
+ * [`''.split`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/split)
+ * but typed better: it always returns an array with at least one string.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function safeSplit(input, splitString) {
+    return input.split(splitString);
+}

package/dist/augments/string/substring-index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Finds all indexes of a `searchFor` string or RegExp in `searchIn`. Ths is similar to
+ * [`''.indexOf`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf)
+ * except that it finds _all_ indexes of.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function findSubstringIndexes<IncludeLength extends boolean | undefined>({ searchIn, searchFor, caseSensitive, includeLength, }: {
+    searchIn: string;
+    searchFor: string | RegExp;
+    caseSensitive: boolean;
+    /** Set to true to get an array of objects with the found indexes _and_ their lengths. */
+    includeLength?: IncludeLength;
+}): IncludeLength extends true ? {
+    index: number;
+    length: number;
+}[] : number[];

package/dist/augments/string/substring-index.js

@@ -0,0 +1,47 @@
+import { addRegExpFlags, setRegExpCaseSensitivity } from '../regexp/regexp-flags.js';
+/**
+ * Finds all indexes of a `searchFor` string or RegExp in `searchIn`. Ths is similar to
+ * [`''.indexOf`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String/indexOf)
+ * except that it finds _all_ indexes of.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function findSubstringIndexes({ searchIn, searchFor, caseSensitive, includeLength, }) {
+    const searchRegExp = addRegExpFlags(setRegExpCaseSensitivity(searchFor, { caseSensitive }), 'g');
+    const indexes = [];
+    const indexesAndLengths = [];
+    searchIn.replace(searchRegExp, (...matchResults) => {
+        /**
+         * Grabbing the second to last entry in the array (rather than the second) takes capture
+         * groups into account.
+         */
+        const matchIndex = matchResults[matchResults.length - 2];
+        // this is used as a type safety catch and cannot actually be triggered on purpose
+        /* node:coverage ignore next 5 */
+        if (typeof matchIndex !== 'number') {
+            throw new TypeError(`Match index "${matchIndex}" is not a number. Searching for "${searchFor}" in "${searchIn}".`);
+        }
+        const regExpMatch = matchResults[0];
+        // this is used as a type safety catch and cannot actually be triggered on purpose
+        /* node:coverage ignore next 5 */
+        if (typeof regExpMatch !== 'string') {
+            throw new TypeError(`regExpMatch should've been a string but was ${typeof regExpMatch}!`);
+        }
+        indexesAndLengths.push({ index: matchIndex, length: regExpMatch.length });
+        indexes.push(matchIndex);
+        const originalMatch = matchResults[0];
+        // this is used as a type safety catch and cannot actually be triggered on purpose
+        /* node:coverage ignore next 5 */
+        if (typeof originalMatch !== 'string') {
+            throw new TypeError(`Original match when searching for "${searchFor}" in "${searchIn}" at index ${matchIndex} is not a string.`);
+        }
+        /**
+         * Don't actually change any text. What we do here doesn't matter because we're not
+         * using the output of the .replace method, we're just producing side effects.
+         */
+        return originalMatch;
+    });
+    return (includeLength ? indexesAndLengths : indexes);
+}

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

@@ -0,0 +1,96 @@
+/**
+ * Generic string type but with the given suffix appended to it.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type WithSuffix<Suffix extends string> = `${string}${Suffix}`;
+/**
+ * Suffix for {@link addPercent} and {@link removePercent}.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const percentSuffix = "%";
+/**
+ * Suffix for {@link addPx} and {@link removePx}.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare const pxSuffix = "px";
+/**
+ * Generic string type but with the `'px'` suffix appended to it.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type WithPx = WithSuffix<typeof pxSuffix>;
+/**
+ * Generic string type but with the `'%'` suffix appended to it.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type WithPercent = WithSuffix<typeof percentSuffix>;
+/**
+ * Adds the `'px'` suffix to a string if it does not already exist.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function addPx(input: number | string): WithPx;
+/**
+ * Removes the `'px'` suffix from a string if it exists.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @throws `TypeError` if the input can't be converted into a number.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function removePx(input: string): number;
+/**
+ * Adds the `'%'` suffix to a string if it does not already exist.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function addPercent(input: number | string): WithPercent;
+/**
+ * Removes the `'%'` suffix from a string if it exists.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @throws `TypeError` if the input can't be converted into a number.
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function removePercent(input: string): number;
+/**
+ * Adds a suffix to a string if it does not already exist.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function addSuffix<const Suffix extends string>({ value, suffix, }: {
+    value: unknown;
+    suffix: Suffix;
+}): WithSuffix<Suffix>;
+/**
+ * Removes a suffix from a string if it exists.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function removeSuffix<const Suffix extends string>({ value, suffix, }: {
+    value: string;
+    suffix: Suffix;
+}): string;