complete-common 2.11.0 → 2.13.0

package/dist/functions/array.d.cts

@@ -51,6 +51,20 @@ export declare function arrayRemoveAllInPlace<T>(array: T[], ...elementsToRemove
 export declare function arrayRemoveInPlace<T>(array: T[], ...elementsToRemove: readonly T[]): readonly T[];
 /** Helper function to remove all of the elements in an array in-place. */
 export declare function emptyArray(array: unknown[]): void;
+/**
+ * Helper function to perform an asynchronous filter. The vanilla `Array.filter` method does not
+ * wait for promises (and treats them as truthy), so this function runs the predicate on all
+ * elements concurrently, awaits the results, and then filters the original array.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const results = await filterAsync(things, async (thing) => await filterFunc(thing));
+ * ```
+ *
+ * (This is an abstraction around `Promise.all`.)
+ */
+export declare function filterAsync<T>(array: readonly T[], predicate: (element: T) => Promise<boolean>): Promise<readonly T[]>;
 /**
  * Helper function to perform a filter and a map at the same time. Similar to `Array.map`, provide a
  * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
@@ -63,6 +77,26 @@ export declare function emptyArray(array: unknown[]): void;
  * https://doc.rust-lang.org/std/iter/struct.FilterMap.html
  */
 export declare function filterMap<OldT, NewT>(array: readonly OldT[], func: (element: OldT) => NewT | undefined): readonly NewT[];
+/**
+ * Helper function to perform a filter and a map at the same time. Similar to `Array.map`, provide a
+ * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
+ * this function cannot be used in situations where `undefined` can be a valid array element.)
+ *
+ * This function is useful because the `Array.map` method will always produce an array with the same
+ * amount of elements as the original array.
+ *
+ * This is named `filterMap` after the Rust function:
+ * https://doc.rust-lang.org/std/iter/struct.FilterMap.html
+ *
+ * This is the asynchronous version, which can be used like this:
+ *
+ * ```ts
+ * const results = await asyncFilterMap(things, someFunc);
+ * ```
+ *
+ * (This is an abstraction around `Promise.all`.)
+ */
+export declare function filterMapAsync<OldT, NewT>(array: readonly OldT[], func: (element: OldT) => Promise<NewT | undefined>): Promise<readonly NewT[]>;
 /**
  * Helper function to get a random element from the provided array.
  *

package/dist/functions/array.d.mts

@@ -51,6 +51,20 @@ export declare function arrayRemoveAllInPlace<T>(array: T[], ...elementsToRemove
 export declare function arrayRemoveInPlace<T>(array: T[], ...elementsToRemove: readonly T[]): readonly T[];
 /** Helper function to remove all of the elements in an array in-place. */
 export declare function emptyArray(array: unknown[]): void;
+/**
+ * Helper function to perform an asynchronous filter. The vanilla `Array.filter` method does not
+ * wait for promises (and treats them as truthy), so this function runs the predicate on all
+ * elements concurrently, awaits the results, and then filters the original array.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const results = await filterAsync(things, async (thing) => await filterFunc(thing));
+ * ```
+ *
+ * (This is an abstraction around `Promise.all`.)
+ */
+export declare function filterAsync<T>(array: readonly T[], predicate: (element: T) => Promise<boolean>): Promise<readonly T[]>;
 /**
  * Helper function to perform a filter and a map at the same time. Similar to `Array.map`, provide a
  * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
@@ -63,6 +77,26 @@ export declare function emptyArray(array: unknown[]): void;
  * https://doc.rust-lang.org/std/iter/struct.FilterMap.html
  */
 export declare function filterMap<OldT, NewT>(array: readonly OldT[], func: (element: OldT) => NewT | undefined): readonly NewT[];
+/**
+ * Helper function to perform a filter and a map at the same time. Similar to `Array.map`, provide a
+ * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
+ * this function cannot be used in situations where `undefined` can be a valid array element.)
+ *
+ * This function is useful because the `Array.map` method will always produce an array with the same
+ * amount of elements as the original array.
+ *
+ * This is named `filterMap` after the Rust function:
+ * https://doc.rust-lang.org/std/iter/struct.FilterMap.html
+ *
+ * This is the asynchronous version, which can be used like this:
+ *
+ * ```ts
+ * const results = await asyncFilterMap(things, someFunc);
+ * ```
+ *
+ * (This is an abstraction around `Promise.all`.)
+ */
+export declare function filterMapAsync<OldT, NewT>(array: readonly OldT[], func: (element: OldT) => Promise<NewT | undefined>): Promise<readonly NewT[]>;
 /**
  * Helper function to get a random element from the provided array.
  *

package/dist/functions/array.d.ts

@@ -51,6 +51,20 @@ export declare function arrayRemoveAllInPlace<T>(array: T[], ...elementsToRemove
 export declare function arrayRemoveInPlace<T>(array: T[], ...elementsToRemove: readonly T[]): readonly T[];
 /** Helper function to remove all of the elements in an array in-place. */
 export declare function emptyArray(array: unknown[]): void;
+/**
+ * Helper function to perform an asynchronous filter. The vanilla `Array.filter` method does not
+ * wait for promises (and treats them as truthy), so this function runs the predicate on all
+ * elements concurrently, awaits the results, and then filters the original array.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const results = await filterAsync(things, async (thing) => await filterFunc(thing));
+ * ```
+ *
+ * (This is an abstraction around `Promise.all`.)
+ */
+export declare function filterAsync<T>(array: readonly T[], predicate: (element: T) => Promise<boolean>): Promise<readonly T[]>;
 /**
  * Helper function to perform a filter and a map at the same time. Similar to `Array.map`, provide a
  * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
@@ -63,6 +77,26 @@ export declare function emptyArray(array: unknown[]): void;
  * https://doc.rust-lang.org/std/iter/struct.FilterMap.html
  */
 export declare function filterMap<OldT, NewT>(array: readonly OldT[], func: (element: OldT) => NewT | undefined): readonly NewT[];
+/**
+ * Helper function to perform a filter and a map at the same time. Similar to `Array.map`, provide a
+ * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
+ * this function cannot be used in situations where `undefined` can be a valid array element.)
+ *
+ * This function is useful because the `Array.map` method will always produce an array with the same
+ * amount of elements as the original array.
+ *
+ * This is named `filterMap` after the Rust function:
+ * https://doc.rust-lang.org/std/iter/struct.FilterMap.html
+ *
+ * This is the asynchronous version, which can be used like this:
+ *
+ * ```ts
+ * const results = await asyncFilterMap(things, someFunc);
+ * ```
+ *
+ * (This is an abstraction around `Promise.all`.)
+ */
+export declare function filterMapAsync<OldT, NewT>(array: readonly OldT[], func: (element: OldT) => Promise<NewT | undefined>): Promise<readonly NewT[]>;
 /**
  * Helper function to get a random element from the provided array.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/functions/array.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAI7D;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,CAAC,EACvC,KAAK,EAAE,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC,GACjC,aAAa,CAAC,SAAS,CAAC,EAAE,CAAC,CAQ7B;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,MAAM,EAAE,SAAS,CAAC,EAAE,EACpB,MAAM,EAAE,SAAS,CAAC,EAAE,GACnB,OAAO,CAST;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,aAAa,EAAE,SAAS,CAAC,EAAE,EAC3B,GAAG,gBAAgB,EAAE,SAAS,CAAC,EAAE,GAChC,SAAS,CAAC,EAAE,CAWd;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EAErC,KAAK,EAAE,CAAC,EAAE,EACV,GAAG,gBAAgB,EAAE,SAAS,CAAC,EAAE,GAChC,OAAO,CAeT;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,EAElC,KAAK,EAAE,CAAC,EAAE,EACV,GAAG,gBAAgB,EAAE,SAAS,CAAC,EAAE,GAChC,SAAS,CAAC,EAAE,CAYd;AAED,0EAA0E;AAE1E,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAEjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAClC,KAAK,EAAE,SAAS,IAAI,EAAE,EACtB,IAAI,EAAE,CAAC,OAAO,EAAE,IAAI,KAAK,IAAI,GAAG,SAAS,GACxC,SAAS,IAAI,EAAE,CAWjB;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,CAAC,EACrC,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,UAAU,GAAE,SAAS,CAAC,EAAO,GAC5B,CAAC,CAiBH;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,UAAU,GAAE,SAAS,MAAM,EAAO,GACjC,MAAM,CAQR;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,YAAY,SAAS,YAAY,CAAC,CAAC,CAAC,EAC9D,KAAK,EAAE,SAAS,YAAY,EAAE,EAC9B,aAAa,EAAE,YAAY,CAAC,CAAC,CAAC,GAC7B,aAAa,IAAI,YAAY,CAG/B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAC3B,KAAK,EAAE,SAAS,CAAC,EAAE,EACnB,GAAG,cAAc,EAAE,SAAS,CAAC,EAAE,GAC9B,OAAO,CAET;AAED,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,OAAO,EAAE,CAEhE;AAED,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,OAAO,EAAE,CAMvE;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,MAAM,EAAE,CAMrE;AAED,iFAAiF;AACjF,wBAAgB,aAAa,CAAC,QAAQ,EAAE,OAAO,GAAG,QAAQ,IAAI,MAAM,EAAE,CAMrE;AAED,qFAAqF;AACrF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,GAAG,SAAS,CAAC,EAAE,CAElE;AAED,+DAA+D;AAC/D,wBAAgB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAEzD"}
+{"version":3,"file":"array.d.ts","sourceRoot":"","sources":["../../src/functions/array.ts"],"names":[],"mappings":"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"}

package/dist/index.cjs

@@ -188,6 +188,12 @@ function arrayRemoveInPlace(array, ...elementsToRemove) {
 function emptyArray(array) {
   array.splice(0);
 }
+async function filterAsync(array, predicate) {
+  const results = await Promise.all(
+    array.map(async (element) => await predicate(element))
+  );
+  return array.filter((_, index) => results[index] === true);
+}
 function filterMap(array, func) {
   const filteredArray = [];
   for (const element of array) {
@@ -198,6 +204,11 @@ function filterMap(array, func) {
   }
   return filteredArray;
 }
+async function filterMapAsync(array, func) {
+  const promises = array.map(async (element) => await func(element));
+  const results = await Promise.all(promises);
+  return results.filter((item) => item !== void 0);
+}
 function getRandomArrayElement(array, exceptions = []) {
   if (array.length === 0) {
     throw new Error(
@@ -621,7 +632,9 @@ exports.copySet = copySet;
 exports.eRange = eRange;
 exports.emptyArray = emptyArray;
 exports.escapeHTMLCharacters = escapeHTMLCharacters;
+exports.filterAsync = filterAsync;
 exports.filterMap = filterMap;
+exports.filterMapAsync = filterMapAsync;
 exports.getElapsedSeconds = getElapsedSeconds;
 exports.getEnumEntries = getEnumEntries;
 exports.getEnumKeys = getEnumKeys;

package/dist/index.mjs

@@ -186,6 +186,12 @@ function arrayRemoveInPlace(array, ...elementsToRemove) {
 function emptyArray(array) {
   array.splice(0);
 }
+async function filterAsync(array, predicate) {
+  const results = await Promise.all(
+    array.map(async (element) => await predicate(element))
+  );
+  return array.filter((_, index) => results[index] === true);
+}
 function filterMap(array, func) {
   const filteredArray = [];
   for (const element of array) {
@@ -196,6 +202,11 @@ function filterMap(array, func) {
   }
   return filteredArray;
 }
+async function filterMapAsync(array, func) {
+  const promises = array.map(async (element) => await func(element));
+  const results = await Promise.all(promises);
+  return results.filter((item) => item !== void 0);
+}
 function getRandomArrayElement(array, exceptions = []) {
   if (array.length === 0) {
     throw new Error(
@@ -586,4 +597,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, filterMap, 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, mapFilter, mapFind, newArray, noop, normalizeString, objectFilter, objectKeysToSet, objectToMap, objectToReverseMap, objectValuesToSet, parseFloatSafe, parseIntSafe, parseSemanticVersion, removeLinesBetweenMarkers, removeLinesMatching, removeNonPrintableCharacters, removeWhitespace, repeat, setAdd, setHas, sortCaseInsensitive, sumArray, 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, mapFilter, mapFind, newArray, noop, normalizeString, objectFilter, objectKeysToSet, objectToMap, objectToReverseMap, objectValuesToSet, parseFloatSafe, parseIntSafe, parseSemanticVersion, removeLinesBetweenMarkers, removeLinesMatching, removeNonPrintableCharacters, removeWhitespace, repeat, setAdd, setHas, sortCaseInsensitive, sumArray, todo, trimPrefix, trimSuffix, truncateString, tupleEntries, tupleKeys };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "complete-common",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "Helper functions for TypeScript projects.",
   "homepage": "https://complete-ts.github.io/",
   "bugs": {
@@ -28,14 +28,14 @@
     "build": "tsx ./scripts/build.ts",
     "docs": "typedoc",
     "lint": "tsx ./scripts/lint.ts",
-    "test": "tsx --test"
+    "test": "tsx --test \"src/**/*.test.ts\""
   },
   "devDependencies": {
-    "@types/node": "24.10.2",
-    "complete-node": "13.0.0",
+    "@types/node": "25.0.3",
+    "complete-node": "16.2.0",
     "eslint-plugin-sort-exports": "0.9.1",
     "typescript": "5.9.3",
-    "typescript-eslint": "8.49.0",
+    "typescript-eslint": "8.52.0",
     "unbuild": "3.6.1"
   }
 }

