@tim-code/my-util 0.6.5 → 0.7.0

package/package.json

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

package/src/math.js

@@ -144,6 +144,24 @@ export function range(start, end, increment = 1) {
   return results
 }
 
+/**
+ * Create an array of numbers progressing from start up to and including end.
+ * @param {number} start
+ * @param {number=} end
+ * @param {number=} increment
+ * @returns {number[]}
+ */
+export function between(start, end, increment = 1) {
+  if (!(increment > 0)) {
+    return []
+  }
+  const results = []
+  for (let i = start; i <= end; i += increment) {
+    results.push(i)
+  }
+  return results
+}
+
 /**
  * Check if the argument is a number.
  * This excludes Infinity and NaN, but otherwise is equivalent to `typeof number === "number"`.

package/src/math.test.js

@@ -1,4 +1,5 @@
 import { describe, expect, it } from "@jest/globals"
+import { between } from "./math.js"
 
 // EXPORTED FUNCTIONS UNDER TEST:
 // - mod
@@ -314,6 +315,52 @@ describe("range", () => {
   })
 })
 
+describe("between", () => {
+  it("returns an empty array if start >= end", () => {
+    expect(between(7, 5)).toEqual([])
+    expect(between(10, 5)).toEqual([])
+
+    expect(between(5, 5)).toEqual([5])
+  })
+
+  it("returns a sequence from start to end with default increment 1", () => {
+    expect(between(0, 3)).toEqual([0, 1, 2, 3])
+    expect(between(2, 6)).toEqual([2, 3, 4, 5, 6])
+  })
+
+  it("returns a sequence with a custom positive increment", () => {
+    expect(between(0, 5, 2)).toEqual([0, 2, 4])
+    expect(between(1, 8, 3)).toEqual([1, 4, 7])
+  })
+  it("works with negative start and end", () => {
+    expect(between(-3, 1)).toEqual([-3, -2, -1, 0, 1])
+    expect(between(-5, -2)).toEqual([-5, -4, -3, -2])
+  })
+
+  it("returns an empty array if increment is zero", () => {
+    expect(between(0, 5, 0)).toEqual([])
+  })
+
+  it("returns an empty array if increment is negative and start < end", () => {
+    expect(between(0, 5, -1)).toEqual([])
+    expect(between(2, 6, -2)).toEqual([])
+  })
+
+  it("returns an empty array if increment is negative and start > end", () => {
+    expect(between(5, 0, -1)).toEqual([])
+    expect(between(3, -2, -2)).toEqual([])
+  })
+
+  it("returns an empty array if increment is positive and start > end", () => {
+    expect(between(5, 0, 1)).toEqual([])
+    expect(between(2, -2, 2)).toEqual([])
+  })
+
+  it("handles floating point increments", () => {
+    expect(between(0, 1, 0.25)).toEqual([0, 0.25, 0.5, 0.75, 1])
+  })
+})
+
 describe("isNumber", () => {
   it("returns true for finite numbers", () => {
     expect(isNumber(0)).toBe(true)

package/src/promise.js

@@ -2,6 +2,8 @@ import { chunk } from "./array.js"
 
 export class PollError extends Error {}
 
+export class PromiseAllError extends Error {}
+
 /**
  * Calls a function immediately and then every X milliseconds until the function does not return undefined, null or false.
  * Note that other falsy values such as 0 or "" or NaN will resolve and be returned.
@@ -70,14 +72,17 @@ export async function sleep(ms) {
  * @param {number=} $1.limit The number of calls to do in parallel. If not provided, each call is done in parallel.
  * @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" and "returned" before returning; useful if promises return arrays
+ * @param {boolean=} $1.flatten If true, flattens "values" and "returned" before returning; useful if promises return arrays.
+ *  `null` and `undefined` return values are passed through.
  * @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 {boolean=} $1.throws If true, will collect error messages, if any, together into one PromiseAllError object and throw it.
+ *  Sets the PromiseAllError's stack from one of the collected errors, if available.
  * @param {Function} callback Default is identity function to enable passing promises as "array".
  * @returns {Object} {results, values, returned, errors}
  */
 export async function allSettled(
-  { array, iterable = array, limit, limiter, flatten = false, abort = false },
+  { array, iterable = array, limit, limiter, flatten = false, abort = false, throws = false },
   callback = (promise) => promise
 ) {
   const results = []
@@ -103,13 +108,35 @@ export async function allSettled(
     }
     await limiter?.(elements.length)
   }
+  if (throws && errors.length) {
+    const string = errors.map((error) => error.message ?? error).join("; ")
+    const resultError = new PromiseAllError(string)
+    const { trace } = errors.find((error) => Array.isArray(error.trace)) ?? {}
+    if (trace) {
+      resultError.stack = trace.join("\n")
+    }
+    throw resultError
+  }
   if (flatten) {
-    values = values.flat()
-    returned = returned.flat()
+    values = values?.flat()
+    returned = returned?.flat()
   }
   return { values, returned, errors, results }
 }
 
