@tim-code/my-util 0.5.9 → 0.5.12

package/package.json

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

package/src/math.js

@@ -1,3 +1,5 @@
+import { ascending } from "./array.js"
+
 /**
  * Gives the remainder when the number is divided by modulus.
  * The sign of the remainder is always the same as the modulus i.e. mod(-1, 3) === 2 (not -1 as in -1 % 3).
@@ -128,7 +130,7 @@ export function formatPlus(number, { zero = false } = {}) {
  * Create an array of numbers progressing from start up to, but not including, end.
  * @param {number} start
  * @param {number=} end
- * @param {number=} step
+ * @param {number=} increment
  * @returns {number[]}
  */
 export function range(start, end, increment = 1) {
@@ -150,3 +152,33 @@ export function range(start, end, increment = 1) {
 export function isNumber(number) {
   return Number.isFinite(number)
 }
+
+/**
+ * Returns an object mapping quantile labels ("0", "10", ..., "100" for N = 10)
+ * to the corresponding element in the array at that percentile.
+ * @template T
+ * @param {T[]} array
+ * @param {Object} $1
+ * @param {number} $1.N How many quantiles
+ * @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.
+ * @returns {Object|undefined} Returns undefined is array is empty
+ */
+export function quantiles(array, { N, key, method = Math.round }) {
+  if (!(N > 0) || N % 1 !== 0) {
+    throw new Error("N must be a positive integer")
+  }
+  if (!array.length) {
+    return undefined
+  }
+  const sorted = [...array].sort(ascending(key))
+  const result = {}
+  for (let i = 0; i <= N; i++) {
+    const percentile = i / N
+    const percentileIndex = method(percentile * (sorted.length - 1))
+    const label = method(i * (100 / N))
+    result[label] = sorted[percentileIndex]
+  }
+  return result
+}

package/src/math.test.js

@@ -1,7 +1,17 @@
 import { describe, expect, it } from "@jest/globals"
-const { mod, formatPlus, line, sum, average, variance, range, isNumber } = await import(
-  "./math.js"
-)
+
+// EXPORTED FUNCTIONS UNDER TEST:
+// - mod
+// - line
+// - sum
+// - average
+// - variance
+// - formatPlus
+// - range
+// - isNumber
+// - quantiles
+const { mod, formatPlus, line, sum, average, variance, range, isNumber, quantiles } =
+  await import("./math.js")
 
 describe("mod", () => {
   it("returns n when n is less than m and n is non-negative", () => {
@@ -98,6 +108,7 @@ describe("line", () => {
     expect(f(1)).toBeNaN()
   })
 
+  // ISSUE: line() does not guard against identical points (x1===x2 and y1===y2), which yields NaN for all x. Consider throwing or documenting behavior for degenerate input.
   it("works with negative coordinates", () => {
     const f = line([-1, -2], [1, 2]) // slope 2
     expect(f(-1)).toBe(-2)
@@ -255,6 +266,8 @@ describe("formatPlus", () => {
     expect(formatPlus(Symbol("x"))).toBeUndefined()
     expect(formatPlus(NaN)).toBeUndefined()
   })
+
+  // ISSUE: formatPlus() treats any string not starting with "-" as positive, e.g. "+5" becomes "++5" and "abc" becomes "+abc". Consider handling leading "+" or non-numeric strings explicitly.
 })
 
 describe("range", () => {
@@ -330,3 +343,115 @@ describe("isNumber", () => {
     expect(isNumber(() => 1)).toBe(false)
   })
 })
+
+describe("quantiles", () => {
+  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 })
+    for (let i = 0; i <= 10; i++) {
+      expect(result[i * 10]).toBe(i)
+    }
+  })
+
+  it("sorts the input before selecting percentiles", () => {
+    const arr = [9, 7, 5, 3, 1, 2, 4, 6, 8, 0, 10]
+    const result = quantiles(arr, { N: 10 })
+    for (let i = 0; i <= 10; i++) {
+      expect(result[i * 10]).toBe(i)
+    }
+  })
+
+  it("supports a string key to select values for percentile positions", () => {
+    const arr = [
+      { v: 9 },
+      { v: 7 },
+      { v: 5 },
+      { v: 3 },
+      { v: 1 },
+      { v: 2 },
+      { v: 4 },
+      { v: 6 },
+      { v: 8 },
+      { v: 0 },
+      { v: 10 },
+    ]
+    const result = quantiles(arr, { N: 10, key: "v" })
+    for (let i = 0; i <= 10; i++) {
+      expect(result[i * 10].v).toBe(i)
+    }
+  })
+
+  it("supports a key function", () => {
+    const arr = [
+      { n: 90 },
+      { n: 70 },
+      { n: 50 },
+      { n: 30 },
+      { n: 10 },
+      { n: 20 },
+      { n: 40 },
+      { n: 60 },
+      { n: 80 },
+      { n: 0 },
+      { n: 100 },
+    ]
+    const result = quantiles(arr, { N: 10, key: (el) => el.n })
+    for (let i = 0; i <= 10; i++) {
+      expect(result[i * 10].n).toBe(i * 10)
+    }
+  })
+
+  it("respects a custom method (Math.floor) for fractional indices (N=10)", () => {
+    const arr = Array.from({ length: 10 }, (_, i) => i) // 0..9
+    const defaultResult = quantiles(arr, { N: 10 }) // uses Math.round
+    const floorResult = quantiles(arr, { N: 10, method: Math.floor })
+    expect(defaultResult[50]).toBe(5) // round(0.5 * 9) = 5
+    expect(floorResult[50]).toBe(4) // floor(0.5 * 9) = 4
+  })
+
+  it("handles arrays of length 1 by returning that element for all deciles", () => {
+    const arr = [42]
+    const result = quantiles(arr, { N: 10 })
+    for (let i = 0; i <= 10; i++) {
+      expect(result[i * 10]).toBe(42)
+    }
+  })
+
+  it("supports quartiles (N=4) with expected labels 0,25,50,75,100", () => {
+    const arr = Array.from({ length: 9 }, (_, i) => i) // 0..8
+    const result = quantiles(arr, { N: 4 })
+    expect(result[0]).toBe(0) // index round(0 * 8)   = 0
+    expect(result[25]).toBe(2) // index round(0.25* 8) = 2
+    expect(result[50]).toBe(4) // index round(0.5 * 8) = 4
+    expect(result[75]).toBe(6) // index round(0.75* 8) = 6
+    expect(result[100]).toBe(8) // index round(1   * 8) = 8
+  })
+
+  it("supports tertiles (N=3) and label rounding to 33 and 67", () => {
+    const arr = Array.from({ length: 11 }, (_, i) => i) // 0..10
+    const result = quantiles(arr, { N: 3 }) // labels via round(i*(100/3)) => 0,33,67,100
+    expect(result[0]).toBe(0) // round(0/3 * 10)  = 0
+    expect(result[33]).toBe(3) // round(1/3 * 10)  = 3
+    expect(result[67]).toBe(7) // round(2/3 * 10)  = 7
+    expect(result[100]).toBe(10) // round(1   * 10)  = 10
+  })
+
+  it("respects a custom method (Math.floor) for fractional indices when N != 10", () => {
+    const arr = Array.from({ length: 10 }, (_, i) => i) // 0..9
+    const defaultResult = quantiles(arr, { N: 4 }) // uses Math.round
+    const floorResult = quantiles(arr, { N: 4, method: Math.floor })
+    expect(defaultResult[50]).toBe(5) // round(0.5 * 9) = 5
+    expect(floorResult[50]).toBe(4) // floor(0.5 * 9) = 4
+  })
+
+  it("returns undefined for empty array", () => {
+    expect(quantiles([], { N: 4 })).toBeUndefined()
+  })
+
+  it("throws if N is negative or not an integer", () => {
+    expect(() => quantiles([1, 2, 3], {})).toThrow("N must be a positive integer")
+    expect(() => quantiles([1, 2, 3], { N: -1 })).toThrow("N must be a positive integer")
+    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")
+  })
+})

package/src/promise.js

@@ -72,12 +72,12 @@ export async function sleep(ms) {
  * @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
+ * @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 },
-  callback
+  callback = (promise) => promise
 ) {
   const results = []
   let returned = []

package/src/promise.test.js

@@ -132,6 +132,15 @@ describe("allSettled", () => {
     expect(result.results.every((r) => r.status === "fulfilled")).toBe(true)
   })
 
+  it("returns correct structure for all fulfilled", async () => {
+    const arr = [Promise.resolve(1), Promise.resolve(2), Promise.resolve(3)]
+    const result = await allSettled({ array: arr })
+    expect(result.values).toEqual([1, 2, 3])
+    expect(result.returned).toEqual([1, 2, 3])
+    expect(result.errors).toEqual([])
+    expect(result.results.every((r) => r.status === "fulfilled")).toBe(true)
+  })
+
   it("handles rejected promises and collects errors", async () => {
     const arr = [1, 2, 3]
     const cb = (x) => (x === 2 ? Promise.reject("fail") : x + 1)