complete-common 2.16.0 → 2.17.0

package/dist/functions/array.d.cts

@@ -153,6 +153,17 @@ export declare function isArrayString(variable: unknown): variable is string[];
  * (This is an abstraction around `Promise.all`.)
  */
 export declare function mapAsync<T, U>(array: readonly T[], callback: (element: T, index: number, array: readonly T[]) => Promise<U>): Promise<readonly U[]>;
+/**
+ * Helper function to perform an asynchronous map. This is the same thing as the `mapAsync`
+ * function, but allows for limiting the number of array elements that should be worked on at a
+ * time. This is useful to prevent the system from running out of memory in situations with large
+ * arrays and/or expensive functions.
+ *
+ * @param array The array to map.
+ * @param limit The maximum number of concurrent executions that should happen at once.
+ * @param callback The map function.
+ */
+export declare function mapAsyncLimit<T, U>(array: readonly T[], limit: number, callback: (item: T) => Promise<U>): Promise<readonly U[]>;
 /** Initializes an array with all elements containing the specified default value. */
 export declare function newArray<T>(length: number, value: T): readonly T[];
 /** Helper function to sum every value in an array together. */

package/dist/functions/array.d.mts

@@ -153,6 +153,17 @@ export declare function isArrayString(variable: unknown): variable is string[];
  * (This is an abstraction around `Promise.all`.)
  */
 export declare function mapAsync<T, U>(array: readonly T[], callback: (element: T, index: number, array: readonly T[]) => Promise<U>): Promise<readonly U[]>;
+/**
+ * Helper function to perform an asynchronous map. This is the same thing as the `mapAsync`
+ * function, but allows for limiting the number of array elements that should be worked on at a
+ * time. This is useful to prevent the system from running out of memory in situations with large
+ * arrays and/or expensive functions.
+ *
+ * @param array The array to map.
+ * @param limit The maximum number of concurrent executions that should happen at once.
+ * @param callback The map function.
+ */
+export declare function mapAsyncLimit<T, U>(array: readonly T[], limit: number, callback: (item: T) => Promise<U>): Promise<readonly U[]>;
 /** Initializes an array with all elements containing the specified default value. */
 export declare function newArray<T>(length: number, value: T): readonly T[];
 /** Helper function to sum every value in an array together. */

package/dist/functions/array.d.ts

@@ -153,6 +153,17 @@ export declare function isArrayString(variable: unknown): variable is string[];
  * (This is an abstraction around `Promise.all`.)
  */
 export declare function mapAsync<T, U>(array: readonly T[], callback: (element: T, index: number, array: readonly T[]) => Promise<U>): Promise<readonly U[]>;
+/**
+ * Helper function to perform an asynchronous map. This is the same thing as the `mapAsync`
+ * function, but allows for limiting the number of array elements that should be worked on at a
+ * time. This is useful to prevent the system from running out of memory in situations with large
+ * arrays and/or expensive functions.
+ *
+ * @param array The array to map.
+ * @param limit The maximum number of concurrent executions that should happen at once.
+ * @param callback The map function.
+ */
+export declare function mapAsyncLimit<T, U>(array: readonly T[], limit: number, callback: (item: T) => Promise<U>): Promise<readonly U[]>;
 /** Initializes an array with all elements containing the specified default value. */
 export declare function newArray<T>(length: number, value: T): readonly T[];
 /** Helper function to sum every value in an array together. */

package/dist/functions/array.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/functions/array.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/functions/array.ts"],"names":[],"mappings":"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"}

package/dist/functions/assert.d.cts

@@ -5,29 +5,41 @@
  */
 import type { TranspiledEnum } from "../types/TranspiledEnum.js";
 /** Helper function to throw an error if the provided value is not an array. */
-export declare function assertArray(value: unknown, msg: string): asserts value is unknown[];
+export declare function assertArray<T>(value: T, ...[msg]: [T] extends [readonly unknown[]] ? [
+    "The assertion is useless because the provided value is already an array."
+] : [string]): asserts value is T & unknown[];
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * a boolean.
  */
-export declare function assertArrayBoolean(value: unknown, msg: string): asserts value is boolean[];
+export declare function assertArrayBoolean<T>(value: T, ...[msg]: [T] extends [readonly boolean[]] ? [
+    "The assertion is useless because the provided value is already a boolean array."
+] : [string]): asserts value is T & boolean[];
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * a number.
  */
-export declare function assertArrayNumber(value: unknown, msg: string): asserts value is number[];
+export declare function assertArrayNumber<T>(value: T, ...[msg]: [T] extends [readonly number[]] ? [
+    "The assertion is useless because the provided value is already a number array."
+] : [string]): asserts value is T & number[];
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * an object (i.e. a TypeScript record).
  */
-export declare function assertArrayObject(value: unknown, msg: string): asserts value is Array<Record<string, unknown>>;
+export declare function assertArrayObject<T>(value: T, ...[msg]: [T] extends [ReadonlyArray<Record<string, unknown>>] ? [
+    "The assertion is useless because the provided value is already an object array."
+] : [string]): asserts value is T & Array<Record<string, unknown>>;
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * a string.
  */
-export declare function assertArrayString(value: unknown, msg: string): asserts value is string[];
+export declare function assertArrayString<T>(value: T, ...[msg]: [T] extends [readonly string[]] ? [
+    "The assertion is useless because the provided value is already a string array."
+] : [string]): asserts value is T & string[];
 /** Helper function to throw an error if the provided value is not a boolean. */
