@ls-stack/utils 3.35.0 → 3.37.0

package/dist/arrayUtils.cjs

@@ -25,6 +25,7 @@ __export(arrayUtils_exports, {
   arrayWithPrevAndIndex: () => arrayWithPrevAndIndex,
   filterAndMap: () => filterAndMap,
   findAfterIndex: () => findAfterIndex,
+  findAndMap: () => findAndMap,
   findBeforeIndex: () => findBeforeIndex,
   getAscIndexOrder: () => getAscIndexOrder,
   hasDuplicates: () => hasDuplicates,
@@ -160,11 +161,19 @@ function truncateArray(array, maxLength, appendIfTruncated) {
   }
   return result;
 }
+function findAndMap(array, predicate) {
+  for (const item of array) {
+    const value = predicate(item);
+    if (value !== false) return value;
+  }
+  return void 0;
+}
 function arrayOps(array) {
   return {
     filterAndMap: (mapFilter) => filterAndMap(array, mapFilter),
     sortBy: (sortByValue, props) => sortBy(array, sortByValue, props),
-    rejectDuplicates: (getKey) => rejectDuplicates(array, getKey)
+    rejectDuplicates: (getKey) => rejectDuplicates(array, getKey),
+    findAndMap: (predicate) => findAndMap(array, predicate)
   };
 }
 // Annotate the CommonJS export names for ESM import in node:
@@ -174,6 +183,7 @@ function arrayOps(array) {
   arrayWithPrevAndIndex,
   filterAndMap,
   findAfterIndex,
+  findAndMap,
   findBeforeIndex,
   getAscIndexOrder,
   hasDuplicates,

package/dist/arrayUtils.d.cts

@@ -94,7 +94,26 @@ type ArrayOps<T> = {
     filterAndMap: <R>(mapFilter: (item: T, index: number) => false | R) => R[];
     sortBy: (sortByValue: SortByValue<T>, props: SortByProps) => T[];
     rejectDuplicates: (getKey: (item: T) => unknown) => T[];
+    findAndMap: <R>(predicate: (value: T) => R | false) => R | undefined;
 };
+/**
+ * Finds the first item in an array where the predicate returns a non-false value and returns that mapped value.
+ *
+ * Combines find and map operations - applies the predicate to each item until one returns
+ * a value that is not `false`, then returns that mapped value. If no item matches, returns `undefined`.
+ *
+ * @param array - The array to search through
+ * @param predicate - Function that returns a mapped value or `false` to skip the item
+ * @returns The first mapped value that is not `false`, or `undefined` if no item matches
+ * @example
+ * const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ *
+ * const foundName = findAndMap(users, (user) =>
+ *   user.id === 2 ? user.name.toUpperCase() : false
+ * );
+ * // foundName is 'BOB'
+ */
+declare function findAndMap<T, R>(array: T[], predicate: (value: T) => R | false): R | undefined;
 /**
  * Enhance an array with extra methods
  *
@@ -109,4 +128,4 @@ type ArrayOps<T> = {
  */
 declare function arrayOps<T>(array: T[]): ArrayOps<T>;
 
-export { type FilterAndMapReturn, arrayOps, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findBeforeIndex, getAscIndexOrder, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy, truncateArray };
+export { type FilterAndMapReturn, arrayOps, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findAndMap, findBeforeIndex, getAscIndexOrder, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy, truncateArray };

package/dist/arrayUtils.d.ts

@@ -94,7 +94,26 @@ type ArrayOps<T> = {
     filterAndMap: <R>(mapFilter: (item: T, index: number) => false | R) => R[];
     sortBy: (sortByValue: SortByValue<T>, props: SortByProps) => T[];
     rejectDuplicates: (getKey: (item: T) => unknown) => T[];
+    findAndMap: <R>(predicate: (value: T) => R | false) => R | undefined;
 };
+/**
+ * Finds the first item in an array where the predicate returns a non-false value and returns that mapped value.
+ *
+ * Combines find and map operations - applies the predicate to each item until one returns
+ * a value that is not `false`, then returns that mapped value. If no item matches, returns `undefined`.
+ *
+ * @param array - The array to search through
+ * @param predicate - Function that returns a mapped value or `false` to skip the item
+ * @returns The first mapped value that is not `false`, or `undefined` if no item matches
+ * @example
+ * const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+ *
+ * const foundName = findAndMap(users, (user) =>
+ *   user.id === 2 ? user.name.toUpperCase() : false
+ * );
+ * // foundName is 'BOB'
+ */
+declare function findAndMap<T, R>(array: T[], predicate: (value: T) => R | false): R | undefined;
 /**
  * Enhance an array with extra methods
  *
@@ -109,4 +128,4 @@ type ArrayOps<T> = {
  */
 declare function arrayOps<T>(array: T[]): ArrayOps<T>;
 
-export { type FilterAndMapReturn, arrayOps, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findBeforeIndex, getAscIndexOrder, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy, truncateArray };
+export { type FilterAndMapReturn, arrayOps, arrayWithPrev, arrayWithPrevAndIndex, filterAndMap, findAfterIndex, findAndMap, findBeforeIndex, getAscIndexOrder, hasDuplicates, isInArray, rejectArrayUndefinedValues, rejectDuplicates, sortBy, truncateArray };

package/dist/arrayUtils.js

@@ -4,6 +4,7 @@ import {
   arrayWithPrevAndIndex,
   filterAndMap,
   findAfterIndex,
+  findAndMap,
   findBeforeIndex,
   getAscIndexOrder,
   hasDuplicates,
@@ -12,7 +13,7 @@ import {
   rejectDuplicates,
   sortBy,
   truncateArray
-} from "./chunk-4DVTWCXL.js";
+} from "./chunk-27AL66CH.js";
 import "./chunk-C2SVCIWE.js";
 import "./chunk-JF2MDHOJ.js";
 export {
@@ -21,6 +22,7 @@ export {
   arrayWithPrevAndIndex,
   filterAndMap,
   findAfterIndex,
+  findAndMap,
   findBeforeIndex,
   getAscIndexOrder,
   hasDuplicates,

package/dist/asyncQueue.cjs

@@ -61,10 +61,10 @@ var AsyncQueue = class {
     this.#signal = signal;
     this.#taskTimeout = taskTimeout;
     this.events.on("error", (e) => {
-      this.failures.push(e);
+      this.failures.push(e.payload);
     });
     this.events.on("complete", (e) => {
-      this.completions.push(e);
+      this.completions.push(e.payload);
     });
   }
   #enqueue(task) {

package/dist/asyncQueue.js

@@ -32,10 +32,10 @@ var AsyncQueue = class {
     this.#signal = signal;
     this.#taskTimeout = taskTimeout;
     this.events.on("error", (e) => {
-      this.failures.push(e);
+      this.failures.push(e.payload);
     });
     this.events.on("complete", (e) => {
-      this.completions.push(e);
+      this.completions.push(e.payload);
     });
   }
   #enqueue(task) {

package/dist/{chunk-4DVTWCXL.js → chunk-27AL66CH.js}

@@ -118,11 +118,19 @@ function truncateArray(array, maxLength, appendIfTruncated) {
   }
   return result;
 }
+function findAndMap(array, predicate) {
+  for (const item of array) {
+    const value = predicate(item);
+    if (value !== false) return value;
+  }
+  return void 0;
+}
 function arrayOps(array) {
   return {
     filterAndMap: (mapFilter) => filterAndMap(array, mapFilter),
     sortBy: (sortByValue, props) => sortBy(array, sortByValue, props),
-    rejectDuplicates: (getKey) => rejectDuplicates(array, getKey)
+    rejectDuplicates: (getKey) => rejectDuplicates(array, getKey),
+    findAndMap: (predicate) => findAndMap(array, predicate)
   };
 }
 
@@ -139,5 +147,6 @@ export {
   hasDuplicates,
   rejectDuplicates,
   truncateArray,
+  findAndMap,
   arrayOps
 };

package/dist/{chunk-XPOGWCUC.js → chunk-6CG6JZKB.js}

@@ -1,6 +1,6 @@
 import {
   sortBy
-} from "./chunk-4DVTWCXL.js";
+} from "./chunk-27AL66CH.js";
 import {
   isPlainObject
 } from "./chunk-JF2MDHOJ.js";

package/dist/concurrentCalls.js

@@ -9,7 +9,7 @@ import {
 } from "./chunk-VAAMRG4K.js";
 import {
   truncateArray
-} from "./chunk-4DVTWCXL.js";
+} from "./chunk-27AL66CH.js";
 import {
   invariant
 } from "./chunk-C2SVCIWE.js";

package/dist/filterObjectOrArrayKeys.js

@@ -1,7 +1,7 @@
 import {
   filterObjectOrArrayKeys
-} from "./chunk-XPOGWCUC.js";
-import "./chunk-4DVTWCXL.js";
+} from "./chunk-6CG6JZKB.js";
+import "./chunk-27AL66CH.js";
 import "./chunk-C2SVCIWE.js";
 import "./chunk-JF2MDHOJ.js";
 export {

package/dist/serializeXML.js

@@ -1,6 +1,6 @@
 import {
   filterAndMap
-} from "./chunk-4DVTWCXL.js";
+} from "./chunk-27AL66CH.js";
 import "./chunk-C2SVCIWE.js";
 import {
   isTruthy

package/dist/testUtils.cjs

@@ -1347,6 +1347,7 @@ function compactSnapshot(value, {
   maxLineLength = 100,
   showUndefined = false,
   showBooleansAs = true,
+  replaceValues,
   rejectKeys,
   filterKeys,
   sortKeys,
@@ -1364,6 +1365,9 @@ function compactSnapshot(value, {
       });
     }
   }
+  if (replaceValues) {
+    processedValue = applyValueReplacements(processedValue, replaceValues);
+  }
   processedValue = showBooleansAs ? replaceBooleansWithEmoji(processedValue, showBooleansAs) : processedValue;
   return `
 ${yamlStringify(processedValue, {
@@ -1373,6 +1377,46 @@ ${yamlStringify(processedValue, {
     ...options
   })}`;
 }