package/src/functions/array.ts

@@ -136,6 +136,30 @@ export function emptyArray(array: unknown[]): void {
   array.splice(0);
 }
 
+/**
+ * Helper function to perform an asynchronous filter. The vanilla `Array.filter` method does not
+ * wait for promises (and treats them as truthy), so this function runs the predicate on all
+ * elements concurrently, awaits the results, and then filters the original array.
+ *
+ * Usage:
+ *
+ * ```ts
+ * const results = await filterAsync(things, async (thing) => await filterFunc(thing));
+ * ```
+ *
+ * (This is an abstraction around `Promise.all`.)
+ */
+export async function filterAsync<T>(
+  array: readonly T[],
+  predicate: (element: T) => Promise<boolean>,
+): Promise<readonly T[]> {
+  const results = await Promise.all(
+    array.map(async (element) => await predicate(element)),
+  );
+
+  return array.filter((_, index) => results[index] === true);
+}
+
 /**
  * Helper function to perform a filter and a map at the same time. Similar to `Array.map`, provide a
  * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
@@ -163,6 +187,34 @@ export function filterMap<OldT, NewT>(
   return filteredArray;
 }
 
+/**
+ * Helper function to perform a filter and a map at the same time. Similar to `Array.map`, provide a
+ * function that transforms a value, but return `undefined` if the value should be skipped. (Thus,
+ * this function cannot be used in situations where `undefined` can be a valid array element.)
+ *
+ * This function is useful because the `Array.map` method will always produce an array with the same
+ * amount of elements as the original array.
+ *
+ * This is named `filterMap` after the Rust function:
+ * https://doc.rust-lang.org/std/iter/struct.FilterMap.html
+ *
+ * This is the asynchronous version, which can be used like this:
+ *
+ * ```ts
+ * const results = await asyncFilterMap(things, someFunc);
+ * ```
+ *
+ * (This is an abstraction around `Promise.all`.)
+ */
+export async function filterMapAsync<OldT, NewT>(
+  array: readonly OldT[],
+  func: (element: OldT) => Promise<NewT | undefined>,
+): Promise<readonly NewT[]> {
+  const promises = array.map(async (element) => await func(element));
+  const results = await Promise.all(promises);
+  return results.filter((item) => item !== undefined);
+}
+
 /**
  * Helper function to get a random element from the provided array.
  *