@tim-code/my-util 0.2.7 → 0.3.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.2.7",
+  "version": "0.3.1",
   "description": "",
   "type": "module",
   "author": "Tim Sprowl",
@@ -9,8 +9,14 @@
   "main": "src/index.js",
   "exports": {
     ".": "./src/index.js",
+    "./array": "./src/array.js",
+    "./find": "./src/find.js",
     "./fs": "./src/fs.js",
-    "./run": "./src/run.js"
+    "./math": "./src/math.js",
+    "./object": "./src/object.js",
+    "./promise": "./src/promise.js",
+    "./run": "./src/run.js",
+    "./time": "./src/time.js"
   },
   "scripts": {
     "test": "node --no-warnings --experimental-vm-modules node_modules/.bin/jest"

package/src/promise.js

@@ -1,38 +1,57 @@
 import { chunk } from "./array.js"
 
+export class PollError 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.
- * This will never resolve if callback always returns undefined, null, or false. I may add a "max attempt" or "timeout" option at some point.
- * @param {Function} callback
- * @param {number} milliseconds
- * @returns The result of the callback
+ * This will never resolve if callback always returns undefined, null, or false.
+ * @param {number} ms Milliseconds to wait between invocations
+ * @param {boolean|number=} wait If true, waits before initially calling the callback. If a number, waits that many milliseconds.
+ * @param {number=} attempts If a number, limits to that many invocations of callback before throwing a PollError.
+ * @param {Function} callback The argument is the number of times the callback has been called previously.
+ * @returns {any} The result of the callback
  */
-export function poll(callback, milliseconds) {
+export function poll({ ms, wait = false, attempts = undefined }, callback) {
   return new Promise((resolve, reject) => {
+    let attemptIndex = 0
     const resolver = async () => {
+      if (typeof attempts === "number" && attemptIndex >= attempts) {
+        reject(new PollError("max attempts reached"))
+        return
+      }
       try {
-        const result = await callback()
+        const result = await callback(attemptIndex)
+        attemptIndex++
         if (result !== undefined && result !== null && result !== false) {
           resolve(result)
         } else {
-          setTimeout(resolver, milliseconds)
+          setTimeout(resolver, ms)
         }
       } catch (error) {
         reject(error)
       }
     }
-    resolver()
+    if (typeof wait === "number") {
+      setTimeout(resolver, wait)
+    } else if (wait === true) {
+      setTimeout(resolver, ms)
+    } else {
+      resolver()
+    }
   })
 }
 
 /**
  * Sleep for X milliseconds.
- * @param {number} milliseconds
+ * @param {number} ms Milliseconds; returns immediately if negative
  */
-export async function sleep(milliseconds) {
+export async function sleep(ms) {
+  if (ms < 0) {
+    return
+  }
   await new Promise((resolve) => {
-    setTimeout(resolve, milliseconds)
+    setTimeout(resolve, ms)
   })
 }
 
@@ -47,12 +66,14 @@ export async function sleep(milliseconds) {
  *  - "errors": The "reason" property for each "result" object that did not have a status of "fulfilled".
  * @param {Object} $1
  * @param {Array} $1.array
- * @param {number=} $1.limit If not provided, each call is done in parallel.
+ * @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 before returning; useful if promises return arrays
  * @param {Function} callback
  * @returns {Object} {results, values, returned, errors}
  */
-export async function allSettled({ array, limit, flatten = false }, callback) {
+export async function allSettled({ array, limit, limiter, flatten = false }, callback) {
   const results = []
   let returned = []
   let values = []
@@ -71,6 +92,7 @@ export async function allSettled({ array, limit, flatten = false }, callback) {
         errors.push(reason)
       }
     }
+    await limiter?.(elements.length)
   }
   if (flatten) {
     values = values.flat()
@@ -79,6 +101,28 @@ export async function allSettled({ array, limit, flatten = false }, callback) {
   return { values, returned, errors, results }
 }
 
+/**
+ * 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.
+ * @param {Object} $1
+ * @param {number} $1.limit The maximum number of elements to be processed in the interval
+ * @param {Function=} $1.interval The length of the interval in milliseconds. Default is one minute.
+ * @returns {Function} Returned function expects to be called with the number of elements added since last call.
+ */
+export function intervalLimiter({ limit, interval = 1000 * 60 }) {
+  let count = 0
+  let startTimestamp = Date.now()
+  return async (added) => {
+    count += added
+    if (count >= limit) {
+      const currentTimestamp = Date.now()
+      await sleep(interval - (currentTimestamp - startTimestamp))
+      startTimestamp = Date.now()
+      count = 0
+    }
+  }
+}
+
 /**
  * A convenience method to throw the result of allSettled().
  * Useful in testing contexts when simply propagating the error is enough.

package/src/promise.test.js

@@ -2,14 +2,15 @@
 /* eslint-disable prefer-promise-reject-errors */
 import { jest } from "@jest/globals"
 
-const { poll, sleep, allSettled, alert, throwFirstReject } = await import("./promise.js")
+import { alert, allSettled, poll, PollError, sleep, throwFirstReject, intervalLimiter } from "./promise.js"
 
 describe("poll", () => {
   it("resolves immediately if callback returns a non-undefined/null/false value", async () => {
     const cb = jest.fn().mockReturnValue(42)
-    const promise = poll(cb, 1000)
+    const promise = poll({ ms: 1 }, cb)
     await expect(promise).resolves.toBe(42)
     expect(cb).toHaveBeenCalledTimes(1)
+    expect(cb).toHaveBeenCalledWith(0)
   })
 
   it("resolves after several attempts when callback returns undefined/null/false before a value", async () => {
@@ -19,23 +20,19 @@ describe("poll", () => {
       .mockReturnValueOnce(null)
       .mockReturnValueOnce(false)
       .mockReturnValueOnce(0)
-    const promise = poll(cb, 500)
-    // Advance timers for 3 unsuccessful attempts (undefined, null, false)
-    const before = Date.now()
-    // The fourth call returns 0, which should resolve
+    const promise = poll({ ms: 2 }, cb)
     await expect(promise).resolves.toBe(0)
-    const after = Date.now()
-    expect((after - before) / 1000).toBeCloseTo(1.5, 1)
     expect(cb).toHaveBeenCalledTimes(4)
+    expect(cb.mock.calls.map((args) => args[0])).toEqual([0, 1, 2, 3])
   })
 
   it('resolves if callback returns "" or NaN (should not treat as "keep polling")', async () => {
     const cb = jest.fn().mockReturnValueOnce("").mockReturnValueOnce(NaN)
-    const promise1 = poll(cb, 100)
+    const promise1 = poll({ ms: 1 }, cb)
     await expect(promise1).resolves.toBe("")
     expect(cb).toHaveBeenCalledTimes(1)
     cb.mockClear()
-    const promise2 = poll(cb, 100)
+    const promise2 = poll({ ms: 1 }, cb)
     await expect(promise2).resolves.toBe(NaN)
     expect(cb).toHaveBeenCalledTimes(1)
   })
@@ -45,26 +42,75 @@ describe("poll", () => {
     const cb = jest.fn().mockImplementation(() => {
       throw error
     })
-    await expect(poll(cb, 100)).rejects.toBe(error)
+    await expect(poll({ ms: 1 }, cb)).rejects.toBe(error)
     expect(cb).toHaveBeenCalledTimes(1)
   })
 
   it("rejects if callback returns a rejected promise", async () => {
     const error = new Error("async fail")
     const cb = jest.fn().mockReturnValue(Promise.reject(error))
-    const promise = poll(cb, 100)
+    const promise = poll({ ms: 1 }, cb)
     await expect(promise).rejects.toBe(error)
     expect(cb).toHaveBeenCalledTimes(1)
   })
+
+  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)
+  })
+
+  it("waits specified ms before first call if wait is a number", async () => {
+    const cb = jest.fn().mockReturnValue(1)
+    const promise = poll({ ms: 2, wait: 5 }, cb)
+    await sleep(4)
+    expect(cb).not.toHaveBeenCalled()
+    await sleep(2)
+    await expect(promise).resolves.toBe(1)
+    expect(cb).toHaveBeenCalledTimes(1)
+  })
+
+  it("rejects with PollError if attempts is reached", async () => {
+    const cb = jest.fn().mockReturnValue(undefined)
+    const promise = poll({ ms: 1, attempts: 3 }, cb)
+    await expect(promise).rejects.toBeInstanceOf(PollError)
+    await expect(promise).rejects.toThrow("max attempts reached")
+    expect(cb).toHaveBeenCalledTimes(3)
+    expect(cb.mock.calls.map((args) => args[0])).toEqual([0, 1, 2])
+  })
+
+  it("resolves if callback returns a value before reaching max attempts", async () => {
+    const cb = jest
+      .fn()
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(undefined)
+      .mockReturnValueOnce(5)
+    const promise = poll({ ms: 1, attempts: 5 }, cb)
+    await expect(promise).resolves.toBe(5)
+    expect(cb).toHaveBeenCalledTimes(3)
+    expect(cb.mock.calls.map((args) => args[0])).toEqual([0, 1, 2])
+  })
 })
 
 describe("sleep", () => {
   it("resolves after the specified milliseconds", async () => {
     const before = Date.now()
-    const promise = sleep(500)
+    const promise = sleep(5)
     await expect(promise).resolves.toBeUndefined()
     const after = Date.now()
-    expect((after - before) / 1000).toBeCloseTo(0.5, 1)
+    // Allow for some jitter
+    expect(after - before).toBeGreaterThanOrEqual(5)
+  })
+
+  it("resolves immediately if ms is negative", async () => {
+    const before = Date.now()
+    const promise = sleep(-10)
+    await expect(promise).resolves.toBeUndefined()
+    const after = Date.now()
+    expect(after - before).toBeLessThan(5)
   })
 })
 
@@ -116,6 +162,60 @@ describe("allSettled", () => {
     expect(result.errors).toEqual([])
     expect(result.results).toEqual([])
   })
+
+  it("calls limiter after each chunk if provided", async () => {
+    const arr = [1, 2, 3, 4, 5]
+    const calls = []
+    const limiterCalls = []
+    const cb = (x) => {
+      calls.push(x)
+      return x
+    }
+    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)
+    expect(result.values).toEqual([1, 2, 3, 4, 5])
+    expect(calls).toEqual([1, 2, 3, 4, 5])
+    expect(limiter).toHaveBeenCalledTimes(3)
+    expect(limiterCalls).toEqual([2, 2, 1])
+  })
+})
+
+describe("intervalLimiter", () => {
+  it("does not delay until limit is reached", async () => {
+    const limiter = intervalLimiter({ limit: 3, interval: 10 })
+    const before = Date.now()
+    await limiter(1)
+    await limiter(1)
+    await limiter(1) // should reach limit here, triggers wait
+    const after = Date.now()
+    expect(after - before).toBeGreaterThanOrEqual(10)
+  })
+
+  it("resets count and interval after waiting", async () => {
+    const limiter = intervalLimiter({ limit: 2, interval: 5 })
+    const before = Date.now()
+    await limiter(1)
+    await limiter(1) // triggers wait
+    const afterFirst = Date.now()
+    await limiter(1)
+    await limiter(1) // triggers wait again
+    const afterSecond = Date.now()
+    expect(afterFirst - before).toBeGreaterThanOrEqual(5)
+    expect(afterSecond - afterFirst).toBeGreaterThanOrEqual(5)
+  })
+
+  it("handles added < limit with no delay", async () => {
+    const limiter = intervalLimiter({ limit: 10, interval: 5 })
+    const before = Date.now()
+    await limiter(3)
+    await limiter(3)
+    const after = Date.now()
+    expect(after - before).toBeLessThan(5)
+  })
 })
 
 describe("alert", () => {
@@ -172,3 +272,12 @@ describe("throwFirstReject", () => {
     expect(result.returned).toEqual([])
   })
 })
+
+describe("PollError", () => {
+  it("is an Error subclass", () => {
+    const err = new PollError("oops")
+    expect(err).toBeInstanceOf(Error)
+    expect(err).toBeInstanceOf(PollError)
+    expect(err.message).toBe("oops")
+  })
+})