@tim-code/my-util 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "",
   "type": "module",
   "author": "",

package/src/find.js

@@ -182,6 +182,88 @@ export function findClosest(array, value, options = {}) {
     case "abs":
       return findClosestAbs(array, value, options)
     default:
-      throw new Error(`Unknown comparator: ${comparator}`)
+      throw new Error(`unknown comparator: ${comparator}`)
   }
 }
+
+/**
+ * Find the minimum value in an array.
+ * @template T, V
+ * @param {Array<T>} array
+ * @param {Object} $1
+ * @param {string|Function=} $1.key Specifies an alternative to using each element as the value.
+ *  If string, then accesses each element at that key to get value.
+ *  If function, then calls the callback on each element to get value.
+ * @param {V=} $1.cutoff Only values below cutoff will be considered.
+ * @returns {T}
+ */
+export function findMin(array, { key, cutoff = Infinity } = {}) {
+  let closest
+  if (typeof key === "function") {
+    for (let i = 0; i < array.length; i++) {
+      const element = array[i]
+      const value = key(element, i, array)
+      if (value < cutoff) {
+        closest = element
+        cutoff = value
+      }
+    }
+  } else if (typeof key === "number" || typeof key === "string") {
+    for (const element of array) {
+      const value = element[key]
+      if (value < cutoff) {
+        closest = element
+        cutoff = value
+      }
+    }
+  } else {
+    for (const value of array) {
+      if (value < cutoff) {
+        closest = value
+        cutoff = value
+      }
+    }
+  }
+  return closest
+}
+
+/**
+ * Find the maximum value in an array.
+ * @template T, V
+ * @param {Array<T>} array
+ * @param {Object} $1
+ * @param {string|Function=} $1.key Specifies an alternative to using each element as the value.
+ *  If string, then accesses each element at that key to get value.
+ *  If function, then calls the callback on each element to get value.
+ * @param {V=} $1.cutoff Only values above cutoff will be considered.
+ * @returns {T}
+ */
+export function findMax(array, { key, cutoff = -Infinity } = {}) {
+  let closest
+  if (typeof key === "function") {
+    for (let i = 0; i < array.length; i++) {
+      const element = array[i]
+      const value = key(element, i, array)
+      if (value > cutoff) {
+        closest = element
+        cutoff = value
+      }
+    }
+  } else if (typeof key === "number" || typeof key === "string") {
+    for (const element of array) {
+      const value = element[key]
+      if (value > cutoff) {
+        closest = element
+        cutoff = value
+      }
+    }
+  } else {
+    for (const value of array) {
+      if (value > cutoff) {
+        closest = value
+        cutoff = value
+      }
+    }
+  }
+  return closest
+}

package/src/find.test.js