-export declare function assertBoolean(value: unknown, msg: string): asserts value is boolean;
+export declare function assertBoolean<T>(value: T, ...[msg]: [T] extends [boolean] ? [
+    "The assertion is useless because the provided value is already a boolean."
+] : [string]): asserts value is T & boolean;
 /**
  * Helper function to throw an error if the provided value is equal to `undefined`.
  *
@@ -64,7 +76,9 @@ export declare function assertNotNull<T>(value: T, ...[msg]: [null] extends [T]
     "The assertion is useless because the provided value does not contain null."
 ]): asserts value is Exclude<T, null>;
 /** Helper function to throw an error if the provided value is not a number. */
-export declare function assertNumber(value: unknown, msg: string): asserts value is number;
+export declare function assertNumber<T>(value: T, ...[msg]: [T] extends [number] ? [
+    "The assertion is useless because the provided value is already a number."
+] : [string]): asserts value is T & number;
 /**
  * Helper function to throw an error if the provided value is not an object (i.e. a TypeScript
  * record).
@@ -74,9 +88,13 @@ export declare function assertNumber(value: unknown, msg: string): asserts value
  *
  * Under the hood, this function uses the `isObject` helper function.
  */
-export declare function assertObject(value: unknown, msg: string): asserts value is Record<string, unknown>;
+export declare function assertObject<T>(value: T, ...[msg]: [T] extends [Record<string, unknown>] ? [
+    "The assertion is useless because the provided value is already an object."
+] : [string]): asserts value is T & Record<string, unknown>;
 /** Helper function to throw an error if the provided value is not a string. */
-export declare function assertString(value: unknown, msg: string): asserts value is string;
+export declare function assertString<T>(value: T, ...[msg]: [T] extends [string] ? [
+    "The assertion is useless because the provided value is already a string."
+] : [string]): asserts value is T & string;
 /** Helper function to throw an error if the provided value is not a string or an empty string. */
 export declare function assertStringNotEmpty(value: unknown, msg: string): asserts value is string;
 //# sourceMappingURL=assert.d.ts.map

package/dist/functions/assert.d.mts

@@ -5,29 +5,41 @@
  */
 import type { TranspiledEnum } from "../types/TranspiledEnum.js";
 /** Helper function to throw an error if the provided value is not an array. */
-export declare function assertArray(value: unknown, msg: string): asserts value is unknown[];
+export declare function assertArray<T>(value: T, ...[msg]: [T] extends [readonly unknown[]] ? [
+    "The assertion is useless because the provided value is already an array."
+] : [string]): asserts value is T & unknown[];
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * a boolean.
  */
-export declare function assertArrayBoolean(value: unknown, msg: string): asserts value is boolean[];
+export declare function assertArrayBoolean<T>(value: T, ...[msg]: [T] extends [readonly boolean[]] ? [
+    "The assertion is useless because the provided value is already a boolean array."
+] : [string]): asserts value is T & boolean[];
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * a number.
  */
-export declare function assertArrayNumber(value: unknown, msg: string): asserts value is number[];
+export declare function assertArrayNumber<T>(value: T, ...[msg]: [T] extends [readonly number[]] ? [
+    "The assertion is useless because the provided value is already a number array."
+] : [string]): asserts value is T & number[];
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * an object (i.e. a TypeScript record).
  */
-export declare function assertArrayObject(value: unknown, msg: string): asserts value is Array<Record<string, unknown>>;
+export declare function assertArrayObject<T>(value: T, ...[msg]: [T] extends [ReadonlyArray<Record<string, unknown>>] ? [
+    "The assertion is useless because the provided value is already an object array."
+] : [string]): asserts value is T & Array<Record<string, unknown>>;
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * a string.
  */
-export declare function assertArrayString(value: unknown, msg: string): asserts value is string[];
+export declare function assertArrayString<T>(value: T, ...[msg]: [T] extends [readonly string[]] ? [
+    "The assertion is useless because the provided value is already a string array."
+] : [string]): asserts value is T & string[];
 /** Helper function to throw an error if the provided value is not a boolean. */
-export declare function assertBoolean(value: unknown, msg: string): asserts value is boolean;
+export declare function assertBoolean<T>(value: T, ...[msg]: [T] extends [boolean] ? [
+    "The assertion is useless because the provided value is already a boolean."
+] : [string]): asserts value is T & boolean;
 /**
  * Helper function to throw an error if the provided value is equal to `undefined`.
  *
@@ -64,7 +76,9 @@ export declare function assertNotNull<T>(value: T, ...[msg]: [null] extends [T]
     "The assertion is useless because the provided value does not contain null."
 ]): asserts value is Exclude<T, null>;
 /** Helper function to throw an error if the provided value is not a number. */
-export declare function assertNumber(value: unknown, msg: string): asserts value is number;
+export declare function assertNumber<T>(value: T, ...[msg]: [T] extends [number] ? [
+    "The assertion is useless because the provided value is already a number."
+] : [string]): asserts value is T & number;
 /**
  * Helper function to throw an error if the provided value is not an object (i.e. a TypeScript
  * record).
@@ -74,9 +88,13 @@ export declare function assertNumber(value: unknown, msg: string): asserts value
  *
  * Under the hood, this function uses the `isObject` helper function.
  */