+function applyValueReplacements(value, replaceValues, visited = /* @__PURE__ */ new Set(), currentPath = "") {
+  function processValue(val, path) {
+    const replacement = replaceValues(val, path);
+    if (replacement !== false) {
+      return replacement.newValue;
+    }
+    if (Array.isArray(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in array");
+      }
+      visited.add(val);
+      try {
+        return val.map((item, index) => {
+          const itemPath = path ? `${path}[${index}]` : `[${index}]`;
+          return processValue(item, itemPath);
+        });
+      } finally {
+        visited.delete(val);
+      }
+    }
+    if (isPlainObject(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in object");
+      }
+      visited.add(val);
+      try {
+        const result = {};
+        for (const [key, itemValue] of Object.entries(val)) {
+          const itemPath = path ? `${path}.${key}` : key;
+          result[key] = processValue(itemValue, itemPath);
+        }
+        return result;
+      } finally {
+        visited.delete(val);
+      }
+    }
+    return val;
+  }
+  return processValue(value, currentPath);
+}
 function replaceBooleansWithEmoji(value, showBooleansAs, visited = /* @__PURE__ */ new Set()) {
   if (showBooleansAs === false) {
     return value;

package/dist/testUtils.d.cts

@@ -88,11 +88,12 @@ declare function waitController(): {
  * @param options.rejectKeys - The keys to reject.
  * @param options.filterKeys - The keys to filter.
  * @param options.ignoreProps - The props to ignore.
+ * @param options.replaceValues - Function to replace values at specific paths. Returns `false` to keep original value or `{newValue}` to replace.
  * @param options.sortKeys - Sort all keys by a specific order (default: `simpleValuesFirst`).
  * @param options.sortPatterns - Sort specific keys by pattern. Use to control the order of specific properties. The same patterns as `filterKeys` are supported.
  * @returns The compact snapshot of the value.
  */
-declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, rejectKeys, filterKeys, sortKeys, sortPatterns, ...options }?: YamlStringifyOptions & {
+declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, replaceValues, rejectKeys, filterKeys, sortKeys, sortPatterns, ...options }?: YamlStringifyOptions & {
     showBooleansAs?: boolean | {
         props?: Record<string, {
             trueText?: string;
@@ -102,6 +103,9 @@ declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLengt
         trueText?: string;
         falseText?: string;
     };
+    replaceValues?: (value: unknown, path: string) => false | {
+        newValue: unknown;
+    };
     rejectKeys?: string[] | string;
     filterKeys?: string[] | string;
     sortKeys?: 'asc' | 'desc' | 'simpleValuesFirst' | false;

package/dist/testUtils.d.ts

@@ -88,11 +88,12 @@ declare function waitController(): {
  * @param options.rejectKeys - The keys to reject.
  * @param options.filterKeys - The keys to filter.
  * @param options.ignoreProps - The props to ignore.
+ * @param options.replaceValues - Function to replace values at specific paths. Returns `false` to keep original value or `{newValue}` to replace.
  * @param options.sortKeys - Sort all keys by a specific order (default: `simpleValuesFirst`).
  * @param options.sortPatterns - Sort specific keys by pattern. Use to control the order of specific properties. The same patterns as `filterKeys` are supported.
  * @returns The compact snapshot of the value.
  */
-declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, rejectKeys, filterKeys, sortKeys, sortPatterns, ...options }?: YamlStringifyOptions & {
+declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLength, showUndefined, showBooleansAs, replaceValues, rejectKeys, filterKeys, sortKeys, sortPatterns, ...options }?: YamlStringifyOptions & {
     showBooleansAs?: boolean | {
         props?: Record<string, {
             trueText?: string;
@@ -102,6 +103,9 @@ declare function compactSnapshot(value: unknown, { collapseObjects, maxLineLengt
         trueText?: string;
         falseText?: string;
     };
+    replaceValues?: (value: unknown, path: string) => false | {
+        newValue: unknown;
+    };
     rejectKeys?: string[] | string;
     filterKeys?: string[] | string;
     sortKeys?: 'asc' | 'desc' | 'simpleValuesFirst' | false;

package/dist/testUtils.js

@@ -11,7 +11,7 @@ import {
 } from "./chunk-JQFUKJU5.js";
 import {
   filterObjectOrArrayKeys
-} from "./chunk-XPOGWCUC.js";
+} from "./chunk-6CG6JZKB.js";
 import {
   defer
 } from "./chunk-DFXNVEH6.js";
@@ -22,7 +22,7 @@ import "./chunk-KW55OTUG.js";
 import {
   arrayWithPrevAndIndex,
   filterAndMap
-} from "./chunk-4DVTWCXL.js";
+} from "./chunk-27AL66CH.js";
 import {
   isObject
 } from "./chunk-C2SVCIWE.js";
@@ -261,6 +261,7 @@ function compactSnapshot(value, {
   maxLineLength = 100,
   showUndefined = false,
   showBooleansAs = true,
+  replaceValues,
   rejectKeys,
   filterKeys,
   sortKeys,
@@ -278,6 +279,9 @@ function compactSnapshot(value, {
       });
     }
   }
+  if (replaceValues) {
+    processedValue = applyValueReplacements(processedValue, replaceValues);
+  }
   processedValue = showBooleansAs ? replaceBooleansWithEmoji(processedValue, showBooleansAs) : processedValue;
   return `
 ${yamlStringify(processedValue, {
@@ -287,6 +291,46 @@ ${yamlStringify(processedValue, {
     ...options
   })}`;
 }
+function applyValueReplacements(value, replaceValues, visited = /* @__PURE__ */ new Set(), currentPath = "") {
+  function processValue(val, path) {
+    const replacement = replaceValues(val, path);
+    if (replacement !== false) {
+      return replacement.newValue;
+    }
+    if (Array.isArray(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in array");
+      }
+      visited.add(val);
+      try {
+        return val.map((item, index) => {
+          const itemPath = path ? `${path}[${index}]` : `[${index}]`;
+          return processValue(item, itemPath);
+        });
+      } finally {
+        visited.delete(val);
+      }
+    }
+    if (isPlainObject(val)) {
+      if (visited.has(val)) {
+        throw new Error("Circular reference detected in object");
+      }
+      visited.add(val);
+      try {
+        const result = {};
+        for (const [key, itemValue] of Object.entries(val)) {
+          const itemPath = path ? `${path}.${key}` : key;
+          result[key] = processValue(itemValue, itemPath);
+        }
+        return result;
+      } finally {
+        visited.delete(val);
+      }
+    }
+    return val;
+  }
+  return processValue(value, currentPath);
+}
 function replaceBooleansWithEmoji(value, showBooleansAs, visited = /* @__PURE__ */ new Set()) {
   if (showBooleansAs === false) {
     return value;

package/docs/arrayUtils/-internal-.md

@@ -63,6 +63,30 @@ const enhancedItems = arrayOps(items);
 enhancedItems.filterAndMap((item) => item === 2 ? false : item);
 ```
 
+##### findAndMap()
+
+```ts
+findAndMap: <R>(predicate) => R | undefined;
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:275](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L275)
+
+###### Type Parameters
+
+###### R
+
+`R`
+
+###### Parameters
+
+###### predicate
+
+(`value`) => `R` \| `false`
+
+###### Returns
+
+`R` \| `undefined`
+
 ##### rejectDuplicates()
 
 ```ts

package/docs/arrayUtils/README.md

@@ -34,7 +34,7 @@ Defined in: [packages/utils/src/arrayUtils.ts:42](https://github.com/lucasols/ut
 function arrayOps<T>(array): ArrayOps<T>;
 ```
 
-Defined in: [packages/utils/src/arrayUtils.ts:289](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L289)
+Defined in: [packages/utils/src/arrayUtils.ts:318](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L318)
 
 Enhance an array with extra methods
 
@@ -209,6 +209,62 @@ Defined in: [packages/utils/src/arrayUtils.ts:165](https://github.com/lucasols/u
 
 ***
 
+### findAndMap()
+
+```ts
+function findAndMap<T, R>(array, predicate): undefined | R;
+```
+
+Defined in: [packages/utils/src/arrayUtils.ts:295](https://github.com/lucasols/utils/blob/main/packages/utils/src/arrayUtils.ts#L295)
+
+Finds the first item in an array where the predicate returns a non-false value and returns that mapped value.
+
+Combines find and map operations - applies the predicate to each item until one returns
+a value that is not `false`, then returns that mapped value. If no item matches, returns `undefined`.
+
+#### Type Parameters
+
+##### T
+
+`T`
+
+##### R
+
+`R`
+
+#### Parameters
+
+##### array
+
+`T`[]
+
+The array to search through
+
+##### predicate
+
+(`value`) => `false` \| `R`
+
+Function that returns a mapped value or `false` to skip the item
+
+#### Returns
+
+`undefined` \| `R`
+
+The first mapped value that is not `false`, or `undefined` if no item matches
+
+#### Example
+
+```ts
+const users = [{ id: 1, name: 'Alice' }, { id: 2, name: 'Bob' }];
+
+const foundName = findAndMap(users, (user) => 
+  user.id === 2 ? user.name.toUpperCase() : false
+);
+// foundName is 'BOB'
+```
+
+***
+
 ### findBeforeIndex()
 
 ```ts

package/docs/testUtils.md

@@ -14,7 +14,7 @@
 function compactSnapshot(value, options): string;
 ```
 
-Defined in: [packages/utils/src/testUtils.ts:363](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L363)
+Defined in: [packages/utils/src/testUtils.ts:364](https://github.com/lucasols/utils/blob/main/packages/utils/src/testUtils.ts#L364)
 
 Produces a more compact and readable snapshot of a value using yaml.
 By default booleans are shown as `✅` and `❌`, use `showBooleansAs` to disable/configure this.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ls-stack/utils",
   "description": "Universal TypeScript utilities for browser and Node.js",
-  "version": "3.35.0",
+  "version": "3.37.0",
   "license": "MIT",
   "files": [
     "dist",
@@ -222,7 +222,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.18.0",
-    "@ls-stack/extended-lint": "^0.20.1",
+    "@ls-stack/extended-lint": "^0.67.2",
     "@types/eslint": "^9.6.1",
     "@types/eslint__js": "^8.42.3",
     "@types/node": "^22.10.9",
@@ -247,7 +247,7 @@
     "vitest": "^3.0.4"
   },
   "dependencies": {
-    "evtmitter": "^0.3.3",
+    "evtmitter": "^1.0.2",
     "t-result": "^0.3.0"
   },
   "scripts": {