@@ -7,6 +7,8 @@ const {
   findClosestGT,
   findClosestGTE,
   findClosest,
+  findMin,
+  findMax,
 } = await import("./find.js")
 
 describe("findClosestAbs", () => {
@@ -205,7 +207,7 @@ describe("findClosest", () => {
 
   it("throws on unknown comparator", () => {
     expect(() => findClosest([1, 5, 9], 6, { comparator: "foo" })).toThrow(
-      "Unknown comparator: foo"
+      "unknown comparator: foo"
     )
   })
 
@@ -214,3 +216,71 @@ describe("findClosest", () => {
     expect(findClosest(arr, 8, { comparator: "abs", key: "x" })).toEqual({ x: 10 })
   })
 })
+
+describe("findMin", () => {
+  it("returns the minimum value in a numeric array", () => {
+    expect(findMin([3, 1, 4, 2])).toBe(1)
+  })
+
+  it("returns undefined for empty array", () => {
+    expect(findMin([])).toBeUndefined()
+  })
+
+  it("returns the first minimum if there are duplicates", () => {
+    expect(findMin([2, 1, 1, 3])).toBe(1)
+  })
+
+  it("supports key as function", () => {
+    const arr = [{ v: 5 }, { v: 2 }, { v: 8 }]
+    expect(findMin(arr, { key: (e) => e.v })).toEqual({ v: 2 })
+  })
+
+  it("supports key as string", () => {
+    const arr = [{ x: 5 }, { x: 2 }, { x: 8 }]
+    expect(findMin(arr, { key: "x" })).toEqual({ x: 2 })
+  })
+
+  it("supports key as number", () => {
+    const arr = [[5], [2], [8]]
+    expect(findMin(arr, { key: 0 })).toEqual([2])
+  })
+
+  it("respects cutoff", () => {
+    expect(findMin([3, 1, 4, 2], { cutoff: 2 })).toBe(1)
+    expect(findMin([3, 1, 4, 2], { cutoff: 1 })).toBeUndefined()
+  })
+})
+
+describe("findMax", () => {
+  it("returns the maximum value in a numeric array", () => {
+    expect(findMax([3, 1, 4, 2])).toBe(4)
+  })
+
+  it("returns undefined for empty array", () => {
+    expect(findMax([])).toBeUndefined()
+  })
+
+  it("returns the first maximum if there are duplicates", () => {
+    expect(findMax([4, 2, 4, 1])).toBe(4)
+  })
+
+  it("supports key as function", () => {
+    const arr = [{ v: 5 }, { v: 2 }, { v: 8 }]
+    expect(findMax(arr, { key: (e) => e.v })).toEqual({ v: 8 })
+  })
+
+  it("supports key as string", () => {
+    const arr = [{ x: 5 }, { x: 2 }, { x: 8 }]
+    expect(findMax(arr, { key: "x" })).toEqual({ x: 8 })
+  })
+
+  it("supports key as number", () => {
+    const arr = [[5], [2], [8]]
+    expect(findMax(arr, { key: 0 })).toEqual([8])
+  })
+
+  it("respects cutoff", () => {
+    expect(findMax([3, 1, 4, 2], { cutoff: 2 })).toBe(4)
+    expect(findMax([3, 1, 4, 2], { cutoff: 4 })).toBeUndefined()
+  })
+})

package/src/math.js

@@ -23,6 +23,85 @@ export function line([x1, y1], [x2, y2]) {
   return (x) => m * x + b
 }
 
+/**
+ * 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
+ * @returns {number}
+ */
+export function sum(array, { key } = {}) {
+  let total = 0
+  if (typeof key === "function") {
+    for (let i = 0; i < array.length; i++) {
+      total += key(array[i], i, array)
+    }
+  } else if (typeof key === "string" || typeof key === "number") {
+    for (let i = 0; i < array.length; i++) {
+      total += array[i][key]
+    }
+  } else {
+    for (let i = 0; i < array.length; i++) {
+      total += array[i]
+    }
+  }
+  return total
+}
+
+/**
+ * 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
+ * @returns {number}
+ * @throws {Error} If the array is empty.
+ */
+export function average(array, { key } = {}) {
+  if (array.length === 0) {
+    throw new Error("cannot compute average of empty array")
+  }
+  return sum(array, { key }) / array.length
+}
+
+/**
+ * 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
+ * @returns {number}
+ * @throws {Error} If the array is empty.
+ */
+export function variance(array, { key } = {}) {
+  if (array.length === 0) {
+    throw new Error("cannot compute variance of empty array")
+  }
+  const avg = average(array, { key })
+  let total = 0
+  if (typeof key === "function") {
+    for (let i = 0; i < array.length; i++) {
+      const value = key(array[i], i, array)
+      const diff = value - avg
+      total += diff * diff
+    }
+  } else if (typeof key === "string" || typeof key === "number") {
+    for (let i = 0; i < array.length; i++) {
+      const value = array[i][key]
+      const diff = value - avg
+      total += diff * diff
+    }
+  } else {
+    for (let i = 0; i < array.length; i++) {
+      const value = array[i]
+      const diff = value - avg
+      total += diff * diff
+    }
+  }
+  return total / array.length
+}
+
 /**
  * Prepend a plus to a number or string if positive.
  * @param {number|string} number Or string

package/src/math.test.js

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "@jest/globals"
-const { mod, formatPlus, line } = await import("./math.js")
+const { mod, formatPlus, line, sum, average, variance } = await import("./math.js")
 
 describe("mod", () => {
   it("returns n when n is less than m and n is non-negative", () => {
@@ -104,6 +104,102 @@ describe("line", () => {
   })
 })
 
+describe("sum", () => {
+  it("returns 0 for an empty array", () => {
+    expect(sum([])).toBe(0)
+  })
+
+  it("sums a simple array of numbers", () => {
+    expect(sum([1, 2, 3])).toBe(6)
+    expect(sum([-1, 1, 2])).toBe(2)
+  })
+
+  it("sums using a key function", () => {
+    const arr = [{ v: 2 }, { v: 3 }, { v: 4 }]
+    expect(sum(arr, { key: (el) => el.v })).toBe(9)
+    expect(sum(arr, { key: (el, i) => el.v * i })).toBe(0 * 2 + 1 * 3 + 2 * 4) // 0 + 3 + 8 = 11
+  })
+
+  it("sums using a string key", () => {
+    const arr = [{ v: 2 }, { v: 3 }, { v: 4 }]
+    expect(sum(arr, { key: "v" })).toBe(9)
+  })
+
+  it("sums using a numeric key", () => {
+    const arr = [[1], [2], [3]]
+    expect(sum(arr, { key: 0 })).toBe(6)
+  })
+
+  it("handles array of numbers with undefined options", () => {
+    expect(sum([5, 6, 7])).toBe(18)
+    expect(sum([5, 6, 7], undefined)).toBe(18)
+  })
+
+  it("returns NaN if key is string/number and property is missing", () => {
+    expect(sum([{ a: 1 }, {}], { key: "a" })).toBeNaN()
+  })
+})
+
+describe("average", () => {
+  it("computes the mean of a number array", () => {
+    expect(average([1, 2, 3])).toBe(2)
+    expect(average([1, 1, 1, 1])).toBe(1)
+  })
+
+  it("computes the mean using a key function", () => {
+    const arr = [{ v: 2 }, { v: 4 }]
+    expect(average(arr, { key: (el) => el.v })).toBe(3)
+  })
+
+  it("computes the mean using a string key", () => {
+    const arr = [{ v: 2 }, { v: 4 }]
+    expect(average(arr, { key: "v" })).toBe(3)
+  })
+
+  it("computes the mean using a numeric key", () => {
+    const arr = [[2], [4]]
+    expect(average(arr, { key: 0 })).toBe(3)
+  })
+
+  it("throws for empty array", () => {
+    expect(() => average([])).toThrow("cannot compute average of empty array")
+  })
+
+  it("returns NaN if key is string/number and property is missing", () => {
+    expect(average([{ a: 1 }, {}], { key: "a" })).toBeNaN()
+  })
+})
+
+describe("variance", () => {
+  it("computes the variance of a number array", () => {
+    expect(variance([1, 2, 3])).toBeCloseTo(2 / 3)
+    expect(variance([1, 1, 1, 1])).toBe(0)
+  })
+
+  it("computes the variance using a key function", () => {
+    const arr = [{ v: 2 }, { v: 4 }]
+    expect(variance(arr, { key: (el) => el.v })).toBe(1)
+  })
+
+  it("computes the variance using a string key", () => {
+    const arr = [{ v: 2 }, { v: 4 }]
+    expect(variance(arr, { key: "v" })).toBe(1)
+  })
+
+  it("computes the variance using a numeric key", () => {
+    const arr = [[2], [4]]
+    expect(variance(arr, { key: 0 })).toBe(1)
+  })
+
+  it("throws for empty array", () => {
+    expect(() => variance([])).toThrow("cannot compute variance of empty array")
+  })
+
+  it("returns NaN if key is string/number and property is missing", () => {
+    expect(variance([{ a: 1 }, {}], { key: "a" })).toBeNaN()
+  })
+})
+
 describe("formatPlus", () => {
   it("prepends a plus for positive numbers", () => {
     expect(formatPlus(1)).toBe("+1")