-export declare function assertObject(value: unknown, msg: string): asserts value is Record<string, unknown>;
+export declare function assertObject<T>(value: T, ...[msg]: [T] extends [Record<string, unknown>] ? [
+    "The assertion is useless because the provided value is already an object."
+] : [string]): asserts value is T & Record<string, unknown>;
 /** Helper function to throw an error if the provided value is not a string. */
-export declare function assertString(value: unknown, msg: string): asserts value is string;
+export declare function assertString<T>(value: T, ...[msg]: [T] extends [string] ? [
+    "The assertion is useless because the provided value is already a string."
+] : [string]): asserts value is T & string;
 /** Helper function to throw an error if the provided value is not a string or an empty string. */
 export declare function assertStringNotEmpty(value: unknown, msg: string): asserts value is string;
 //# sourceMappingURL=assert.d.ts.map

package/dist/functions/assert.d.ts

@@ -5,29 +5,41 @@
  */
 import type { TranspiledEnum } from "../types/TranspiledEnum.js";
 /** Helper function to throw an error if the provided value is not an array. */
-export declare function assertArray(value: unknown, msg: string): asserts value is unknown[];
+export declare function assertArray<T>(value: T, ...[msg]: [T] extends [readonly unknown[]] ? [
+    "The assertion is useless because the provided value is already an array."
+] : [string]): asserts value is T & unknown[];
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * a boolean.
  */
-export declare function assertArrayBoolean(value: unknown, msg: string): asserts value is boolean[];
+export declare function assertArrayBoolean<T>(value: T, ...[msg]: [T] extends [readonly boolean[]] ? [
+    "The assertion is useless because the provided value is already a boolean array."
+] : [string]): asserts value is T & boolean[];
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * a number.
  */
-export declare function assertArrayNumber(value: unknown, msg: string): asserts value is number[];
+export declare function assertArrayNumber<T>(value: T, ...[msg]: [T] extends [readonly number[]] ? [
+    "The assertion is useless because the provided value is already a number array."
+] : [string]): asserts value is T & number[];
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * an object (i.e. a TypeScript record).
  */
-export declare function assertArrayObject(value: unknown, msg: string): asserts value is Array<Record<string, unknown>>;
+export declare function assertArrayObject<T>(value: T, ...[msg]: [T] extends [ReadonlyArray<Record<string, unknown>>] ? [
+    "The assertion is useless because the provided value is already an object array."
+] : [string]): asserts value is T & Array<Record<string, unknown>>;
 /**
  * Helper function to throw an error if the provided value is not an array with every element being
  * a string.
  */
-export declare function assertArrayString(value: unknown, msg: string): asserts value is string[];
+export declare function assertArrayString<T>(value: T, ...[msg]: [T] extends [readonly string[]] ? [
+    "The assertion is useless because the provided value is already a string array."
+] : [string]): asserts value is T & string[];
 /** Helper function to throw an error if the provided value is not a boolean. */
-export declare function assertBoolean(value: unknown, msg: string): asserts value is boolean;
+export declare function assertBoolean<T>(value: T, ...[msg]: [T] extends [boolean] ? [
+    "The assertion is useless because the provided value is already a boolean."
+] : [string]): asserts value is T & boolean;
 /**
  * Helper function to throw an error if the provided value is equal to `undefined`.
  *
@@ -64,7 +76,9 @@ export declare function assertNotNull<T>(value: T, ...[msg]: [null] extends [T]
     "The assertion is useless because the provided value does not contain null."
 ]): asserts value is Exclude<T, null>;
 /** Helper function to throw an error if the provided value is not a number. */
-export declare function assertNumber(value: unknown, msg: string): asserts value is number;
+export declare function assertNumber<T>(value: T, ...[msg]: [T] extends [number] ? [
+    "The assertion is useless because the provided value is already a number."
+] : [string]): asserts value is T & number;
 /**
  * Helper function to throw an error if the provided value is not an object (i.e. a TypeScript
  * record).
@@ -74,9 +88,13 @@ export declare function assertNumber(value: unknown, msg: string): asserts value
  *
  * Under the hood, this function uses the `isObject` helper function.
  */
-export declare function assertObject(value: unknown, msg: string): asserts value is Record<string, unknown>;
+export declare function assertObject<T>(value: T, ...[msg]: [T] extends [Record<string, unknown>] ? [
+    "The assertion is useless because the provided value is already an object."
+] : [string]): asserts value is T & Record<string, unknown>;
 /** Helper function to throw an error if the provided value is not a string. */
-export declare function assertString(value: unknown, msg: string): asserts value is string;
+export declare function assertString<T>(value: T, ...[msg]: [T] extends [string] ? [
+    "The assertion is useless because the provided value is already a string."
+] : [string]): asserts value is T & string;
 /** Helper function to throw an error if the provided value is not a string or an empty string. */
 export declare function assertStringNotEmpty(value: unknown, msg: string): asserts value is string;
 //# sourceMappingURL=assert.d.ts.map

package/dist/functions/assert.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/functions/assert.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"assert.d.ts","sourceRoot":"","sources":["../../src/functions/assert.ts"],"names":[],"mappings":"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"}

package/dist/functions/string.d.cts

