@augment-vir/common 30.0.0 → 30.0.1

package/dist/augments/object/object-keys.d.ts

@@ -1,2 +1,34 @@
+/**
+ * Same as the TypeScript built-in type `Omit` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {omitObjectKeys} from '@augment-vir/common';
+ *
+ * omitObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{b: 'b'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function omitObjectKeys<const ObjectGeneric, const KeyGeneric extends keyof ObjectGeneric>(inputObject: Readonly<ObjectGeneric>, omitTheseKeys: ReadonlyArray<KeyGeneric>): Omit<ObjectGeneric, KeyGeneric>;
+/**
+ * Same as the TypeScript built-in type `Pick` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {pickObjectKeys} from '@augment-vir/common';
+ *
+ * pickObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{a: 'a'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function pickObjectKeys<const ObjectGeneric, const KeyGeneric extends keyof ObjectGeneric>(inputObject: Readonly<ObjectGeneric>, pickTheseKeys: ReadonlyArray<KeyGeneric>): Pick<ObjectGeneric, KeyGeneric>;

package/dist/augments/object/object-keys.js

@@ -1,9 +1,41 @@
 import { filterObject } from './object-filter.js';
+/**
+ * Same as the TypeScript built-in type `Omit` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {omitObjectKeys} from '@augment-vir/common';
+ *
+ * omitObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{b: 'b'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function omitObjectKeys(inputObject, omitTheseKeys) {
     return filterObject(inputObject, (currentKey) => {
         return !omitTheseKeys.includes(currentKey);
     });
 }
+/**
+ * Same as the TypeScript built-in type `Pick` except that it works on actual runtime values.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {pickObjectKeys} from '@augment-vir/common';
+ *
+ * pickObjectKeys({a: 'a', b: 'b'}, ['a']);
+ * // output is `{a: 'a'}`
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function pickObjectKeys(inputObject, pickTheseKeys) {
     return filterObject(inputObject, (currentKey) => {
         return pickTheseKeys.includes(currentKey);

package/dist/augments/object/object-values.d.ts

@@ -1,2 +1,11 @@
 import { CompleteRequire } from '@augment-vir/core';
+/**
+ * Gets an object's values. This is the same as
+ * [`Object.values`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/values)
+ * except that it has better TypeScript types.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function getObjectTypedValues<ObjectGeneric>(input: ObjectGeneric): CompleteRequire<ObjectGeneric>[keyof CompleteRequire<ObjectGeneric>][];

package/dist/augments/object/object-values.js

@@ -1,4 +1,13 @@
 import { getObjectTypedKeys } from '@augment-vir/core';
+/**
+ * Gets an object's values. This is the same as
+ * [`Object.values`](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object/values)
+ * except that it has better TypeScript types.
+ *
+ * @category Object
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function getObjectTypedValues(input) {
     return getObjectTypedKeys(input).map((key) => input[key]);
 }

package/dist/augments/path/esm-path.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Creates the equivalent of CJS's
+ * [`__dirname`](https://nodejs.org/docs/latest/api/globals.html#__dirname) and
+ * [`__filename`](https://nodejs.org/docs/latest/api/globals.html#__filename) for ESM modules.
+ *
+ * This is the equivalent of
+ * [`import.meta.dirname`](https://nodejs.org/api/esm.html#importmetadirname) and
+ * [`import.meta.filename`](https://nodejs.org/api/esm.html#importmetafilename) added to Node.js
+ * v20.11.0 but is compatible with older versions of Node.js as well as browsers.
+ *
+ * @category Path : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {getEsmPath} from '@augment-vir/common';
+ *
+ * const {filePath, dirPath} = getEsmPath(import.meta);
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export declare function getEsmPath(importMeta: ImportMeta): {
+    filePath: string;
+    dirPath: string;
+};

package/dist/augments/path/esm-path.js

@@ -0,0 +1,31 @@
+import { removeSuffix } from '../string/suffix.js';
+/**
+ * Creates the equivalent of CJS's
+ * [`__dirname`](https://nodejs.org/docs/latest/api/globals.html#__dirname) and
+ * [`__filename`](https://nodejs.org/docs/latest/api/globals.html#__filename) for ESM modules.
+ *
+ * This is the equivalent of
+ * [`import.meta.dirname`](https://nodejs.org/api/esm.html#importmetadirname) and
+ * [`import.meta.filename`](https://nodejs.org/api/esm.html#importmetafilename) added to Node.js
+ * v20.11.0 but is compatible with older versions of Node.js as well as browsers.
+ *
+ * @category Path : Common
+ * @category Package : @augment-vir/common
+ * @example
+ *
+ * ```ts
+ * import {getEsmPath} from '@augment-vir/common';
+ *
+ * const {filePath, dirPath} = getEsmPath(import.meta);
+ * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
+export function getEsmPath(importMeta) {
+    const filePath = new URL('', importMeta.url).pathname;
+    const dirPath = removeSuffix({ value: new URL('.', importMeta.url).pathname, suffix: '/' });
+    return {
+        filePath,
+        dirPath,
+    };
+}

package/dist/augments/prisma/prisma-models.d.ts

@@ -2,25 +2,35 @@ import type { AnyFunction, AnyObject } from '@augment-vir/core';
 /**
  * Extracts all model names from a generated `Prisma` object.
  *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
  * import type {Prisma} from '@prisma/client';
+ * import type {ModelNameFromPrismaTypeMap} from '@augment-vir/common';
  *
  * function doThing(modelName: ModelNameFromPrismaTypeMap<Prisma.TypeMap>) {}
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type ModelNameFromPrismaTypeMap<PrismaTypeMap extends BasePrismaTypeMap> = PrismaTypeMap['meta']['modelProps'];
 /**
  * Extracts all model names from a generated `PrismaClient`.
  *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
  * import type {PrismaClient} from '@prisma/client';
+ * import type {ModelNameFromPrismaClient} from '@augment-vir/common';
  *
  * function doThing(modelName: ModelNameFromPrismaClient<PrismaClient>) {}
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type ModelNameFromPrismaClient<PrismaClient extends AnyObject> = keyof {
     [Model in Extract<keyof PrismaClient, string> as PrismaClient[Model] extends {
@@ -30,20 +40,29 @@ export type ModelNameFromPrismaClient<PrismaClient extends AnyObject> = keyof {
 /**
  * Extracts the creation data for a model from the given `PrismaClient` type.
  *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
  * import type {PrismaClient} from '@prisma/client';
+ * import type {ModelCreationEntry} from '@augment-vir/common';
  *
  * function doThing(entry: ModelCreationEntry<PrismaClient, 'User'>) {}
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type PrismaModelCreationEntry<PrismaClient extends AnyObject, Model extends ModelNameFromPrismaClient<PrismaClient>> = NonNullable<Parameters<PrismaClient[Model]['create']>[0]> extends {
     data?: infer Data;
 } ? NonNullable<Data> : `ERROR: failed to infer creation entry for model '${Model}'`;
 /**
  * A base type for `Prisma.TypeMap` because Prisma doesn't give us one. This currently only includes
- * the properties that are used within `@augment-vir/prisma-node-js`.
+ * the properties that are used within `@augment-vir/common`.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type BasePrismaTypeMap = {
     meta: {
@@ -59,6 +78,10 @@ export type BasePrismaTypeMap = {
  *
  * Note: this omits the `composites` property because I don't have any examples of what those
  * actually are.
+ *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type BasePrismaPayload = {
     name: string;
@@ -68,32 +91,44 @@ export type BasePrismaPayload = {
 /**
  * A full model entry with all relations from the given Prisma type map and model name.
  *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
  * import type {Prisma} from '@prisma/client';
+ * import type {FullPrismaModel} from '@augment-vir/common';
  *
  * function doThing(fullModel: FullModel<Prisma.TypeMap, 'User'>) {}
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type FullPrismaModel<PrismaTypeMap extends BasePrismaTypeMap, Model extends ModelNameFromPrismaTypeMap<PrismaTypeMap>> = ExpandPrismaTypeMapPayload<PrismaTypeMap['model'][Model]['payload']>;
 /**
  * A base model entry with only its immediate properties from the given Prisma type map and model
  * name.
  *
+ * @category Prisma : Common
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
  * import type {Prisma} from '@prisma/client';
+ * import type {BasePrismaModel} from '@augment-vir/common';
  *
  * function doThing(fullModel: BaseModel<Prisma.TypeMap, 'User'>) {}
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type BasePrismaModel<PrismaTypeMap extends BasePrismaTypeMap, Model extends ModelNameFromPrismaTypeMap<PrismaTypeMap>> = PrismaTypeMap['model'][Model]['payload']['scalars'];
 /**
  * Expand a Prisma payload into its scalars and recursive relations.
  *
- * @category Internals
+ * @category Prisma : Common : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type ExpandPrismaTypeMapPayload<Payload extends BasePrismaPayload> = Payload['scalars'] & {
     [Key in keyof Payload['objects']]: ExpandPotentialArrayPrismaTypeMapPayload<NonNullable<Payload['objects'][Key]>> | (null extends Payload['objects'][Key] ? null : never);
@@ -101,6 +136,8 @@ export type ExpandPrismaTypeMapPayload<Payload extends BasePrismaPayload> = Payl
 /**
  * Expand a payload that might be inside of an array, keeping it inside of an array if it is.
  *
- * @category Internals
+ * @category Prisma : Common : Util
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export type ExpandPotentialArrayPrismaTypeMapPayload<PayloadWrapper extends BasePrismaPayload | BasePrismaPayload[]> = PayloadWrapper extends (infer ActualPayload extends BasePrismaPayload)[] ? ExpandPrismaTypeMapPayload<ActualPayload>[] : PayloadWrapper extends BasePrismaPayload ? ExpandPrismaTypeMapPayload<PayloadWrapper> : never;

package/dist/augments/promise/timed-promise.d.ts

@@ -1,7 +1,22 @@
 import { AnyDuration } from '@date-vir/duration';
+/**
+ * An error thrown by {@link wrapPromiseInTimeout} when the timeout is reached.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare class PromiseTimeoutError extends Error {
     readonly duration: AnyDuration;
     readonly name = "PromiseTimeoutError";
     constructor(duration: AnyDuration, failureMessage?: string | undefined);
 }
+/**
+ * Wraps an already-created Promise in a timeout, causing a rejection if the original Promise isn't
+ * resolved by then.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export declare function wrapPromiseInTimeout<T>(duration: Readonly<AnyDuration>, originalPromise: PromiseLike<T>, failureMessage?: string | undefined): Promise<T>;

package/dist/augments/promise/timed-promise.js

@@ -1,6 +1,13 @@
 import { check } from '@augment-vir/assert';
 import { ensureError } from '@augment-vir/core';
 import { convertDuration, DurationUnit } from '@date-vir/duration';
+/**
+ * An error thrown by {@link wrapPromiseInTimeout} when the timeout is reached.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export class PromiseTimeoutError extends Error {
     duration;
     name = 'PromiseTimeoutError';
@@ -14,6 +21,14 @@ export class PromiseTimeoutError extends Error {
         this.duration = duration;
     }
 }
+/**
+ * Wraps an already-created Promise in a timeout, causing a rejection if the original Promise isn't
+ * resolved by then.
+ *
+ * @category Promise
+ * @category Package : @augment-vir/common
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
+ */
 export function wrapPromiseInTimeout(duration, originalPromise, failureMessage) {
     const milliseconds = convertDuration(duration, DurationUnit.Milliseconds).milliseconds;
     return new Promise(async (resolve, reject) => {

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

@@ -6,13 +6,19 @@
  *
  * This function uses cryptographically secure randomness.
  *
+ * @category Random
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
+ * import {randomBoolean} from '@augment-vir/common';
+ *
  * randomBoolean(50); // 50% chance to return true
  * randomBoolean(0); // always false, 0% chance of being true
  * randomBoolean(100); // always true, 100% chance of being true
  * randomBoolean(59.67); // 59% chance of being true
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export declare function randomBoolean(percentLikelyToBeTrue?: number): boolean;

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

@@ -8,14 +8,20 @@ import { randomInteger } from './random-integer.js';
  *
  * This function uses cryptographically secure randomness.
  *
+ * @category Random
+ * @category Package : @augment-vir/common
  * @example
  *
  * ```ts
+ * import {randomBoolean} from '@augment-vir/common';
+ *
  * randomBoolean(50); // 50% chance to return true
  * randomBoolean(0); // always false, 0% chance of being true
  * randomBoolean(100); // always true, 100% chance of being true
  * randomBoolean(59.67); // 59% chance of being true
  * ```
+ *
+ * @package [`@augment-vir/common`](https://www.npmjs.com/package/@augment-vir/common)
  */
 export function randomBoolean(percentLikelyToBeTrue = 50) {
     return (randomInteger({ min: 0, max: 99 }) <

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 `\$&`);
 }