@tim-code/my-util 0.5.14 → 0.6.0

package/package.json

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

package/src/array.js

@@ -5,7 +5,7 @@
  * @param {Iterable} iterable
  * @param {number=} chunkSize If not provided, returns an array consisting of one chunk, which has all the elements of input iterable.
  *  This has the same effect as passing a chunk size that is greater than the number of elements in the iterable.
- * @returns {Array}
+ * @returns {Array<Array>}
  */
 export function chunk(iterable, chunkSize = Infinity) {
   if (chunkSize !== Infinity && (chunkSize <= 0 || !Number.isInteger(chunkSize))) {

package/src/find.js

@@ -181,7 +181,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.
+ *  "~" and "" are good cutoff string values for gt/gte and lt/lte respectively.
  * @template T, V
  * @param {Array<T>} array
  * @param {V} value The desired value to search for
@@ -191,8 +191,8 @@ export function findClosestGTE(array, desired, { key, cutoff = Infinity } = {})
  *  If a function, called with the element, index and array (same as .map() callback) to produce the value to sort on.
  * @param {string=} options.comparator "diff", "lt", "lte", "gt", "gte", "eq". Default is "diff" which implies T is number.
  * @param {V=} options.cutoff If specified, sets a initial constraint on how close the found value must be.
- *  If used with lt, lte, value must be greater than or equal to cutoff.
- *  If used with gt, gte, value must be less than or equal to cutoff.
+ *  If used with lt/lte, value must be greater than or equal to cutoff.
+ *  If used with gt/gte, value must be less than or equal to cutoff.
  *  If used with diff, value's difference with desired must be less than or equal to cutoff.
  *  No effect with eq.
  * @returns {T|undefined}

package/src/math.js

@@ -14,8 +14,8 @@ export function mod(number, modulus) {
 /**
  * Given two points, returns a function
  * This function, given an "x" value, returns a "y" value that is on the same line as the first two points.
- * @param {[number, number]} firstPoint
- * @param {[number, number]} secondPoint
+ * @param {[number, number]} point1
+ * @param {[number, number]} point2
  * @returns {Function}
  */
 export function line([x1, y1], [x2, y2]) {
@@ -29,8 +29,8 @@ export function line([x1, y1], [x2, y2]) {
  * Calculate the sum of values in an array.
  * @template T
  * @param {Array<T>} array
- * @param {Object} [options]
- * @param {string|number|((element: T, index: number, array: Array<T>) => number)=} options.key
+ * @param {Object} $1
+ * @param {string|number|Function=} $1.key Can specify a key of the object or a function.
  * @returns {number}
  */
 export function sum(array, { key } = {}) {
@@ -55,8 +55,8 @@ export function sum(array, { key } = {}) {
  * Calculate the average (mean) of values in an array.
  * @template T
  * @param {Array<T>} array
- * @param {Object} [options]
- * @param {string|number|((element: T, index: number, array: Array<T>) => number)=} options.key
+ * @param {Object} $1
+ * @param {string|number|Function=} $1.key Can specify a key of the object or a function.
  * @returns {number}
  * @throws {Error} If the array is empty.
  */
@@ -71,8 +71,8 @@ export function average(array, { key } = {}) {
  * Calculate the variance of values in an array.
  * @template T
  * @param {Array<T>} array
- * @param {Object} [options]
- * @param {string|number|((element: T, index: number, array: Array<T>) => number)=} options.key
+ * @param {Object} $1
+ * @param {string|number|Function=} $1.key Can specify a key of the object or a function.
  * @returns {number}
  * @throws {Error} If the array is empty.
  */
@@ -145,7 +145,8 @@ export function range(start, end, increment = 1) {
 }
 
 /**
- * Check if the argument is a number (typeof is "number" and not NaN).
+ * Check if the argument is a number.
+ * This excludes Infinity and NaN, but otherwise is equivalent to `typeof number === "number"`.
  * @param {any} number
  * @returns {boolean}
  */
@@ -163,9 +164,11 @@ export function isNumber(number) {
  * @param {string|number|Function=} $1.key Can specify a key of the object to sort on or a function.
  * @param {Function=} $1.method Method to use to choose which element when the percentile index is a fractional value.
  *  Default is Math.round.
+ * @param {Function=} $.labeller Function that returns a quantile label given a fractional value (i.e. 33.3...).
+ *  Default is Math.round.
  * @returns {Object|undefined} Returns undefined is array is empty
  */
-export function quantiles(array, { N, key, method = Math.round }) {
+export function quantiles(array, { N, key, method = Math.round, labeller = Math.round }) {
   if (!(N > 0) || !Number.isInteger(N)) {
     throw new Error("N must be a positive integer")
   }
@@ -177,7 +180,7 @@ export function quantiles(array, { N, key, method = Math.round }) {
   for (let i = 0; i <= N; i++) {
     const percentile = i / N
     const percentileIndex = method(percentile * (sorted.length - 1))
-    const label = method(i * (100 / N))
+    const label = labeller(i * (100 / N))
     result[label] = sorted[percentileIndex]
   }
   return result

package/src/math.test.js

@@ -345,6 +345,9 @@ describe("isNumber", () => {
 })
 
 describe("quantiles", () => {
+  // ISSUE: JSDoc for labeller parameter uses "$.labeller" instead of "$1.labeller", which is inconsistent with the other params.
+  // ISSUE: If labeller maps multiple percent values to the same label, later entries overwrite earlier ones without warning.
+
   it("maps 0..100 deciles for an already sorted array of length 11 (default rounding)", () => {
     const arr = Array.from({ length: 11 }, (_, i) => i)
     const result = quantiles(arr, { N: 10 })
@@ -454,4 +457,24 @@ describe("quantiles", () => {
     expect(() => quantiles([1, 2, 3], { N: 0 })).toThrow("N must be a positive integer")
     expect(() => quantiles([1, 2, 3], { N: 2.5 })).toThrow("N must be a positive integer")
   })
+
+  it("supports a custom labeller (Math.floor) independent of the index method", () => {
+    const arr = Array.from({ length: 11 }, (_, i) => i) // 0..10
+    const result = quantiles(arr, { N: 3, labeller: Math.floor }) // labels 0,33,66,100
+    expect(result[0]).toBe(0)
+    expect(result[33]).toBe(3) // index still uses default Math.round
+    expect(result[66]).toBe(7) // label differs from default (which would be 67)
+    expect(result[100]).toBe(10)
+  })
+
+  it("supports a custom labeller that produces string labels", () => {
+    const arr = Array.from({ length: 9 }, (_, i) => i) // 0..8
+    const labeller = (p) => `Q${Math.round(p / 25)}`
+    const result = quantiles(arr, { N: 4, labeller })
+    expect(result.Q0).toBe(0)
+    expect(result.Q1).toBe(2)
+    expect(result.Q2).toBe(4)
+    expect(result.Q3).toBe(6)
+    expect(result.Q4).toBe(8)
+  })
 })

package/src/object.js

@@ -10,7 +10,8 @@ export function isObject(thing) {
 /**
  * Creates a new object with values created by calling callback on each of argument's values.
  * @param {Object} object
- * @param {Function} callback (value, key, object) => newValue // note if not changing value, should return value
+ * @param {Function} callback (value, key, object) => newValue
+ *  Note if not changing value, should return value.
  * @returns {Object}
  */
 export function mapValues(object, callback) {
@@ -25,7 +26,8 @@ export function mapValues(object, callback) {
 /**
  * Mutates the passed in object by calling callback on each of its values.
  * @param {Object} object
- * @param {Function} callback (value, key, object) => newValue // note if not changing value, should return value
+ * @param {Function} callback (value, key, object) => newValue
+ *  Note if not changing value, should return value.
  * @returns {Object}
  */
 export function mutateValues(object, callback) {
@@ -83,6 +85,7 @@ export function like(template) {
 /**
  * Copies the source recursively.
  * Does not preserve constructors of source or constructors of its keys' values.
+ * Preserves distinction between an array and an object i.e. `[1]` and `{"0": 1}`.
  * @template T
  * @param {T} source
  * @returns {T}
@@ -105,9 +108,9 @@ export function deepCopy(source) {
  *    the source object's value is a non-array object, recursively merges the source into the target.
  *  Otherwise, assigns source's key's value into the target's key.
  * This means that arrays are never merged into arrays or other objects.
- * @param {Object} target The target object that will receive the merged properties.
- * @param {...Object} sources The source objects whose properties will be merged into the target.
- * @returns {Object} The target object with the merged properties from all source objects.
+ * @param {Object} target The target object that will receive the merged properties
+ * @param {...Object} sources The source objects whose properties will be merged into the target
+ * @returns {Object} The target object with the merged properties from all source objects
  */
 export function deepMerge(target, ...sources) {
   for (const source of sources) {
@@ -136,7 +139,7 @@ export function deepMerge(target, ...sources) {
 
 /**
  * Merges a deep copy of each source object into target. See deepCopy() and deepMerge() documentation for caveats.
- * @param {Object} target The target object that will receive the merged properties.
+ * @param {Object} target The target object that will receive the merged properties
  * @param {...Object} sources The source objects whose properties will be merged into the returned object
  * @returns {Object}
  */
@@ -151,11 +154,11 @@ export function deepMergeCopy(target, ...sources) {
  * Objects and arrays are compared recursively by their properties and elements.
  * Primitives are compared with strict equality.
  * Caveats:
- *  Does not check class: [1] is considered equal to {0: 1}.
- *  Any Symbol keys in the arguments are ignored (Object.keys only returns string keys).
- * @param {any} a The first value to compare.
- * @param {any} b The second value to compare.
- * @returns {boolean} True if the values are deeply equal, false otherwise.
+ *  Does not check class: `[1]` is considered equal to `{"0": 1}`.
+ *  Any `Symbol` keys in the arguments are ignored (Object.keys only returns string keys).
+ * @param {any} a The first value to compare
+ * @param {any} b The second value to compare
+ * @returns {boolean} True if the values are deeply equal, false otherwise
  */
 export function deepEqual(a, b) {
   if (a === b) {

package/src/promise.js

@@ -59,35 +59,36 @@ export async function sleep(ms) {
  * Parallelize executions of a function using `Promise.allSettled()`.
  * This is useful because usually you want to set a limit to the number of parallel requests possible at once.
  * The output of this function contains the outcome of each call of the callback in a variety of formats.
- *  - "results": Essentially the return value from Promise.allSettled().
+ *  - "results": An array with the same elements as returned by Promise.allSettled().
  *  - "values": The "value" property of each "result" object returned from allSettled(); this will be undefined if the associated promise rejects.
  *  - "returned": The "value" property for each "result" object where the "status" property has a value of fulfilled.
  *     This is arguably more useful than "values" unless you need to be able to index into the array based on the index of the promise.
  *  - "errors": The "reason" property for each "result" object that did not have a status of "fulfilled".
  * @param {Object} $1
- * @param {Array} $1.array
+ * @param {Iterable} $1.array
+ * @param {Iterable=} $1.iterable An alternative, more accurate property name for specifying "array"
  * @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 {boolean=} $1.flatten Flattens "values" and "returned" 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 Default is identity function to enable passing promises as "array".
  * @returns {Object} {results, values, returned, errors}
  */
 export async function allSettled(
-  { array, limit, limiter, flatten = false, abort = false },
+  { array, iterable = array, limit, limiter, flatten = false, abort = false },
   callback = (promise) => promise
 ) {
   const results = []
   let returned = []
   let values = []
   const errors = []
-  const chunked = chunk(array, limit)
+  const chunked = chunk(iterable, limit)
   for (const elements of chunked) {
     const promises = elements.map(callback)
-    const _results = await Promise.allSettled(promises)
-    for (const result of _results) {
+    const chunkResults = await Promise.allSettled(promises)
+    for (const result of chunkResults) {
       const { value, status, reason } = result
       results.push(result)
       values.push(value)

package/src/promise.test.js

@@ -1,6 +1,11 @@
 /* eslint-disable prefer-promise-reject-errors */
 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)
+
 import {
   alert,
   allSettled,
@@ -214,6 +219,20 @@ describe("allSettled", () => {
     expect(cb).toHaveBeenCalledTimes(2)
     // Should not process [3,4] or [5,6]
   })
+
+  it("accepts non-Array iterable via iterable option (Map)", async () => {
+    const map = new Map([
+      ["a", 1],
+      ["b", 2],
+      ["c", 3],
+    ])
+    const cb = ([k, v]) => `${k}:${v * 2}`
+    const result = await allSettled({ iterable: map, limit: 2 }, cb)
+    expect(result.values).toEqual(["a:2", "b:4", "c:6"])
+    expect(result.returned).toEqual(["a:2", "b:4", "c:6"])
+    expect(result.errors).toEqual([])
+    expect(result.results.every((r) => r.status === "fulfilled")).toBe(true)
+  })
 })
 
 describe("intervalLimiter", () => {

package/src/time.js

@@ -5,13 +5,13 @@ import { mod } from "./math.js"
  * @param {Object} $1
  * @param {boolean=} $1.floorMinute If true, floors to the nearest minute. If false, floors to the nearest second.
  * @param {number=} $1.timestamp Unix timestamp to use instead of current time.
- * @param {string=} $1.timezone Timezone to use instead of Eastern time.
+ * @param {string=} $1.timeZone Time zone to use instead of Eastern time. A falsy value corresponds to local time.
  * @returns {Object} { timestamp, date: YYYY-MM-DD, time: HH:mm:ss }
  */
 export function getEasternTime({
   floorMinute = false,
   timestamp = undefined,
-  timezone = "America/New_York",
+  timeZone = "America/New_York",
 } = {}) {
   if (!timestamp) {
     timestamp = new Date().getTime() / 1000
@@ -19,7 +19,7 @@ export function getEasternTime({
   timestamp = floorMinute ? Math.floor(timestamp / 60) * 60 : Math.floor(timestamp)
   // 'en-CA' (English - Canada) formats dates as YYYY-MM-DD and times in 24-hour format by default
   const string = new Date(timestamp * 1000).toLocaleString("en-CA", {
-    ...(timezone ? { timeZone: timezone } : {}),
+    ...(timeZone ? { timeZone } : {}),
     hour12: false,
     year: "numeric",
     month: "2-digit",
@@ -37,11 +37,11 @@ export function getEasternTime({
  * @param {Object} $1
  * @param {boolean=} $1.floorMinute If true, floors to the nearest minute. If false, floors to the nearest second.
  * @param {number=} $1.timestamp Unix timestamp to use instead of current time.
- * @param {string=} $1.timezone Timezone to use instead of local time. undefined corresponds to "America/New_York" and "" (falsy) corresponds to local time.
+ * @param {string=} $1.timeZone Time zone to use instead of local time. A falsy value (default) corresponds to local time.
  * @returns {Object} { timestamp, date, time, minute, datetime }
  */
-export function getTime({ floorMinute, timestamp, timezone = "" } = {}) {
-  return getEasternTime({ floorMinute, timestamp, timezone })
+export function getTime({ floorMinute, timestamp, timeZone = false } = {}) {
+  return getEasternTime({ floorMinute, timestamp, timeZone })
 }
 
 /**
@@ -82,7 +82,7 @@ export function getMinute(time) {
  * @param {string} string
  * @returns {boolean}
  */
-export function isDate(string) {
+export function isDateString(string) {
   const match = /^(\d{4})-(0[1-9]|1[0-2])-(0[1-9]|[12]\d|3[01])$/u.exec(string)
   if (!match) {
     return false
@@ -96,15 +96,33 @@ export function isDate(string) {
   )
 }
 
+/**
+ * @deprecated Prefer isDateString()
+ * @param {string} string
+ * @returns {boolean}
+ */
+export function isDate(string) {
+  return isDateString(string)
+}
+
 /**
  * Checks if the string represent a valid HH:mm:ss time.
  * @param {string} string
  * @returns {boolean}
  */
-export function isTime(string) {
+export function isTimeString(string) {
   return /^([01]\d|2[0-3]):[0-5]\d:[0-5]\d$/u.test(string)
 }
 
+/**
+ * @deprecated Prefer isTimeString()
+ * @param {string} string
+ * @returns {boolean}
+ */
+export function isTime(string) {
+  return isTimeString(string)
+}
+
 /**
  * Checks if a number is a Unix timestamp (i.e. in seconds).
  * Would not validate timestamps set very far into the future.
@@ -173,7 +191,8 @@ export function getTimeRange(start, end, { hours = 0, minutes = 1 } = {}) {
 /**
  * Adds a number of days to a date string.
  * @param {string} dateString YYYY-MM-DD
- * @param {number} days
+ * @param {Object} $1
+ * @param {number} $1.days
  * @returns {string}
  */
 export function addDays(dateString, { days = 0 } = {}) {

package/src/time.test.js

@@ -4,14 +4,15 @@ import {
   addTime,
   getDateRange,
   getDayIndexInWeek,
-  // getDayOfWeek, // removed, replaced by getDayIndexInWeek
   getEasternTime,
   getMinute,
   getStartOfWeek,
   getTime,
   getTimeRange,
   isDate,
+  isDateString,
   isTime,
+  isTimeString,
   isUnixTimestamp,
   today,
 } from "./time.js"
@@ -54,15 +55,15 @@ describe("getEasternTime", () => {
     expect(def.timestamp).toEqual(explicit.timestamp)
   })
 
-  test("respects timezone parameter", () => {
+  test("respects timeZone parameter", () => {
     // 2024-06-01T12:34:56Z (UTC)
     const ts = 1717245296
     // New York (EDT, UTC-4)
-    const eastern = getEasternTime({ timestamp: ts, timezone: "America/New_York" })
+    const eastern = getEasternTime({ timestamp: ts, timeZone: "America/New_York" })
     // Los Angeles (PDT, UTC-7)
-    const pacific = getEasternTime({ timestamp: ts, timezone: "America/Los_Angeles" })
+    const pacific = getEasternTime({ timestamp: ts, timeZone: "America/Los_Angeles" })
     // UTC
-    const utc = getEasternTime({ timestamp: ts, timezone: "UTC" })
+    const utc = getEasternTime({ timestamp: ts, timeZone: "UTC" })
     expect(eastern.time).not.toBe(pacific.time)
     expect(eastern.time).not.toBe(utc.time)
     expect(pacific.time).not.toBe(utc.time)
@@ -71,11 +72,11 @@ describe("getEasternTime", () => {
     expect(utc.time.startsWith("12:34")).toBe(true) // UTC
   })
 
-  test("returns local time if timezone is empty string", () => {
-    // If timezone is falsy (""), should use local time zone
+  test("returns local time if timeZone is empty string", () => {
+    // If timeZone is falsy (""), should use local time zone
     // We'll compare to Date.toLocaleString with no timeZone option
     const ts = 1717245296
-    const local = getEasternTime({ timestamp: ts, timezone: "" })
+    const local = getEasternTime({ timestamp: ts, timeZone: "" })
     const expected = new Date(ts * 1000).toLocaleString("en-US", {
       hour12: false,
       year: "numeric",
@@ -141,8 +142,8 @@ describe("getTime", () => {
     expect(result).not.toHaveProperty("datetime")
   })
 
-  test("defaults to local time if timezone is not provided", () => {
-    // getTime({}) should use timezone = false, which disables the timeZone option and uses local
+  test("defaults to local time if timeZone is not provided", () => {
+    // getTime({}) should use timeZone = false, which disables the timeZone option and uses local
     const ts = 1717245296
     const local = getTime({ timestamp: ts })
     const expected = new Date(ts * 1000).toLocaleString("en-US", {
@@ -161,11 +162,11 @@ describe("getTime", () => {
     expect(local.time).toBe(time)
   })
 
-  test("passes timezone through to getEasternTime", () => {
-    // Should match getEasternTime with same timezone
+  test("passes timeZone through to getEasternTime", () => {
+    // Should match getEasternTime with same timeZone
     const ts = 1717245296
-    const pacific = getTime({ timestamp: ts, timezone: "America/Los_Angeles" })
-    const ref = getEasternTime({ timestamp: ts, timezone: "America/Los_Angeles" })
+    const pacific = getTime({ timestamp: ts, timeZone: "America/Los_Angeles" })
+    const ref = getEasternTime({ timestamp: ts, timeZone: "America/Los_Angeles" })
     expect(pacific).toEqual(ref)
   })
 
@@ -208,7 +209,7 @@ describe("getDayIndexInWeek", () => {
 
   test("throws on invalid date strings", () => {
     expect(() => getDayIndexInWeek("not-a-date")).toThrow(/invalid date/u)
-    // don't worry about bad dates like the following; can be caught with isDate()
+    // don't worry about bad dates like the following; can be caught with isDateString()
     expect(getDayIndexInWeek("2024-02-31")).toBe(6)
   })
 })
@@ -234,7 +235,19 @@ describe("getMinute", () => {
   })
 })
 
-describe("isDate", () => {
+describe("isDateString", () => {
+  test("validates correct dates", () => {
+    expect(isDateString("2024-06-01")).toBe(true)
+    expect(isDateString("1999-12-31")).toBe(true)
+  })
+
+  test("rejects invalid dates and formats", () => {
+    expect(isDateString("2024-02-31")).toBe(false)
+    expect(isDateString("2024/06/01")).toBe(false)
+  })
+})
+
+describe("isDate (deprecated wrapper)", () => {
   test("returns true for valid YYYY-MM-DD dates", () => {
     expect(isDate("2024-06-01")).toBe(true)
     expect(isDate("1999-12-31")).toBe(true)
@@ -266,7 +279,19 @@ describe("isDate", () => {
   })
 })
 
-describe("isTime", () => {
+describe("isTimeString", () => {
+  test("validates correct times", () => {
+    expect(isTimeString("00:00:00")).toBe(true)
+    expect(isTimeString("23:59:59")).toBe(true)
+  })
+
+  test("rejects invalid times and formats", () => {
+    expect(isTimeString("24:00:00")).toBe(false)
+    expect(isTimeString("12:34")).toBe(false)
+  })
+})
+
+describe("isTime (deprecated wrapper)", () => {
   test("returns true for valid HH:mm:ss times", () => {
     expect(isTime("00:00:00")).toBe(true)
     expect(isTime("23:59:59")).toBe(true)