@tim-code/my-util 0.4.0 → 0.4.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "",
   "type": "module",
   "author": "Tim Sprowl",

package/src/find.js

@@ -153,6 +153,7 @@ export function findClosestGTE(array, desired, { key, cutoff = Infinity } = {})
 
 /**
  * Find the closest element in an array. If there is a tie, then returns the first matching element by order in the array.
+ * If some values are undefined or null, they will be ignored. If no element is found, returns undefined.
  * If using for strings, need to specify different values for "cutoff" and "comparator".
  * "~" and "" are good cutoff string values for gt/gte and lt/lte respectively.
  * @template T, V
@@ -267,3 +268,72 @@ export function findMax(array, { key, cutoff = -Infinity } = {}) {
   }
   return closest
 }
+
+/**
+ * Like Array.prototype.findIndex but starts from given index.
+ * @template T
+ * @param {Array<T>} array
+ * @param {number} fromIndex
+ * @param {(value: T, index: number, array: Array<T>) => boolean} callback
+ * @returns {number}
+ */
+export function findIndexFrom(array, fromIndex, callback) {
+  for (let i = fromIndex; i < array.length; i++) {
+    if (callback(array[i], i, array)) {
+      return i
+    }
+  }
+  return -1
+}
+
+/**
+ * Like Array.prototype.find but starts from given index.
+ * @template T
+ * @param {Array<T>} array
+ * @param {number} fromIndex
+ * @param {(value: T, index: number, array: Array<T>) => boolean} callback
+ * @returns {T|undefined}
+ */
+export function findFrom(array, fromIndex, callback) {
+  const foundIndex = findIndexFrom(array, fromIndex, callback)
+  if (foundIndex < 0) {
+    return undefined
+  }
+  return array[foundIndex]
+}
+
+/**
+ * Like Array.prototype.findLastIndex but starts from given index.
+ * @template T
+ * @param {Array<T>} array
+ * @param {number} fromIndex If greater or equal to length, coerces to last index in array.
+ * @param {(value: T, index: number, array: Array<T>) => boolean} callback
+ * @returns {number}
+ */
+export function findLastIndexFrom(array, fromIndex, callback) {
+  if (fromIndex >= array.length) {
+    fromIndex = array.length - 1
+  }
+  for (let i = fromIndex; i >= 0; i--) {
+    if (callback(array[i], i, array)) {
+      return i
+    }
+  }
+  return -1
+}
+
+/**
+ * Like Array.prototype.findLast but starts from given index.
+ * @template T
+ * @param {Array<T>} array
+ * @param {number} fromIndex
+ * @param {(value: T, index: number, array: Array<T>) => boolean} callback
+ * @returns {T|undefined}
+ */
+export function findLastFrom(array, fromIndex, callback) {
+  const foundIndex = findLastIndexFrom(array, fromIndex, callback)
+  if (foundIndex < 0) {
+    return undefined
+  }
+  return array[foundIndex]
+}

package/src/find.test.js

@@ -9,6 +9,10 @@ const {
   findClosest,
   findMin,
   findMax,
+  findIndexFrom,
+  findFrom,
+  findLastIndexFrom,
+  findLastFrom,
 } = await import("./find.js")
 
 describe("findClosestAbs", () => {
@@ -284,3 +288,117 @@ describe("findMax", () => {
     expect(findMax([3, 1, 4, 2], { cutoff: 4 })).toBeUndefined()
   })
 })