+/**
+ * Parallelize awaiting an array of promises using `Promise.allSettled()` but throw if an error, similar to Promise.all().
+ * Also like Promise.all(), returns the return values of passed promises as an array.
+ * If multiple errors, joins error messages together and tries to keep a stack trace from the first error with a trace.
+ * @param {Array<Promise>} promises
+ * @param {Object} $1
+ * @param {boolean=} $1.flatten If true, flattens values before returning; useful if promises return arrays.
+ * @returns {Array}
+ */
+export async function allPatiently(promises, { flatten }) {
+  return (await allSettled({ iterable: promises, flatten, throws: true })).returned
+}
+
 /**
  * Creates a function that can be used with allSettled to limit the number of elements processed in a time interval.
  * Once the limit is reached, waits until the start of a new interval before returning.

package/src/promise.test.js

@@ -3,11 +3,11 @@ import { jest } from "@jest/globals"
 
 // Exported API under test:
 // - class PollError
-// - functions: poll, sleep, allSettled, intervalLimiter, alert, throwFirstReject
-// Code changes in this diff affect: allSettled (added "iterable" param and generalized to Iterable)
+// - functions: poll, sleep, allSettled, allPatiently, intervalLimiter, alert, throwFirstReject
 
 import {
   alert,
+  allPatiently,
   allSettled,
   intervalLimiter,
   poll,
@@ -69,7 +69,6 @@ describe("poll", () => {
   it("waits before first call if wait=true", async () => {
     const cb = jest.fn().mockReturnValue(1)
     const promise = poll({ ms: 2, wait: true }, cb)
-    // Wait a little longer than ms to ensure callback is called
     await sleep(3)
     await expect(promise).resolves.toBe(1)
     expect(cb).toHaveBeenCalledTimes(1)
@@ -113,7 +112,6 @@ describe("sleep", () => {
     const promise = sleep(5)
     await expect(promise).resolves.toBeUndefined()
     const after = Date.now()
-    // Allow for some jitter
     expect(after - before).toBeGreaterThanOrEqual(5)
   })
 
@@ -176,6 +174,20 @@ describe("allSettled", () => {
     expect(result.returned).toEqual([1, 2, 2, 3])
   })
 
+  it("passes through null/undefined when flatten=true", async () => {
+    const arr = [0, 1, 2, 3]
+    const cb = (x) => {
+      if (x === 0) return [1, null]
+      if (x === 1) return undefined
+      if (x === 2) return [3]
+      return null
+    }
+    const result = await allSettled({ array: arr, flatten: true }, cb)
+    expect(result.values).toEqual([1, null, undefined, 3, null])
+    expect(result.returned).toEqual([1, null, undefined, 3, null])
+    expect(result.errors).toEqual([])
+  })
+
   it("handles empty array", async () => {
     const result = await allSettled({ array: [] }, () => 1)
     expect(result.values).toEqual([])
@@ -194,7 +206,6 @@ describe("allSettled", () => {
     }
     const limiter = jest.fn(async (n) => {
       limiterCalls.push(n)
-      // simulate async delay
       await sleep(1)
     })
     const result = await allSettled({ array: arr, limit: 2, limiter }, cb)
@@ -205,19 +216,14 @@ describe("allSettled", () => {
   })
 
   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]
   })
 
   it("accepts non-Array iterable via iterable option (Map)", async () => {
@@ -233,6 +239,41 @@ describe("allSettled", () => {
     expect(result.errors).toEqual([])
     expect(result.results.every((r) => r.status === "fulfilled")).toBe(true)
   })
+
+  it("throws joined error message when throws=true and adopts trace stack if provided", async () => {
+    const eWithTrace = new Error("e1")
+    eWithTrace.trace = ["trace line 1", "trace line 2"]
+    const e2 = new Error("third")
+    const arr = [1, 2, 3]
+    const cb = (x) => {
+      if (x === 1) return Promise.reject(eWithTrace)
+      if (x === 2) return x // fulfilled
+      return Promise.reject(e2)
+    }
+    let thrown
+    try {
+      await allSettled({ array: arr, throws: true }, cb)
+    } catch (e) {
+      thrown = e
+    }
+    expect(thrown).toBeInstanceOf(Error)
+    expect(thrown.message).toBe("e1; third")
+    expect(thrown.stack).toBe("trace line 1\ntrace line 2")
+  })
+})
+
+describe("allPatiently", () => {
+  it("returns flattened values when all promises resolve", async () => {
+    const promises = [Promise.resolve([1]), Promise.resolve([2, 3])]
+    const result = await allPatiently(promises, { flatten: true })
+    expect(result).toEqual([1, 2, 3])
+  })
+
+  it("throws with joined messages when any promise rejects", async () => {
+    const bad = new Error("bad")
+    const promises = [Promise.resolve(1), Promise.reject(bad), Promise.reject("oops")]
+    await expect(allPatiently(promises, { flatten: false })).rejects.toThrow("bad; oops")
+  })
 })
 
 describe("intervalLimiter", () => {