@augment-vir/common 29.3.0 → 30.0.1

package/dist/augments/string/suffix.js

@@ -0,0 +1,89 @@
+import { toEnsuredNumber } from '../number/number-conversion.js';
+/**
+ * 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 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 const pxSuffix = 'px';
+/**
+ * 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 function addPx(input) {
+    return addSuffix({ value: input, suffix: pxSuffix });
+}
+/**
+ * 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 function removePx(input) {
+    return toEnsuredNumber(removeSuffix({ value: input, suffix: pxSuffix }));
+}
+/**
+ * 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 function addPercent(input) {
+    return addSuffix({ value: input, suffix: percentSuffix });
+}
+/**
+ * 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 function removePercent(input) {
+    return toEnsuredNumber(removeSuffix({ value: input, suffix: percentSuffix }));
+}
+/**
+ * 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 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
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+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,12 @@
+import { PartialWithUndefined } from '@augment-vir/core';
+/**
+ * Collapse all consecutive white space into just one space and trim surrounding whitespace.
+ * Optionally, collapsed newlines can be preserved.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function collapseWhiteSpace(input: string, { keepNewLines }?: PartialWithUndefined<{
+    keepNewLines: boolean;
+}>): string;

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

@@ -0,0 +1,19 @@
+/**
+ * Collapse all consecutive white space into just one space and trim surrounding whitespace.
+ * Optionally, collapsed newlines can be preserved.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+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,19 @@
+/**
+ * Wraps a string in another string.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {wrapString} from '@augment-vir/common';
+ *
+ * wrapString({value: 'some words', wrapper: '"'}); // outputs `'"some words"'`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function wrapString({ value, wrapper }: {
+    value: string;
+    wrapper: string;
+}): string;

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

@@ -0,0 +1,20 @@
+import { addPrefix } from './prefix.js';
+import { addSuffix } from './suffix.js';
+/**
+ * Wraps a string in another string.
+ *
+ * @category String
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {wrapString} from '@augment-vir/common';
+ *
+ * wrapString({value: 'some words', wrapper: '"'}); // outputs `'"some words"'`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+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,12 @@
+/**
+ * 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.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function ensureType<ExpectedType = never>(input: NoInfer<ExpectedType>): NoInfer<ExpectedType>;

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

@@ -0,0 +1,14 @@
+/**
+ * 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.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function ensureType(input) {
+    return input;
+}

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

@@ -0,0 +1,9 @@
+export type { ReadonlyDeep } from 'type-fest';
+/**
+ * This function does nothing but return the input as a readonly typed version of itself.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function makeReadonly<T>(input: T): Readonly<T>;

package/dist/augments/type/readonly.js

@@ -0,0 +1,10 @@
+/**
+ * This function does nothing but return the input as a readonly typed version of itself.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function makeReadonly(input) {
+    return input;
+}

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

@@ -0,0 +1,253 @@
+type TsRecursionArray = [
+    1,
+    2,
+    3,
+    4,
+    5,
+    6,
+    7,
+    8,
+    9,
+    10,
+    11,
+    12,
+    13,
+    14,
+    15,
+    16,
+    17,
+    18,
+    19,
+    20,
+    21,
+    22,
+    23,
+    24,
+    25,
+    26,
+    27,
+    28,
+    29,
+    30,
+    31,
+    32,
+    33,
+    34,
+    35,
+    36,
+    37,
+    38,
+    39,
+    40,
+    41,
+    42,
+    43,
+    44,
+    45,
+    46,
+    47,
+    48,
+    49,
+    50,
+    51,
+    52,
+    53,
+    54,
+    55,
+    56,
+    57,
+    58,
+    59,
+    60,
+    61,
+    62,
+    63,
+    64,
+    65,
+    66,
+    67,
+    68,
+    69,
+    70,
+    71,
+    72,
+    73,
+    74,
+    75,
+    76,
+    77,
+    78,
+    79,
+    80,
+    81,
+    82,
+    83,
+    84,
+    85,
+    86,
+    87,
+    88,
+    89,
+    90,
+    91,
+    92,
+    93,
+    94,
+    95,
+    96,
+    97,
+    98,
+    99,
+    100,
+    101,
+    102,
+    103,
+    104,
+    105,
+    106,
+    107,
+    108,
+    109,
+    110,
+    111,
+    112,
+    113,
+    114,
+    115,
+    116,
+    117,
+    118,
+    119,
+    120,
+    121,
+    122,
+    123,
+    124,
+    125,
+    126,
+    127,
+    128,
+    129,
+    130,
+    131,
+    132,
+    133,
+    134,
+    135,
+    136,
+    137,
+    138,
+    139,
+    140,
+    141,
+    142,
+    143,
+    144,
+    145,
+    146,
+    147,
+    148,
+    149,
+    150
+];
+/**
+ * This is used as the baseline type for TypeScript recursion tracking indexes. Use this to manually
+ * abort a type's recursion to prevent it from going too deep and throwing an error in TypeScript's
+ * language server.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {
+ *     TsRecursionTracker,
+ *     TsRecursionStart,
+ *     TsRecurse,
+ *     TsTooMuchRecursion,
+ * } from '@augment-vir/common';
+ *
+ * export type SomeType<Depth extends TsRecursionTracker = TsRecursionStart> =
+ *     Depth extends TsTooMuchRecursion
+ *         ? 'Error: recursive object depth is too deep.'
+ *         : SomeType<TsRecurse<Depth>>;
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type TsRecursionTracker = keyof TsRecursionArray;
+/**
+ * Through experimentation on Typescript version 5.4.5, this is the maximum recursion depth we can
+ * go to before TypeScript will block recursive types. Use this as the limit to type recursion.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {
+ *     TsRecursionTracker,
+ *     TsRecursionStart,
+ *     TsRecurse,
+ *     TsTooMuchRecursion,
+ * } from '@augment-vir/common';
+ *
+ * export type SomeType<Depth extends TsRecursionTracker = TsRecursionStart> =
+ *     Depth extends TsTooMuchRecursion
+ *         ? 'Error: recursive object depth is too deep.'
+ *         : SomeType<TsRecurse<Depth>>;
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type TsTooMuchRecursion = 91;
+/**
+ * This is the default starting recursion depth needed to get the full tested allowed recursion
+ * depth.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {
+ *     TsRecursionTracker,
+ *     TsRecursionStart,
+ *     TsRecurse,
+ *     TsTooMuchRecursion,
+ * } from '@augment-vir/common';
+ *
+ * export type SomeType<Depth extends TsRecursionTracker = TsRecursionStart> =
+ *     Depth extends TsTooMuchRecursion
+ *         ? 'Error: recursive object depth is too deep.'
+ *         : SomeType<TsRecurse<Depth>>;
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type TsRecursionStart = 0;
+/**
+ * Increments a TypeScript recursion depth tracker.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import type {
+ *     TsRecursionTracker,
+ *     TsRecursionStart,
+ *     TsRecurse,
+ *     TsTooMuchRecursion,
+ * } from '@augment-vir/common';
+ *
+ * export type SomeType<Depth extends TsRecursionTracker = TsRecursionStart> =
+ *     Depth extends TsTooMuchRecursion
+ *         ? 'Error: recursive object depth is too deep.'
+ *         : SomeType<TsRecurse<Depth>>;
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export type TsRecurse<CurrentRecursion extends TsRecursionTracker> = TsRecursionArray[CurrentRecursion] extends TsRecursionTracker ? TsRecursionArray[CurrentRecursion] : TsTooMuchRecursion;
+export {};

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

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

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

@@ -0,0 +1 @@
+export type { UnionToIntersection } from 'type-fest';

package/dist/augments/type/union.js

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

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

@@ -0,0 +1,9 @@
+/**
+ * Require that the given `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.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+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,10 @@
+import type { Writable } from 'type-fest';
+export type { Writable, WritableDeep } from 'type-fest';
+/**
+ * This function does nothing but return the input as a writable typed version of itself.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function makeWritable<T>(input: T): Writable<T>;

package/dist/augments/type/writable.js

@@ -0,0 +1,10 @@
+/**
+ * This function does nothing but return the input as a writable typed version of itself.
+ *
+ * @category Type
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function makeWritable(input) {
+    return input;
+}

package/dist/index.d.ts

@@ -0,0 +1,83 @@
+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/core-exports.js';
+export * from './augments/enum/enum-value-check.js';
+export * from './augments/error/combine-errors.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/if-truthy.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/path/esm-path.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/match.js';
+export * from './augments/regexp/regexp-flags.js';
+export * from './augments/regexp/regexp-string.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/comma.js';
+export * from './augments/string/join.js';
+export * from './augments/string/prefix.js';
+export * from './augments/string/remove-duplicate-characters.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/union.js';
+export * from './augments/type/void-type.js';
+export * from './augments/type/writable.js';