@@ -87,7 +87,7 @@ export declare function parseSemanticVersion(versionString: string): {
  *
  * For example, by using a marker of "@foo":
  *
- * ```text
+ * ```txt
  * line1
  * # @foo-start
  * line2
@@ -98,7 +98,7 @@ export declare function parseSemanticVersion(versionString: string): {
  *
  * Would return:
  *
- * ```text
+ * ```txt
  * line1
  * line4
  * ```

package/dist/functions/string.d.mts

@@ -87,7 +87,7 @@ export declare function parseSemanticVersion(versionString: string): {
  *
  * For example, by using a marker of "@foo":
  *
- * ```text
+ * ```txt
  * line1
  * # @foo-start
  * line2
@@ -98,7 +98,7 @@ export declare function parseSemanticVersion(versionString: string): {
  *
  * Would return:
  *
- * ```text
+ * ```txt
  * line1
  * line4
  * ```

package/dist/functions/string.d.ts

@@ -87,7 +87,7 @@ export declare function parseSemanticVersion(versionString: string): {
  *
  * For example, by using a marker of "@foo":
  *
- * ```text
+ * ```txt
  * line1
  * # @foo-start
  * line2
@@ -98,7 +98,7 @@ export declare function parseSemanticVersion(versionString: string): {
  *
  * Would return:
  *
- * ```text
+ * ```txt
  * line1
  * line4
  * ```

package/dist/functions/string.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../src/functions/string.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA0BH,kEAAkE;AAClE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAU5D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAqBlE;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOpD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,+EAA+E;AAC/E,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE5C;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiBtD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GACtD;IACE,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IAErB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IAErB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;CACtB,GACD,SAAS,CAwBZ;AAGD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,MAAM,CAuBR;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIzE;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAK3D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,UAAQ,GACd,MAAM,CAWR;AAED,gGAAgG;AAChG,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAMxE"}
+{"version":3,"file":"string.d.ts","sourceRoot":"","sources":["../../src/functions/string.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA8BH,kEAAkE;AAClE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAU5D;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAqBlE;AAED,6EAA6E;AAC7E,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAOpD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEhD;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAErD;AAED,+EAA+E;AAC/E,wBAAgB,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAE5C;AAED;;;GAGG;AACH,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,OAAO,CAEhE;AAED,+FAA+F;AAC/F,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEnD;AAED,wEAAwE;AACxE,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAO3D;AAED,yEAAyE;AACzE,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAG5D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAiBtD;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GACtD;IACE,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IAErB,wDAAwD;IACxD,YAAY,EAAE,MAAM,CAAC;IAErB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;CACtB,GACD,SAAS,CAwBZ;AAGD;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,GACb,MAAM,CAuBR;AAED,gGAAgG;AAChG,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAIzE;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED,yEAAyE;AACzE,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,qFAAqF;AACrF,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAK3D;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,OAAO,UAAQ,GACd,MAAM,CAWR;AAED,gGAAgG;AAChG,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAOjE;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,CAMxE"}

package/dist/index.cjs

@@ -36,36 +36,44 @@ function isObject(variable) {
   return typeof variable === "object" && variable !== null && !Array.isArray(variable);
 }
 
-function assertArray(value, msg) {
+function assertArray(value, ...[msg]) {
   if (!Array.isArray(value)) {
     throw new TypeError(msg);
   }
 }
-function assertArrayBoolean(value, msg) {
-  assertArray(value, msg);
+function assertArrayBoolean(value, ...[msg]) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
   if (value.some((element) => typeof element !== "boolean")) {
     throw new TypeError(msg);
   }
 }
-function assertArrayNumber(value, msg) {
-  assertArray(value, msg);
+function assertArrayNumber(value, ...[msg]) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
   if (value.some((element) => typeof element !== "number")) {
     throw new TypeError(msg);
   }
 }
-function assertArrayObject(value, msg) {
-  assertArray(value, msg);
+function assertArrayObject(value, ...[msg]) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
   if (value.some((element) => !isObject(element))) {
     throw new TypeError(msg);
   }
 }
-function assertArrayString(value, msg) {
-  assertArray(value, msg);
+function assertArrayString(value, ...[msg]) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
   if (value.some((element) => typeof element !== "string")) {
     throw new TypeError(msg);
   }
 }
-function assertBoolean(value, msg) {
+function assertBoolean(value, ...[msg]) {
   if (typeof value !== "boolean") {
     throw new TypeError(msg);
   }
@@ -95,17 +103,17 @@ function assertNotNull(value, ...[msg]) {
     throw new TypeError(msg);
   }
 }
-function assertNumber(value, msg) {
+function assertNumber(value, ...[msg]) {
   if (typeof value !== "number") {
     throw new TypeError(msg);
   }
 }
-function assertObject(value, msg) {
+function assertObject(value, ...[msg]) {
   if (!isObject(value)) {
     throw new TypeError(msg);
   }
 }
-function assertString(value, msg) {
+function assertString(value, ...[msg]) {
   if (typeof value !== "string") {
     throw new TypeError(msg);
   }
@@ -268,6 +276,30 @@ async function mapAsync(array, callback) {
   );
   return await Promise.all(promises);
 }
+async function mapAsyncLimit(array, limit, callback) {
+  if (limit < 1) {
+    throw new RangeError("The limit argument must be at least 1.");
+  }
+  const results = [];
+  let currentIndex = 0;
+  let hasFailed = false;
+  async function worker() {
+    while (currentIndex < array.length && !hasFailed) {
+      const index = currentIndex;
+      currentIndex++;
+      try {
+        results[index] = await callback(array[index]);
+      } catch (error) {
+        hasFailed = true;
+        throw error;
+      }
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(limit, array.length) }, worker)
+  );
+  return results;
+}
 function newArray(length, value) {
   return Array.from({ length }, () => value);
 }
@@ -449,7 +481,8 @@ const EMOJI_REGEX = /(\p{Extended_Pictographic}|[#*0-9]\uFE0F?\u20E3)/u;
 const FIRST_LETTER_CAPITALIZED_REGEX = /^\p{Lu}/u;
 const KEBAB_CASE_REGEX = /^[\da-z]+(?:-[\da-z]+)*$/;
 const SEMANTIC_VERSION_REGEX = /^v*(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)/;
-const WHITESPACE_REGEX = /\s/g;
+const WHITESPACE_REGEX = /\s/;
+const WHITESPACE_GLOBAL_REGEX = /\s/g;
 const TITLE_CASE_BOUNDARY_REGEX = /(?<=[\da-z])(?=[A-Z])/g;
 const UPPERCASE_REGEX = /^[A-Z]*$/;
 const LOWERCASE_REGEX = /^[a-z]*$/;
@@ -574,7 +607,7 @@ function removeNonPrintableCharacters(string) {
   return string.replaceAll(/\p{C}/gu, "");
 }
 function removeWhitespace(string) {
-  return string.replaceAll(WHITESPACE_REGEX, "");
+  return string.replaceAll(WHITESPACE_GLOBAL_REGEX, "");
 }
 function titleCaseToKebabCase(string) {
   return string.replaceAll(TITLE_CASE_BOUNDARY_REGEX, "-").replaceAll(/ +/g, "-").toLowerCase();
@@ -686,6 +719,7 @@ exports.isUpperCase = isUpperCase;
 exports.kebabCaseToCamelCase = kebabCaseToCamelCase;
 exports.kebabCaseToPascalCase = kebabCaseToPascalCase;
 exports.mapAsync = mapAsync;
+exports.mapAsyncLimit = mapAsyncLimit;
 exports.mapFilter = mapFilter;
 exports.mapFind = mapFind;
 exports.newArray = newArray;

package/dist/index.mjs

@@ -34,36 +34,44 @@ function isObject(variable) {
   return typeof variable === "object" && variable !== null && !Array.isArray(variable);
 }
 
-function assertArray(value, msg) {
+function assertArray(value, ...[msg]) {
   if (!Array.isArray(value)) {
     throw new TypeError(msg);
   }
 }
-function assertArrayBoolean(value, msg) {
-  assertArray(value, msg);
+function assertArrayBoolean(value, ...[msg]) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
   if (value.some((element) => typeof element !== "boolean")) {
     throw new TypeError(msg);
   }
 }
-function assertArrayNumber(value, msg) {
-  assertArray(value, msg);
+function assertArrayNumber(value, ...[msg]) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
   if (value.some((element) => typeof element !== "number")) {
     throw new TypeError(msg);
   }
 }
-function assertArrayObject(value, msg) {
-  assertArray(value, msg);
+function assertArrayObject(value, ...[msg]) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
   if (value.some((element) => !isObject(element))) {
     throw new TypeError(msg);
   }
 }
-function assertArrayString(value, msg) {
-  assertArray(value, msg);
+function assertArrayString(value, ...[msg]) {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
   if (value.some((element) => typeof element !== "string")) {
     throw new TypeError(msg);
   }
 }
-function assertBoolean(value, msg) {
+function assertBoolean(value, ...[msg]) {
   if (typeof value !== "boolean") {
     throw new TypeError(msg);
   }
@@ -93,17 +101,17 @@ function assertNotNull(value, ...[msg]) {
     throw new TypeError(msg);
   }
 }
-function assertNumber(value, msg) {
+function assertNumber(value, ...[msg]) {
   if (typeof value !== "number") {
     throw new TypeError(msg);
   }
 }
-function assertObject(value, msg) {
+function assertObject(value, ...[msg]) {
   if (!isObject(value)) {
     throw new TypeError(msg);
   }
 }
-function assertString(value, msg) {
+function assertString(value, ...[msg]) {
   if (typeof value !== "string") {
     throw new TypeError(msg);
   }
@@ -266,6 +274,30 @@ async function mapAsync(array, callback) {
   );
   return await Promise.all(promises);
 }
+async function mapAsyncLimit(array, limit, callback) {
+  if (limit < 1) {
+    throw new RangeError("The limit argument must be at least 1.");
+  }
+  const results = [];
+  let currentIndex = 0;
+  let hasFailed = false;
+  async function worker() {
+    while (currentIndex < array.length && !hasFailed) {
+      const index = currentIndex;
+      currentIndex++;
+      try {
+        results[index] = await callback(array[index]);
+      } catch (error) {
+        hasFailed = true;
+        throw error;
+      }
+    }
+  }
+  await Promise.all(
+    Array.from({ length: Math.min(limit, array.length) }, worker)
+  );
+  return results;
+}
 function newArray(length, value) {
   return Array.from({ length }, () => value);
 }
@@ -447,7 +479,8 @@ const EMOJI_REGEX = /(\p{Extended_Pictographic}|[#*0-9]\uFE0F?\u20E3)/u;
 const FIRST_LETTER_CAPITALIZED_REGEX = /^\p{Lu}/u;
 const KEBAB_CASE_REGEX = /^[\da-z]+(?:-[\da-z]+)*$/;
 const SEMANTIC_VERSION_REGEX = /^v*(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)/;
-const WHITESPACE_REGEX = /\s/g;
+const WHITESPACE_REGEX = /\s/;
+const WHITESPACE_GLOBAL_REGEX = /\s/g;
 const TITLE_CASE_BOUNDARY_REGEX = /(?<=[\da-z])(?=[A-Z])/g;
 const UPPERCASE_REGEX = /^[A-Z]*$/;
 const LOWERCASE_REGEX = /^[a-z]*$/;
@@ -572,7 +605,7 @@ function removeNonPrintableCharacters(string) {
   return string.replaceAll(/\p{C}/gu, "");
 }
 function removeWhitespace(string) {
-  return string.replaceAll(WHITESPACE_REGEX, "");
+  return string.replaceAll(WHITESPACE_GLOBAL_REGEX, "");
 }
 function titleCaseToKebabCase(string) {
   return string.replaceAll(TITLE_CASE_BOUNDARY_REGEX, "-").replaceAll(/ +/g, "-").toLowerCase();
@@ -617,4 +650,4 @@ function* tupleKeys(tuple) {
 
 const ReadonlyMap = Map;
 
-export { HOUR_IN_MILLISECONDS, MINUTE_IN_MILLISECONDS, ReadonlyMap, ReadonlySet, SECOND_IN_MILLISECONDS, addSetsToSet, arrayCopyTwoDimensional, arrayEquals, arrayRemove, arrayRemoveAllInPlace, arrayRemoveInPlace, assertArray, assertArrayBoolean, assertArrayNumber, assertArrayObject, assertArrayString, assertBoolean, assertDefined, assertEnumValue, assertInteger, assertIs, assertNotNull, assertNumber, assertObject, assertString, assertStringNotEmpty, capitalizeFirstLetter, clamp, combineSets, copySet, eRange, emptyArray, escapeHTMLCharacters, filterAsync, filterMap, filterMapAsync, getElapsedSeconds, getEnumEntries, getEnumKeys, getEnumValues, getNumConsecutiveDiacritics, getRandomArrayElement, getRandomArrayIndex, getRandomInt, hasDiacritic, hasEmoji, hasWhitespace, iRange, includes, includesAny, interfaceSatisfiesEnum, isASCII, isArray, isArrayBoolean, isArrayNumber, isArrayString, isEnumValue, isFirstLetterCapitalized, isKebabCase, isKeyOf, isLowerCase, isObject, isSemanticVersion, isUpperCase, kebabCaseToCamelCase, kebabCaseToPascalCase, mapAsync, mapFilter, mapFind, newArray, noop, normalizeString, objectFilter, objectKeysToSet, objectMap, objectToMap, objectToReverseMap, objectValuesToSet, parseFloatSafe, parseIntSafe, parseSemanticVersion, removeLinesBetweenMarkers, removeLinesMatching, removeNonPrintableCharacters, removeWhitespace, repeat, setAdd, setHas, sortCaseInsensitive, sumArray, titleCaseToKebabCase, todo, trimPrefix, trimSuffix, truncateString, tupleEntries, tupleKeys };
+export { HOUR_IN_MILLISECONDS, MINUTE_IN_MILLISECONDS, ReadonlyMap, ReadonlySet, SECOND_IN_MILLISECONDS, addSetsToSet, arrayCopyTwoDimensional, arrayEquals, arrayRemove, arrayRemoveAllInPlace, arrayRemoveInPlace, assertArray, assertArrayBoolean, assertArrayNumber, assertArrayObject, assertArrayString, assertBoolean, assertDefined, assertEnumValue, assertInteger, assertIs, assertNotNull, assertNumber, assertObject, assertString, assertStringNotEmpty, capitalizeFirstLetter, clamp, combineSets, copySet, eRange, emptyArray, escapeHTMLCharacters, filterAsync, filterMap, filterMapAsync, getElapsedSeconds, getEnumEntries, getEnumKeys, getEnumValues, getNumConsecutiveDiacritics, getRandomArrayElement, getRandomArrayIndex, getRandomInt, hasDiacritic, hasEmoji, hasWhitespace, iRange, includes, includesAny, interfaceSatisfiesEnum, isASCII, isArray, isArrayBoolean, isArrayNumber, isArrayString, isEnumValue, isFirstLetterCapitalized, isKebabCase, isKeyOf, isLowerCase, isObject, isSemanticVersion, isUpperCase, kebabCaseToCamelCase, kebabCaseToPascalCase, mapAsync, mapAsyncLimit, mapFilter, mapFind, newArray, noop, normalizeString, objectFilter, objectKeysToSet, objectMap, objectToMap, objectToReverseMap, objectValuesToSet, parseFloatSafe, parseIntSafe, parseSemanticVersion, removeLinesBetweenMarkers, removeLinesMatching, removeNonPrintableCharacters, removeWhitespace, repeat, setAdd, setHas, sortCaseInsensitive, sumArray, titleCaseToKebabCase, todo, trimPrefix, trimSuffix, truncateString, tupleEntries, tupleKeys };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "complete-common",
-  "version": "2.16.0",
+  "version": "2.17.0",
   "description": "Helper functions for TypeScript projects.",
   "homepage": "https://complete-ts.github.io/",
   "bugs": {

package/src/functions/array.ts

@@ -360,6 +360,51 @@ export async function mapAsync<T, U>(
   return await Promise.all(promises);
 }
 
+/**
+ * Helper function to perform an asynchronous map. This is the same thing as the `mapAsync`
+ * function, but allows for limiting the number of array elements that should be worked on at a
+ * time. This is useful to prevent the system from running out of memory in situations with large
+ * arrays and/or expensive functions.
+ *
+ * @param array The array to map.
+ * @param limit The maximum number of concurrent executions that should happen at once.
+ * @param callback The map function.
+ */
+export async function mapAsyncLimit<T, U>(
+  array: readonly T[],
+  limit: number,
+  callback: (item: T) => Promise<U>,
+): Promise<readonly U[]> {
+  if (limit < 1) {
+    throw new RangeError("The limit argument must be at least 1.");
+  }
+
+  const results: U[] = [];
+  let currentIndex = 0;
+  let hasFailed = false;
+
+  async function worker() {
+    // Stop processing if the queue is empty or if another worker failed.
+    while (currentIndex < array.length && !hasFailed) {
+      const index = currentIndex;
+      currentIndex++;
+      try {
+        // eslint-disable-next-line no-await-in-loop, @typescript-eslint/no-non-null-assertion
+        results[index] = await callback(array[index]!);
+      } catch (error) {
+        hasFailed = true; // Signal other workers to stop taking new items.
+        throw error; // Bubble the error up to Promise.all.
+      }
+    }
+  }
+
+  await Promise.all(
+    Array.from({ length: Math.min(limit, array.length) }, worker),
+  );
+
+  return results;
+}
+
 /** Initializes an array with all elements containing the specified default value. */
 export function newArray<T>(length: number, value: T): readonly T[] {
   return Array.from({ length }, () => value);

package/src/functions/assert.ts

@@ -9,10 +9,14 @@ import { isEnumValue } from "./enums.js";
 import { isObject } from "./types.js";
 
 /** Helper function to throw an error if the provided value is not an array. */
-export function assertArray(
-  value: unknown,
-  msg: string,
-): asserts value is unknown[] {
+export function assertArray<T>(
+  value: T,
+  ...[msg]: [T] extends [readonly unknown[]]
+    ? [
+        "The assertion is useless because the provided value is already an array.",
+      ]
+    : [string]
+): asserts value is T & unknown[] {
   if (!Array.isArray(value)) {
     throw new TypeError(msg);
   }
@@ -22,13 +26,19 @@ export function assertArray(
  * Helper function to throw an error if the provided value is not an array with every element being
  * a boolean.
  */
-export function assertArrayBoolean(
-  value: unknown,
-  msg: string,
-): asserts value is boolean[] {
-  assertArray(value, msg);
+export function assertArrayBoolean<T>(
+  value: T,
+  ...[msg]: [T] extends [readonly boolean[]]
+    ? [
+        "The assertion is useless because the provided value is already a boolean array.",
+      ]
+    : [string]
+): asserts value is T & boolean[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
 
-  if (value.some((element) => typeof element !== "boolean")) {
+  if ((value as unknown[]).some((element) => typeof element !== "boolean")) {
     throw new TypeError(msg);
   }
 }
@@ -37,13 +47,19 @@ export function assertArrayBoolean(
  * Helper function to throw an error if the provided value is not an array with every element being
  * a number.
  */
-export function assertArrayNumber(
-  value: unknown,
-  msg: string,
-): asserts value is number[] {
-  assertArray(value, msg);
+export function assertArrayNumber<T>(
+  value: T,
+  ...[msg]: [T] extends [readonly number[]]
+    ? [
+        "The assertion is useless because the provided value is already a number array.",
+      ]
+    : [string]
+): asserts value is T & number[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
 
-  if (value.some((element) => typeof element !== "number")) {
+  if ((value as unknown[]).some((element) => typeof element !== "number")) {
     throw new TypeError(msg);
   }
 }
@@ -52,13 +68,19 @@ export function assertArrayNumber(
  * Helper function to throw an error if the provided value is not an array with every element being
  * an object (i.e. a TypeScript record).
  */
-export function assertArrayObject(
-  value: unknown,
-  msg: string,
-): asserts value is Array<Record<string, unknown>> {
-  assertArray(value, msg);
+export function assertArrayObject<T>(
+  value: T,
+  ...[msg]: [T] extends [ReadonlyArray<Record<string, unknown>>]
+    ? [
+        "The assertion is useless because the provided value is already an object array.",
+      ]
+    : [string]
+): asserts value is T & Array<Record<string, unknown>> {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
 
-  if (value.some((element) => !isObject(element))) {
+  if ((value as unknown[]).some((element) => !isObject(element))) {
     throw new TypeError(msg);
   }
 }
@@ -67,22 +89,32 @@ export function assertArrayObject(
  * Helper function to throw an error if the provided value is not an array with every element being
  * a string.
  */
-export function assertArrayString(
-  value: unknown,
-  msg: string,
-): asserts value is string[] {
-  assertArray(value, msg);
+export function assertArrayString<T>(
+  value: T,
+  ...[msg]: [T] extends [readonly string[]]
+    ? [
+        "The assertion is useless because the provided value is already a string array.",
+      ]
+    : [string]
+): asserts value is T & string[] {
+  if (!Array.isArray(value)) {
+    throw new TypeError(msg);
+  }
 
-  if (value.some((element) => typeof element !== "string")) {
+  if ((value as unknown[]).some((element) => typeof element !== "string")) {
     throw new TypeError(msg);
   }
 }
 
 /** Helper function to throw an error if the provided value is not a boolean. */
-export function assertBoolean(
-  value: unknown,
-  msg: string,
-): asserts value is boolean {
+export function assertBoolean<T>(
+  value: T,
+  ...[msg]: [T] extends [boolean]
+    ? [
+        "The assertion is useless because the provided value is already a boolean.",
+      ]
+    : [string]
+): asserts value is T & boolean {
   if (typeof value !== "boolean") {
     throw new TypeError(msg);
   }
@@ -175,10 +207,14 @@ export function assertNotNull<T>(
 }
 
 /** Helper function to throw an error if the provided value is not a number. */
-export function assertNumber(
-  value: unknown,
-  msg: string,
-): asserts value is number {
+export function assertNumber<T>(
+  value: T,
+  ...[msg]: [T] extends [number]
+    ? [
+        "The assertion is useless because the provided value is already a number.",
+      ]
+    : [string]
+): asserts value is T & number {
   if (typeof value !== "number") {
     throw new TypeError(msg);
   }
@@ -193,20 +229,28 @@ export function assertNumber(
  *
  * Under the hood, this function uses the `isObject` helper function.
  */
-export function assertObject(
-  value: unknown,
-  msg: string,
-): asserts value is Record<string, unknown> {
+export function assertObject<T>(
+  value: T,
+  ...[msg]: [T] extends [Record<string, unknown>]
+    ? [
+        "The assertion is useless because the provided value is already an object.",
+      ]
+    : [string]
+): asserts value is T & Record<string, unknown> {
   if (!isObject(value)) {
     throw new TypeError(msg);
   }
 }
 
 /** Helper function to throw an error if the provided value is not a string. */
-export function assertString(
-  value: unknown,
-  msg: string,
-): asserts value is string {
+export function assertString<T>(
+  value: T,
+  ...[msg]: [T] extends [string]
+    ? [
+        "The assertion is useless because the provided value is already a string.",
+      ]
+    : [string]
+): asserts value is T & string {
   if (typeof value !== "string") {
     throw new TypeError(msg);
   }

package/src/functions/string.test.ts

@@ -1,8 +1,11 @@
+/* eslint-disable complete/require-ascii */
+
 import { equal } from "node:assert";
 import { describe, test } from "node:test";
 import {
   hasDiacritic,
   hasEmoji,
+  isASCII,
   isKebabCase,
   titleCaseToKebabCase,
   trimPrefix,
@@ -61,6 +64,27 @@ describe("hasDiacritic", () => {
   });
 });
 
+describe("isASCII", () => {
+  test("should return true for ASCII strings", () => {
+    equal(isASCII("Hello World"), true);
+    equal(isASCII("1234567890"), true);
+    equal(isASCII("!@#$%^&*()_+"), true);
+    equal(isASCII(" \n\t\r"), true);
+  });
+
+  test("should return false for non-ASCII strings", () => {
+    equal(isASCII("Hello World 😃"), false);
+    equal(isASCII("á"), false);
+    equal(isASCII("è"), false);
+    equal(isASCII("ô"), false);
+    equal(isASCII("😊"), false);
+  });
+
+  test("should handle empty string", () => {
+    equal(isASCII(""), true);
+  });
+});
+
 describe("isKebabCase", () => {
   test("should return true for valid kebab-case strings", () => {
     equal(isKebabCase("hello-world"), true);

package/src/functions/string.ts

@@ -7,8 +7,11 @@
 import { parseIntSafe } from "./utils.js";
 
 // When regular expressions are located at the root instead of inside the function, the functions
-// are tested to perform 11% faster.
+// are tested to perform 11% faster. However, since the global flag makes a regex stateful, care has
+// to be taken to ensure that regexes used for validation do not use the global flag. Otherwise,
+// they will return inconsistent results due to the `lastIndex` property persisting between calls.
 
+/** We use a "*" instead of a "+" so that an empty string will match. */
 // eslint-disable-next-line no-control-regex
 const ASCII_REGEX = /^[\u0000-\u007F]*$/;
 
@@ -23,7 +26,8 @@ const EMOJI_REGEX = /(\p{Extended_Pictographic}|[#*0-9]\uFE0F?\u20E3)/u;
 const FIRST_LETTER_CAPITALIZED_REGEX = /^\p{Lu}/u;
 const KEBAB_CASE_REGEX = /^[\da-z]+(?:-[\da-z]+)*$/;
 const SEMANTIC_VERSION_REGEX = /^v*(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)/;
-const WHITESPACE_REGEX = /\s/g;
+const WHITESPACE_REGEX = /\s/;
+const WHITESPACE_GLOBAL_REGEX = /\s/g;
 const TITLE_CASE_BOUNDARY_REGEX = /(?<=[\da-z])(?=[A-Z])/g;
 const UPPERCASE_REGEX = /^[A-Z]*$/;
 const LOWERCASE_REGEX = /^[a-z]*$/;
@@ -245,7 +249,7 @@ export function parseSemanticVersion(versionString: string):
  *
  * For example, by using a marker of "@foo":
  *
- * ```text
+ * ```txt
  * line1
  * # @foo-start
  * line2
@@ -256,7 +260,7 @@ export function parseSemanticVersion(versionString: string):
  *
  * Would return:
  *
- * ```text
+ * ```txt
  * line1
  * line4
  * ```
@@ -309,7 +313,7 @@ export function removeNonPrintableCharacters(string: string): string {
 
 /** Helper function to remove all whitespace characters from a string. */
 export function removeWhitespace(string: string): string {
-  return string.replaceAll(WHITESPACE_REGEX, "");
+  return string.replaceAll(WHITESPACE_GLOBAL_REGEX, "");
 }
 
 /** Helper function to convert a string from TitleCase (PascalCase) to kebab-case. */