@tim-code/my-util 0.5.8 → 0.5.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.5.8",
+  "version": "0.5.11",
   "description": "",
   "type": "module",
   "author": "Tim Sprowl",
@@ -29,7 +29,7 @@
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
-    "@tim-code/eslint-config": "^1.3.3",
+    "@tim-code/eslint-config": "^1.4.0",
     "jest": "^29.7.0"
   },
   "jest": {

package/src/array.js

@@ -186,17 +186,16 @@ export function multilevel(...comparators) {
   }
 }
 
-function siftDown(heap, i, compare) {
-  const n = heap.length
+function siftDown(heap, i, compare, length) {
   // eslint-disable-next-line no-constant-condition
   while (true) {
     const left = 2 * i + 1
     const right = left + 1
     let largest = i
-    if (left < n && compare(heap[left], heap[largest]) > 0) {
+    if (left < length && compare(heap[left], heap[largest]) > 0) {
       largest = left
     }
-    if (right < n && compare(heap[right], heap[largest]) > 0) {
+    if (right < length && compare(heap[right], heap[largest]) > 0) {
       largest = right
     }
     if (largest === i) {
@@ -209,11 +208,11 @@ function siftDown(heap, i, compare) {
   }
 }
 
-function maxHeapify(heap, compare) {
+function maxHeapify(heap, compare, length) {
   // (heap.length >>> 1) is equivalent to Math.floor(heap.length / 2)
   // eslint-disable-next-line no-bitwise
-  for (let i = (heap.length >>> 1) - 1; i >= 0; i--) {
-    siftDown(heap, i, compare)
+  for (let i = (length >>> 1) - 1; i >= 0; i--) {
+    siftDown(heap, i, compare, length)
   }
 }
 
@@ -222,34 +221,50 @@ function maxHeapify(heap, compare) {
  * @template T
  * @param {Array<T>} array
  * @param {Object} $1
- * @param {number} $1.N Number of elements to return
+ * @param {number} $1.N Number of elements to return; must be a nonnegative integer
  * @param {Function=} $1.compare Sort function. Default is ascending sort.
  * @param {boolean=} $1.unsorted If true, returns the final result in heap order, not sorted order, as an optimization.
  *  Default is false.
  * @param {boolean=} $1.force If true, will force heap-based method for small N instead of more efficient "normal" way.
  *  Default is false.
+ * @param {boolean=} $1.mutate If true, will mutate the original array rather than copy it.
  * @returns {Array<T>}
  */
-export function sortN(array, { N, compare = ascending(), unsorted = false, force = false }) {
-  if (!(N > 0)) {
+export function sortN(
+  array,
+  { N, compare = ascending(), unsorted = false, force = false, mutate = false }
+) {
+  if (!(N >= 0) || N % 1 !== 0) {
+    throw new Error("N must be a nonnegative integer")
+  }
+  if (N === 0) {
+    if (mutate) {
+      array.length = 0
+      return array
+    }
     return []
   }
   if (N >= array.length) {
-    return [...array].sort(compare)
+    return (mutate ? array : [...array]).sort(compare)
   }
   if (!force && array.length <= 100 && N / array.length >= 0.1) {
     // seems to be faster to do it the "normal" way in this case
-    return [...array].sort(compare).slice(0, N)
+    const sorted = (mutate ? array : [...array]).sort(compare)
+    sorted.length = N
+    return sorted
   }
-  const heap = array.slice(0, N)
-  maxHeapify(heap, compare)
+  const heap = mutate ? array : array.slice(0, N)
+  maxHeapify(heap, compare, N)
   for (let i = N; i < array.length; i++) {
     const element = array[i]
     if (compare(element, heap[0]) < 0) {
       heap[0] = element
-      siftDown(heap, 0, compare)
+      siftDown(heap, 0, compare, N)
     }
   }
+  if (mutate) {
+    heap.length = N
+  }
   if (unsorted) {
     return heap
   }

package/src/array.test.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-restricted-syntax */
 import { describe, expect, it, jest } from "@jest/globals"
 
 const { chunk, unique, duplicates, ascending, descending, multilevel, sortN } = await import(
@@ -515,7 +514,12 @@ describe("multilevel", () => {
 describe("sortN", () => {
   it("returns empty array when N <= 0", () => {
     expect(sortN([1, 2, 3], { N: 0, force: true })).toEqual([])
-    expect(sortN([1, 2, 3], { N: -5, force: true })).toEqual([])
+    expect(() => sortN([1, 2, 3], { N: -5, force: true })).toThrow(
+      /N must be a nonnegative integer/u
+    )
+    expect(() => sortN([1, 2, 3], { N: 1.5, force: true })).toThrow(
+      /N must be a nonnegative integer/u
+    )
   })
 
   it("returns the entire array sorted when N >= array.length and does not mutate original", () => {
@@ -526,7 +530,7 @@ describe("sortN", () => {
     expect(result).not.toBe(arr)
   })
 
-  it("returns the first N smallest elements (default ascending comparator)", () => {
+  it("returns the first N smallest elements (default ascending comparator, heap path)", () => {
     expect(sortN([5, 1, 3, 2, 4], { N: 3, force: true })).toEqual([1, 2, 3])
     expect(sortN([3, 1, 3, 2, 2], { N: 4, force: true })).toEqual([1, 2, 2, 3])
   })
@@ -542,14 +546,88 @@ describe("sortN", () => {
     expect(out.map((o) => o.v)).toEqual([1, 2, 3])
   })
 
-  it("does not mutate the original array when N < array.length", () => {
+  it("does not mutate the original array when N < array.length (heap path)", () => {
     const arr = [5, 1, 3, 2, 4]
     const out = sortN(arr, { N: 3, force: true })
     expect(out).toEqual([1, 2, 3])
     expect(arr).toEqual([5, 1, 3, 2, 4])
   })
 
-  it("returns the first N smallest elements (default ascending comparator)", () => {
+  it("returns the N elements in heap order when unsorted=true (heap path)", () => {
     expect(sortN([10, 1, 7, 3, 5], { N: 3, force: true, unsorted: true })).toEqual([5, 1, 3])
   })
+
+  it("uses the 'normal' sort+truncate path when force=false and does not mutate original", () => {
+    const arr = [4, 2, 5, 1, 3] // small array and N/len >= 0.1 -> normal path
+    const out = sortN(arr, { N: 2 })
+    expect(out).toEqual([1, 2])
+    expect(arr).toEqual([4, 2, 5, 1, 3])
+    expect(out).not.toBe(arr)
+  })
+})
+
+describe("sortN mutate", () => {
+  it("returns empty array when N <= 0", () => {
+    const a = [1, 2, 3]
+    const result = sortN(a, { N: 0, force: true, mutate: true })
+    expect(a).toEqual([])
+    expect(result).toBe(a)
+    const b = [1, 2, 3]
+    expect(() => sortN(b, { N: -5, force: true, mutate: true })).toThrow(
+      /N must be a nonnegative integer/u
+    )
+    expect(() => sortN(b, { N: -1.5, force: true, mutate: true })).toThrow(
+      /N must be a nonnegative integer/u
+    )
+  })
+
+  it("returns the entire array sorted when N >= array.length", () => {
+    const array = [3, 1, 2]
+    const result = sortN(array, { N: 10, force: true, mutate: true })
+    expect(array).toEqual([1, 2, 3])
+    expect(result).toBe(array)
+  })
+
+  it("returns the first N smallest elements and mutates in-place (heap path)", () => {
+    const arr = [5, 1, 3, 2, 4]
+    const out = sortN(arr, { N: 3, force: true, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr).toEqual([1, 2, 3])
+  })
+
+  it("respects a descending comparator and mutates in-place (heap path)", () => {
+    const arr = [5, 1, 3, 2, 4]
+    const out = sortN(arr, { N: 2, compare: descending(), force: true, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr).toEqual([5, 4])
+  })
+
+  it("works with key-based comparator, mutating and truncating in-place (heap path)", () => {
+    const arr = [{ v: 3 }, {}, { v: 1 }, { v: null }, { v: 2 }, { v: undefined }]
+    const out = sortN(arr, { N: 3, compare: ascending("v"), force: true, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr.length).toBe(3)
+    expect(out.map((o) => o.v)).toEqual([1, 2, 3])
+  })
+
+  it("mutates the original array when mutate=true and N < array.length (heap path)", () => {
+    const arr = [5, 1, 3, 2, 4]
+    const out = sortN(arr, { N: 3, force: true, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr).toEqual([1, 2, 3])
+  })
+
+  it("returns the first N elements in heap order when unsorted=true (heap path, mutate=true)", () => {
+    const arr = [10, 1, 7, 3, 5]
+    const out = sortN(arr, { N: 3, force: true, unsorted: true, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr).toEqual([5, 1, 3])
+  })
+
+  it("uses the 'normal' sort+truncate path when force=false and mutates in-place", () => {
+    const arr = [4, 2, 5, 1, 3] // small array and N/len >= 0.1 -> normal path
+    const out = sortN(arr, { N: 2, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr).toEqual([1, 2])
+  })
 })

package/src/find.test.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-restricted-syntax */
 import { describe, expect, it } from "@jest/globals"
 
 const {

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)
@@ -248,7 +259,6 @@ describe("formatPlus", () => {
 
   it("returns undefined for non-number, non-string input", () => {
     expect(formatPlus(undefined)).toBeUndefined()
-    // eslint-disable-next-line no-restricted-syntax
     expect(formatPlus(null)).toBeUndefined()
     expect(formatPlus({})).toBeUndefined()
     expect(formatPlus([])).toBeUndefined()
@@ -256,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", () => {
@@ -323,7 +335,6 @@ describe("isNumber", () => {
   it("returns false for non-number types", () => {
     expect(isNumber("123")).toBe(false)
     expect(isNumber(undefined)).toBe(false)
-    // eslint-disable-next-line no-restricted-syntax
     expect(isNumber(null)).toBe(false)
     expect(isNumber({})).toBe(false)
     expect(isNumber([])).toBe(false)
@@ -332,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/object.test.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-restricted-syntax */
 import { jest } from "@jest/globals"
 import {
   deepCopy,

package/src/promise.test.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-restricted-syntax */
 /* eslint-disable prefer-promise-reject-errors */
 import { jest } from "@jest/globals"