+
+describe("findIndexFrom", () => {
+  it("returns the index of the first matching element from fromIndex", () => {
+    expect(findIndexFrom([1, 2, 3, 4], 1, (x) => x > 2)).toBe(2)
+    expect(findIndexFrom([1, 2, 3, 4], 2, (x) => x > 2)).toBe(2)
+    expect(findIndexFrom([1, 2, 3, 4], 3, (x) => x > 2)).toBe(3)
+  })
+
+  it("returns -1 if no element matches", () => {
+    expect(findIndexFrom([1, 2, 3, 4], 2, (x) => x > 10)).toBe(-1)
+  })
+
+  it("returns -1 for empty array", () => {
+    expect(findIndexFrom([], 0, () => true)).toBe(-1)
+  })
+
+  it("passes correct arguments to callback", () => {
+    const arr = [10, 20, 30]
+    const called = []
+    findIndexFrom(arr, 1, (value, index, array) => {
+      called.push([value, index, array])
+      return false
+    })
+    expect(called[0][0]).toBe(20)
+    expect(called[0][1]).toBe(1)
+    expect(called[0][2]).toBe(arr)
+  })
+})
+
+describe("findFrom", () => {
+  it("returns the first matching element from fromIndex", () => {
+    expect(findFrom([1, 2, 3, 4], 1, (x) => x > 2)).toBe(3)
+    expect(findFrom([1, 2, 3, 4], 2, (x) => x > 2)).toBe(3)
+    expect(findFrom([1, 2, 3, 4], 3, (x) => x > 2)).toBe(4)
+  })
+
+  it("returns undefined if no element matches", () => {
+    expect(findFrom([1, 2, 3, 4], 2, (x) => x > 10)).toBeUndefined()
+  })
+
+  it("returns undefined for empty array", () => {
+    expect(findFrom([], 0, () => true)).toBeUndefined()
+  })
+
+  it("passes correct arguments to callback", () => {
+    const arr = [10, 20, 30]
+    const called = []
+    findFrom(arr, 1, (value, index, array) => {
+      called.push([value, index, array])
+      return false
+    })
+    expect(called[0][0]).toBe(20)
+    expect(called[0][1]).toBe(1)
+    expect(called[0][2]).toBe(arr)
+  })
+})
+
+describe("findLastIndexFrom", () => {
+  it("returns the index of the last matching element from fromIndex (backwards)", () => {
+    expect(findLastIndexFrom([1, 2, 3, 4], 2, (x) => x < 3)).toBe(1)
+    expect(findLastIndexFrom([1, 2, 3, 4], 3, (x) => x < 3)).toBe(1)
+    expect(findLastIndexFrom([1, 2, 3, 4], 1, (x) => x < 3)).toBe(1)
+    expect(findLastIndexFrom([1, 2, 3, 4], 0, (x) => x < 3)).toBe(0)
+  })
+
+  it("returns -1 if no element matches", () => {
+    expect(findLastIndexFrom([1, 2, 3, 4], 3, (x) => x > 10)).toBe(-1)
+  })
+
+  it("returns -1 for empty array", () => {
+    expect(findLastIndexFrom([], 0, () => true)).toBe(-1)
+  })
+
+  it("passes correct arguments to callback", () => {
+    const arr = [10, 20, 30]
+    const called = []
+    findLastIndexFrom(arr, 2, (value, index, array) => {
+      called.push([value, index, array])
+      return false
+    })
+    expect(called[0][0]).toBe(30)
+    expect(called[0][1]).toBe(2)
+    expect(called[0][2]).toBe(arr)
+  })
+})
+
+describe("findLastFrom", () => {
+  it("returns the last matching element from fromIndex (backwards)", () => {
+    expect(findLastFrom([1, 2, 3, 4], 2, (x) => x < 3)).toBe(2)
+    expect(findLastFrom([1, 2, 3, 4], 3, (x) => x < 3)).toBe(2)
+    expect(findLastFrom([1, 2, 3, 4], 1, (x) => x < 3)).toBe(2)
+    expect(findLastFrom([1, 2, 3, 4], 0, (x) => x < 3)).toBe(1)
+  })
+
+  it("returns undefined if no element matches", () => {
+    expect(findLastFrom([1, 2, 3, 4], 3, (x) => x > 10)).toBeUndefined()
+  })
+
+  it("returns undefined for empty array", () => {
+    expect(findLastFrom([], 0, () => true)).toBeUndefined()
+  })
+
+  it("passes correct arguments to callback", () => {
+    const arr = [10, 20, 30]
+    const called = []
+    findLastFrom(arr, 2, (value, index, array) => {
+      called.push([value, index, array])
+      return false
+    })
+    expect(called[0][0]).toBe(30)
+    expect(called[0][1]).toBe(2)
+    expect(called[0][2]).toBe(arr)
+  })
+})

package/src/promise.js

@@ -70,10 +70,15 @@ export async function sleep(ms) {
  * @param {Function=} $1.limiter A function awaited after a group of parallel calls is processed.
  *  It is called with the number of parallel calls processed. Could be as simple as `() => sleep(10000)` if you wanted to wait 10 seconds between.
  * @param {boolean=} $1.flatten Flattens values before returning; useful if promises return arrays
+ * @param {boolean=} $1.abort If true, will return early if there are errors.
+ *  If false (default), will process all elements in the array (like Promise.allSettled()).
  * @param {Function} callback
  * @returns {Object} {results, values, returned, errors}
  */
-export async function allSettled({ array, limit, limiter, flatten = false }, callback) {
+export async function allSettled(
+  { array, limit, limiter, flatten = false, abort = false },
+  callback
+) {
   const results = []
   let returned = []
   let values = []
@@ -92,6 +97,9 @@ export async function allSettled({ array, limit, limiter, flatten = false }, cal
         errors.push(reason)
       }
     }
+    if (abort && errors.length) {
+      break
+    }
     await limiter?.(elements.length)
   }
   if (flatten) {

package/src/promise.test.js

@@ -2,7 +2,15 @@
 /* eslint-disable prefer-promise-reject-errors */
 import { jest } from "@jest/globals"
 
-import { alert, allSettled, poll, PollError, sleep, throwFirstReject, intervalLimiter } from "./promise.js"
+import {
+  alert,
+  allSettled,
+  intervalLimiter,
+  poll,
+  PollError,
+  sleep,
+  throwFirstReject,
+} from "./promise.js"
 
 describe("poll", () => {
   it("resolves immediately if callback returns a non-undefined/null/false value", async () => {
@@ -182,6 +190,22 @@ describe("allSettled", () => {
     expect(limiter).toHaveBeenCalledTimes(3)
     expect(limiterCalls).toEqual([2, 2, 1])
   })
+
+  it("returns early if abort=true and any error occurs", async () => {
+    // Should process only up to the first chunk with a rejection, then stop
+    const arr = [1, 2, 3, 4, 5, 6]
+    const cb = jest
+      .fn()
+      .mockImplementation((x) => (x === 2 || x === 4 ? Promise.reject(`fail${x}`) : x))
+    // limit=2 so chunks: [1,2], [3,4], [5,6]
+    const result = await allSettled({ array: arr, limit: 2, abort: true }, cb)
+    // The first chunk: [1,2] => 1 fulfilled, 1 rejected
+    // Should stop after first chunk with error
+    expect(result.values.length).toBe(2)
+    expect(result.errors).toEqual(["fail2"])
+    expect(cb).toHaveBeenCalledTimes(2)
+    // Should not process [3,4] or [5,6]
+  })
 })
 
 describe("intervalLimiter", () => {