@augment-vir/common 29.2.0 → 30.0.0

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

@@ -0,0 +1,10 @@
+/**
+ * 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.
+ *
+ * @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.
+ */
+export declare function joinWithFinalConjunction(list: ReadonlyArray<any>, conjunction?: string): string;

package/dist/augments/string/join.js

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ *
+ * @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.
+ */
+export function joinWithFinalConjunction(list, 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/{types/augments/string/prefixes.d.ts → augments/string/prefix.d.ts}

@@ -1,9 +1,24 @@
+/**
+ * Generic string type but with the given prefix prepended to it.
+ *
+ * @category String
+ */
 export type WithPrefix<Prefix extends string> = `${Prefix}${string}`;
+/**
+ * Adds a prefix to a string if it does not already exist.
+ *
+ * @category String
+ */
 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
+ */
 export declare function removePrefix<const Prefix extends string>({ value, prefix, }: {
-    value: WithPrefix<Prefix> | string;
+    value: string;
     prefix: Prefix;
 }): string;

package/dist/{esm/augments/string/prefixes.js → augments/string/prefix.js}

@@ -1,3 +1,8 @@
+/**
+ * Adds a prefix to a string if it does not already exist.
+ *
+ * @category String
+ */
 export function addPrefix({ value, prefix, }) {
     if (String(value).startsWith(prefix)) {
         return String(value);
@@ -6,9 +11,14 @@ export function addPrefix({ value, prefix, }) {
         return `${prefix}${String(value)}`;
     }
 }
+/**
+ * Removes a prefix from a string if it exists.
+ *
+ * @category String
+ */
 export function removePrefix({ value, prefix, }) {
     if (value.startsWith(prefix)) {
-        return value.substring(prefix.length);
+        return value.slice(prefix.length);
     }
     else {
         return value;

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

@@ -0,0 +1 @@
+export declare function replaceStringAtIndex(originalString: string, start: number, newString: string, length?: number): string;

package/dist/augments/string/replace.js

@@ -0,0 +1,5 @@
+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,4 @@
+import type { AtLeastTuple } from '@augment-vir/core';
+/** Same as String.prototype.split but includes the delimiter to split by in the output array. */
+export declare function splitIncludeSplit(original: string, splitterInput: string | RegExp, caseSensitive: boolean): readonly string[];
+export declare function safeSplit(input: string, splitString: string): AtLeastTuple<string, 1>;

package/dist/augments/string/split.js

@@ -0,0 +1,28 @@
+import { makeCaseInsensitiveRegExp } from '../regexp/regexp-flags.js';
+import { getSubstringIndexes } from './substring-index.js';
+/** Same as String.prototype.split but includes the delimiter to split by in the output array. */
+export function splitIncludeSplit(original, splitterInput, caseSensitive) {
+    const indexLengths = getSubstringIndexes({
+        searchIn: original,
+        searchFor: splitterInput,
+        caseSensitive,
+        includeLength: true,
+    });
+    const splitter = makeCaseInsensitiveRegExp(splitterInput, 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;
+        }
+    }, []);
+}
+export function safeSplit(input, splitString) {
+    return input.split(splitString);
+}

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

@@ -0,0 +1,13 @@
+export declare function getSubstringIndexes<IncludeLength extends boolean | undefined>({ searchIn, searchFor, caseSensitive, includeLength, }: {
+    searchIn: string;
+    searchFor: string | RegExp;
+    /**
+     * CaseSensitive only applies when the input is a string. Otherwise, the RegExp's "i" flag is
+     * used to determine case sensitivity.
+     */
+    caseSensitive: boolean;
+    includeLength?: IncludeLength;
+}): IncludeLength extends true ? {
+    index: number;
+    length: number;
+}[] : number[];

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

@@ -0,0 +1,38 @@
+import { makeCaseInsensitiveRegExp } from '../regexp/regexp-flags.js';
+export function getSubstringIndexes({ searchIn, searchFor, caseSensitive, includeLength, }) {
+    const searchRegExp = makeCaseInsensitiveRegExp(searchFor, caseSensitive);
+    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,74 @@
+/**
+ * Generic string type but with the given suffix appended to it.
+ *
+ * @category String
+ */
+export type WithSuffix<Suffix extends string> = `${string}${Suffix}`;
+/**
+ * Suffix for {@link addPercent} and {@link removePercent}.
+ *
+ * @category String
+ */
+export declare const percentSuffix = "%";
+/**
+ * Suffix for {@link addPx} and {@link removePx}.
+ *
+ * @category String
+ */
+export declare const pxSuffix = "px";
+/**
+ * Generic string type but with the `'px'` suffix appended to it.
+ *
+ * @category String
+ */
+export type WithPx = WithSuffix<typeof pxSuffix>;
+/**
+ * Generic string type but with the `'%'` suffix appended to it.
+ *
+ * @category String
+ */
+export type WithPercent = WithSuffix<typeof percentSuffix>;
+/**
+ * Adds the `'px'` suffix to a string if it does not already exist.
+ *
+ * @category String
+ */
+export declare function addPx(input: number | string): WithPx;
+/**
+ * Removes the `'px'` suffix from a string if it exists.
+ *
+ * @category String
+ * @throws `TypeError` if the input can't be converted into a number.
+ */
+export declare function removePx(input: string): number;
+/**
+ * Adds the `'%'` suffix to a string if it does not already exist.
+ *
+ * @category String
+ */
+export declare function addPercent(input: number | string): WithPercent;
+/**
+ * Removes the `'%'` suffix from a string if it exists.
+ *
+ * @category String
+ * @throws `TypeError` if the input can't be converted into a number.
+ */
+export declare function removePercent(input: string): number;
+/**
+ * Adds a suffix to a string if it does not already exist.
+ *
+ * @category String
+ */
+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
+ */
+export declare function removeSuffix<const Suffix extends string>({ value, suffix, }: {
+    value: string;
+    suffix: Suffix;
+}): string;

package/dist/augments/string/suffix.js

@@ -0,0 +1,73 @@
+import { toEnsuredNumber } from '../number/number-conversion.js';
+/**
+ * Suffix for {@link addPercent} and {@link removePercent}.
+ *
+ * @category String
+ */
+export const percentSuffix = '%';
+/**
+ * Suffix for {@link addPx} and {@link removePx}.
+ *
+ * @category String
+ */
+export const pxSuffix = 'px';
+/**
+ * Adds the `'px'` suffix to a string if it does not already exist.
+ *
+ * @category String
+ */
+export function addPx(input) {
+    return addSuffix({ value: input, suffix: pxSuffix });
+}
+/**
+ * Removes the `'px'` suffix from a string if it exists.
+ *
+ * @category String
+ * @throws `TypeError` if the input can't be converted into a number.
+ */
+export function removePx(input) {
+    return toEnsuredNumber(removeSuffix({ value: input, suffix: pxSuffix }));
+}
+/**
+ * Adds the `'%'` suffix to a string if it does not already exist.
+ *
+ * @category String
+ */
+export function addPercent(input) {
+    return addSuffix({ value: input, suffix: percentSuffix });
+}
+/**
+ * Removes the `'%'` suffix from a string if it exists.
+ *
+ * @category String
+ * @throws `TypeError` if the input can't be converted into a number.
+ */
+export function removePercent(input) {
+    return toEnsuredNumber(removeSuffix({ value: input, suffix: percentSuffix }));
+}
+/**
+ * Adds a suffix to a string if it does not already exist.
+ *
+ * @category String
+ */
+export function addSuffix({ value, suffix, }) {
+    if (String(value).endsWith(suffix)) {
+        return String(value);
+    }
+    else {
+        return `${String(value)}${suffix}`;
+    }
+}
+/**
+ * Removes a suffix from a string if it exists.
+ *
+ * @category String
+ */
+export function removeSuffix({ value, suffix, }) {
+    if (value.endsWith(suffix)) {
+        return value.slice(0, Math.max(0, value.length - suffix.length));
+    }
+    else {
+        return value;
+    }
+}

package/dist/augments/string/white-space.d.ts

@@ -0,0 +1,5 @@
+import { PartialWithUndefined } from '@augment-vir/core';
+/** Collapse all consecutive white space into just one space and trim surrounding whitespace. */
+export declare function collapseWhiteSpace(input: string, { keepNewLines }?: PartialWithUndefined<{
+    keepNewLines: boolean;
+}>): string;

package/dist/augments/string/white-space.js

@@ -0,0 +1,12 @@
+/** Collapse all consecutive white space into just one space and trim surrounding whitespace. */
+export function collapseWhiteSpace(input, { keepNewLines } = {}) {
+    if (keepNewLines) {
+        return input
+            .trim()
+            .replaceAll(/[^\S\r\n]+/g, ' ')
+            .replaceAll(/[^\S\r\n]?\n+[^\S\r\n]?/g, '\n');
+    }
+    else {
+        return input.trim().replaceAll(/\s+/g, ' ');
+    }
+}

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

@@ -0,0 +1,4 @@
+export declare function wrapString({ value, wrapper }: {
+    value: string;
+    wrapper: string;
+}): string;

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

@@ -0,0 +1,5 @@
+import { addPrefix } from './prefix.js';
+import { addSuffix } from './suffix.js';
+export function wrapString({ value, wrapper }) {
+    return addPrefix({ value: addSuffix({ value, suffix: wrapper }), prefix: wrapper });
+}

package/dist/augments/type/ensure-type.d.ts

@@ -0,0 +1,8 @@
+/**
+ * This is a type helper that ensures the given input matches the given generic type. The generic is
+ * setup in such a way that if it is omitted (which is typically allowed in TypeScript, resulting in
+ * the generic being inferred from the inputs), there will actually be a type error. This forces
+ * each usage of this function to explicitly specify the generic, thus giving us type safety for the
+ * input.
+ */
+export declare function ensureType<ExpectedType = never>(input: NoInfer<ExpectedType>): NoInfer<ExpectedType>;

package/dist/augments/type/ensure-type.js

@@ -0,0 +1,10 @@
+/**
+ * This is a type helper that ensures the given input matches the given generic type. The generic is
+ * setup in such a way that if it is omitted (which is typically allowed in TypeScript, resulting in
+ * the generic being inferred from the inputs), there will actually be a type error. This forces
+ * each usage of this function to explicitly specify the generic, thus giving us type safety for the
+ * input.
+ */
+export function ensureType(input) {
+    return input;
+}

package/dist/augments/type/readonly.d.ts

@@ -0,0 +1,2 @@
+export type { ReadonlyDeep } from 'type-fest';
+export declare function makeReadonly<T>(input: T): Readonly<T>;

package/dist/augments/type/readonly.js

@@ -0,0 +1,3 @@
+export function makeReadonly(input) {
+    return input;
+}

package/dist/augments/type/type-recursion.js

@@ -0,0 +1 @@
+export {};

package/dist/augments/type/void-type.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Require that the NonVoid parameter is not void. If it is void, the ErrorType or an error string
+ * type is returned. If it not void, the given SuccessType is returned.
+ */
+export type RequireNonVoid<NonVoid, SuccessType, ErrorType = 'Input should not be void'> = void extends NonVoid ? (NonVoid extends void ? ErrorType : SuccessType) : SuccessType;

package/dist/augments/type/void-type.js

@@ -0,0 +1 @@
+export {};

package/dist/augments/type/writable.d.ts

@@ -0,0 +1,3 @@
+import type { Writable } from 'type-fest';
+export type { Writable, WritableDeep } from 'type-fest';
+export declare function makeWritable<T>(input: T): Writable<T>;

package/dist/augments/type/writable.js

@@ -0,0 +1,3 @@
+export function makeWritable(input) {
+    return input;
+}

package/dist/index.d.ts

@@ -0,0 +1,81 @@
+export * from './augments/array/array-map.js';
+export * from './augments/array/array-to-object.js';
+export * from './augments/array/awaited/awaited-filter.js';
+export * from './augments/array/awaited/awaited-for-each.js';
+export * from './augments/array/awaited/awaited-map.js';
+export * from './augments/array/filter.js';
+export * from './augments/array/remove-duplicates.js';
+export * from './augments/array/repeat-array.js';
+export * from './augments/array/shuffle-array.js';
+export * from './augments/array/string-array.js';
+export * from './augments/boolean/if-truthy.js';
+export * from './augments/core-exports.js';
+export * from './augments/enum/enum-value-check.js';
+export * from './augments/error/combine-errors.js';
+export * from './augments/file/esm-path.js';
+export * from './augments/function/call-asynchronously.js';
+export * from './augments/function/call-with-retries.js';
+export * from './augments/function/debounce.js';
+export * from './augments/function/execution-duration.js';
+export * from './augments/function/wrap-in-try.js';
+export * from './augments/json/append-json.js';
+export * from './augments/json/copy-through-json.js';
+export * from './augments/json/json-compatible.js';
+export * from './augments/json/jsonify.js';
+export * from './augments/log/log-colors.js';
+export * from './augments/log/log-string.js';
+export * from './augments/log/log-writer.js';
+export * from './augments/log/log.js';
+export * from './augments/log/logger.js';
+export * from './augments/number/clamp.js';
+export * from './augments/number/coords.js';
+export * from './augments/number/digit.js';
+export * from './augments/number/dimensions.js';
+export * from './augments/number/min-max.js';
+export * from './augments/number/number-conversion.js';
+export * from './augments/number/round.js';
+export * from './augments/number/scientific.js';
+export * from './augments/number/truncate-number.js';
+export * from './augments/number/wrap-number.js';
+export * from './augments/object/diff.js';
+export * from './augments/object/empty.js';
+export * from './augments/object/get-or-set.js';
+export * from './augments/object/key-count.js';
+export * from './augments/object/map-entries.js';
+export * from './augments/object/map-enum.js';
+export * from './augments/object/map-values.js';
+export * from './augments/object/merge-deep.js';
+export * from './augments/object/merge-defined-properties.js';
+export * from './augments/object/merge-property-arrays.js';
+export * from './augments/object/object-entries.js';
+export * from './augments/object/object-filter.js';
+export * from './augments/object/object-keys.js';
+export * from './augments/object/object-values.js';
+export * from './augments/prisma/prisma-models.js';
+export * from './augments/promise/timed-promise.js';
+export * from './augments/random/random-boolean.js';
+export * from './augments/random/random-integer.js';
+export * from './augments/random/random-string.js';
+export * from './augments/regexp/regexp-flags.js';
+export * from './augments/regexp/regexp-string.js';
+export * from './augments/regexp/safe-match.js';
+export * from './augments/selection-set/select-collapsed.js';
+export * from './augments/selection-set/select-from.js';
+export * from './augments/selection-set/selection-set.js';
+export * from './augments/string/casing/capitalization.js';
+export * from './augments/string/casing/casing.js';
+export * from './augments/string/casing/kebab-and-camel.js';
+export * from './augments/string/commas.js';
+export * from './augments/string/join.js';
+export * from './augments/string/prefix.js';
+export * from './augments/string/replace.js';
+export * from './augments/string/split.js';
+export * from './augments/string/substring-index.js';
+export * from './augments/string/suffix.js';
+export * from './augments/string/white-space.js';
+export * from './augments/string/wrap-string.js';
+export * from './augments/type/ensure-type.js';
+export * from './augments/type/readonly.js';
+export * from './augments/type/type-recursion.js';
+export * from './augments/type/void-type.js';
+export * from './augments/type/writable.js';

package/dist/index.js

@@ -0,0 +1,81 @@
+export * from './augments/array/array-map.js';
+export * from './augments/array/array-to-object.js';
+export * from './augments/array/awaited/awaited-filter.js';
+export * from './augments/array/awaited/awaited-for-each.js';
+export * from './augments/array/awaited/awaited-map.js';
+export * from './augments/array/filter.js';
+export * from './augments/array/remove-duplicates.js';
+export * from './augments/array/repeat-array.js';
+export * from './augments/array/shuffle-array.js';
+export * from './augments/array/string-array.js';
+export * from './augments/boolean/if-truthy.js';
+export * from './augments/core-exports.js';
+export * from './augments/enum/enum-value-check.js';
+export * from './augments/error/combine-errors.js';
+export * from './augments/file/esm-path.js';
+export * from './augments/function/call-asynchronously.js';
+export * from './augments/function/call-with-retries.js';
+export * from './augments/function/debounce.js';
+export * from './augments/function/execution-duration.js';
+export * from './augments/function/wrap-in-try.js';
+export * from './augments/json/append-json.js';
+export * from './augments/json/copy-through-json.js';
+export * from './augments/json/json-compatible.js';
+export * from './augments/json/jsonify.js';
+export * from './augments/log/log-colors.js';
+export * from './augments/log/log-string.js';
+export * from './augments/log/log-writer.js';
+export * from './augments/log/log.js';
+export * from './augments/log/logger.js';
+export * from './augments/number/clamp.js';
+export * from './augments/number/coords.js';
+export * from './augments/number/digit.js';
+export * from './augments/number/dimensions.js';
+export * from './augments/number/min-max.js';
+export * from './augments/number/number-conversion.js';
+export * from './augments/number/round.js';
+export * from './augments/number/scientific.js';
+export * from './augments/number/truncate-number.js';
+export * from './augments/number/wrap-number.js';
+export * from './augments/object/diff.js';
+export * from './augments/object/empty.js';
+export * from './augments/object/get-or-set.js';
+export * from './augments/object/key-count.js';
+export * from './augments/object/map-entries.js';
+export * from './augments/object/map-enum.js';
+export * from './augments/object/map-values.js';
+export * from './augments/object/merge-deep.js';
+export * from './augments/object/merge-defined-properties.js';
+export * from './augments/object/merge-property-arrays.js';
+export * from './augments/object/object-entries.js';
+export * from './augments/object/object-filter.js';
+export * from './augments/object/object-keys.js';
+export * from './augments/object/object-values.js';
+export * from './augments/prisma/prisma-models.js';
+export * from './augments/promise/timed-promise.js';
+export * from './augments/random/random-boolean.js';
+export * from './augments/random/random-integer.js';
+export * from './augments/random/random-string.js';
+export * from './augments/regexp/regexp-flags.js';
+export * from './augments/regexp/regexp-string.js';
+export * from './augments/regexp/safe-match.js';
+export * from './augments/selection-set/select-collapsed.js';
+export * from './augments/selection-set/select-from.js';
+export * from './augments/selection-set/selection-set.js';
+export * from './augments/string/casing/capitalization.js';
+export * from './augments/string/casing/casing.js';
+export * from './augments/string/casing/kebab-and-camel.js';
+export * from './augments/string/commas.js';
+export * from './augments/string/join.js';
+export * from './augments/string/prefix.js';
+export * from './augments/string/replace.js';
+export * from './augments/string/split.js';
+export * from './augments/string/substring-index.js';
+export * from './augments/string/suffix.js';
+export * from './augments/string/white-space.js';
+export * from './augments/string/wrap-string.js';
+export * from './augments/type/ensure-type.js';
+export * from './augments/type/readonly.js';
+export * from './augments/type/type-recursion.js';
+export * from './augments/type/void-type.js';
+export * from './augments/type/writable.js';