@tim-code/my-util 0.1.4 → 0.2.1

package/package.json

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

package/src/find.js

@@ -1,150 +1,150 @@
-export function findClosestAbs(array, desired, { key, map, threshold = Infinity } = {}) {
+export function findClosestAbs(array, desired, { key, cutoff = Infinity } = {}) {
   let closest
-  if (map) {
+  if (typeof key === "function") {
     for (let i = 0; i < array.length; i++) {
       const element = array[i]
-      const value = map(element, i, array)
+      const value = key(element, i, array)
       const diff = Math.abs(value - desired)
-      if (diff < threshold) {
+      if (diff < cutoff) {
         closest = element
-        threshold = diff
+        cutoff = diff
       }
     }
-  } else if (key) {
+  } else if (typeof key === "number" || typeof key === "string") {
     for (const element of array) {
       const value = element[key]
       const diff = Math.abs(value - desired)
-      if (diff < threshold) {
+      if (diff < cutoff) {
         closest = element
-        threshold = diff
+        cutoff = diff
       }
     }
   } else {
     for (const value of array) {
       const diff = Math.abs(value - desired)
-      if (diff < threshold) {
+      if (diff < cutoff) {
         closest = value
-        threshold = diff
+        cutoff = diff
       }
     }
   }
   return closest
 }
 
-export function findClosestLT(array, desired, { key, map, threshold = -Infinity } = {}) {
+export function findClosestLT(array, desired, { key, cutoff = -Infinity } = {}) {
   let closest
-  if (map) {
+  if (typeof key === "function") {
     for (let i = 0; i < array.length; i++) {
       const element = array[i]
-      const value = map(element, i, array)
-      if (value < desired && value > threshold) {
+      const value = key(element, i, array)
+      if (value < desired && value > cutoff) {
         closest = element
-        threshold = value
+        cutoff = value
       }
     }
-  } else if (key) {
+  } else if (typeof key === "number" || typeof key === "string") {
     for (const element of array) {
       const value = element[key]
-      if (value < desired && value > threshold) {
+      if (value < desired && value > cutoff) {
         closest = element
-        threshold = value
+        cutoff = value
       }
     }
   } else {
     for (const value of array) {
-      if (value < desired && value > threshold) {
+      if (value < desired && value > cutoff) {
         closest = value
-        threshold = value
+        cutoff = value
       }
     }
   }
   return closest
 }
 
-export function findClosestLTE(array, desired, { key, map, threshold = -Infinity } = {}) {
+export function findClosestLTE(array, desired, { key, cutoff = -Infinity } = {}) {
   let closest
-  if (map) {
+  if (typeof key === "function") {
     for (let i = 0; i < array.length; i++) {
       const element = array[i]
-      const value = map(element, i, array)
-      if (value <= desired && value > threshold) {
+      const value = key(element, i, array)
+      if (value <= desired && value > cutoff) {
         closest = element
-        threshold = value
+        cutoff = value
       }
     }
-  } else if (key) {
+  } else if (typeof key === "number" || typeof key === "string") {
     for (const element of array) {
       const value = element[key]
-      if (value <= desired && value > threshold) {
+      if (value <= desired && value > cutoff) {
         closest = element
-        threshold = value
+        cutoff = value
       }
     }
   } else {
     for (const value of array) {
-      if (value <= desired && value > threshold) {
+      if (value <= desired && value > cutoff) {
         closest = value
-        threshold = value
+        cutoff = value
       }
     }
   }
   return closest
 }
 
-export function findClosestGT(array, desired, { key, map, threshold = Infinity } = {}) {
+export function findClosestGT(array, desired, { key, cutoff = Infinity } = {}) {
   let closest
-  if (map) {
+  if (typeof key === "function") {
     for (let i = 0; i < array.length; i++) {
       const element = array[i]
-      const value = map(element, i, array)
-      if (value > desired && value < threshold) {
+      const value = key(element, i, array)
+      if (value > desired && value < cutoff) {
         closest = element
-        threshold = value
+        cutoff = value
       }
     }
-  } else if (key) {
+  } else if (typeof key === "number" || typeof key === "string") {
     for (const element of array) {
       const value = element[key]
-      if (value > desired && value < threshold) {
+      if (value > desired && value < cutoff) {
         closest = element
-        threshold = value
+        cutoff = value
       }
     }
   } else {
     for (const value of array) {
-      if (value > desired && value < threshold) {
+      if (value > desired && value < cutoff) {
         closest = value
-        threshold = value
+        cutoff = value
       }
     }
   }
   return closest
 }
 
-export function findClosestGTE(array, desired, { key, map, threshold = Infinity } = {}) {
+export function findClosestGTE(array, desired, { key, cutoff = Infinity } = {}) {
   let closest
-  if (map) {
+  if (typeof key === "function") {
     for (let i = 0; i < array.length; i++) {
       const element = array[i]
-      const value = map(element, i, array)
-      if (value >= desired && value < threshold) {
+      const value = key(element, i, array)
+      if (value >= desired && value < cutoff) {
         closest = element
-        threshold = value
+        cutoff = value
       }
     }
-  } else if (key) {
+  } else if (typeof key === "number" || typeof key === "string") {
     for (const element of array) {
       const value = element[key]
-      if (value >= desired && value < threshold) {
+      if (value >= desired && value < cutoff) {
         closest = element
-        threshold = value
+        cutoff = value
       }
     }
   } else {
     for (const value of array) {
-      if (value >= desired && value < threshold) {
+      if (value >= desired && value < cutoff) {
         closest = value
-        threshold = value
+        cutoff = value
       }
     }
   }
@@ -152,27 +152,24 @@ export function findClosestGTE(array, desired, { key, map, threshold = Infinity
 }
 
 /**
- * Find the closest element in an array.
- * If using for strings, need to specify different values for "threshold" and "comparator".
- * "~" and "" are good threshold string values for gt/gte and lt/lte respectively.
+ * Find the closest element in an array. If there is a tie, then returns the first matching element by order in the array.
+ * 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.
  * @template T, V
  * @param {Array<T>} array
  * @param {V} value The desired value to search for
  * @param {Object} options
- * @param {string|number=} options.key If specified, will consider the value for each element's key instead of the element itself.
- * @param {Function=} options.map If specified, will compute value by calling provided function on the element. Takes precedence over key.
- * @param {string|number|Function=} options.transform Allows combining key and map as one parameter. Useful for piping in passed values.
+ * @param {string|number|Function=} options.key
+ *  If specified, will consider the value for each element's key instead of the element itself.
+ *  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 "abs", "lt", "lte", "gt", "gte", "abs". Default is "abs" which implies T is number.
- * @param {V=} options.threshold If specified, uses a different initial min/max/difference than positive or negative infinity.
+ * @param {V=} options.cutoff If specified, sets a initial constraint on how close the found value must be.
+ *  For example, if used with "lt", the found element would need to be greater than the cutoff but still less than the desired value.
+ *  If used with "abs", the found element would need to have a difference with the desired value less than the cutoff.
  * @returns {T|undefined}
  */
 export function findClosest(array, value, options = {}) {
-  const { comparator = "abs", transform } = options
-  if (typeof transform === "function") {
-    options = { ...options, map: transform }
-  } else if (typeof transform === "string" || typeof transform === "number") {
-    options = { ...options, key: transform }
-  }
+  const { comparator = "abs" } = options
   switch (comparator) {
     case "lt":
       return findClosestLT(array, value, options)
@@ -188,3 +185,85 @@ export function findClosest(array, value, options = {}) {
       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

@@ -1,335 +1,286 @@
-import {
-  findClosest,
+import { describe, expect, it } from "@jest/globals"
+
+const {
   findClosestAbs,
-  findClosestGT,
-  findClosestGTE,
   findClosestLT,
   findClosestLTE,
-} from "./find.js"
+  findClosestGT,
+  findClosestGTE,
+  findClosest,
+  findMin,
+  findMax,
+} = await import("./find.js")
 
-describe("findClosest", () => {
-  it("returns the closest value by absolute difference (default comparator)", () => {
-    expect(findClosest([1, 5, 10], 6)).toBe(5)
-    expect(findClosest([1, 5, 10], 8)).toBe(10)
-    expect(findClosest([1, 5, 10], 1)).toBe(1)
+describe("findClosestAbs", () => {
+  it("returns the element closest in absolute value to desired", () => {
+    expect(findClosestAbs([1, 5, 9], 6)).toBe(5)
+    expect(findClosestAbs([1, 5, 9], 8)).toBe(9)
+    expect(findClosestAbs([1, 5, 9], 1)).toBe(1)
   })
 
-  it("returns undefined if array is empty", () => {
-    expect(findClosest([], 10)).toBeUndefined()
+  it("returns the first element in case of tie", () => {
+    expect(findClosestAbs([4, 8], 6)).toBe(4)
   })
 
-  it("returns the closest object by key (abs)", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosest(arr, 6, { key: "v" })).toEqual({ v: 5 })
+  it("returns undefined for empty array", () => {
+    expect(findClosestAbs([], 10)).toBeUndefined()
   })
 
-  it("returns the closest value less than input (lt comparator)", () => {
-    expect(findClosest([1, 3, 5, 7], 6, { comparator: "lt" })).toBe(5)
-    expect(findClosest([1, 3, 5, 7], 1, { comparator: "lt" })).toBeUndefined()
+  it("supports key as function", () => {
+    const arr = [{ v: 2 }, { v: 8 }]
+    expect(findClosestAbs(arr, 5, { key: (e) => e.v })).toEqual({ v: 2 })
   })
 
-  it("returns the closest value less than or equal to input (lte comparator)", () => {
-    expect(findClosest([1, 3, 5, 7], 5, { comparator: "lte" })).toBe(5)
-    expect(findClosest([1, 3, 5, 7], 2, { comparator: "lte" })).toBe(1)
-    expect(findClosest([1, 3, 5, 7], 0, { comparator: "lte" })).toBeUndefined()
+  it("supports key as string", () => {
+    const arr = [{ x: 1 }, { x: 10 }]
+    expect(findClosestAbs(arr, 8, { key: "x" })).toEqual({ x: 10 })
   })
 
-  it("returns the closest value greater than input (gt comparator)", () => {
-    expect(findClosest([1, 3, 5, 7], 5, { comparator: "gt" })).toBe(7)
-    expect(findClosest([1, 3, 5, 7], 7, { comparator: "gt" })).toBeUndefined()
+  it("supports key as number", () => {
+    const arr = [[2], [8]]
+    expect(findClosestAbs(arr, 7, { key: 0 })).toEqual([8])
   })
 
-  it("returns the closest value greater than or equal to input (gte comparator)", () => {
-    expect(findClosest([1, 3, 5, 7], 5, { comparator: "gte" })).toBe(5)
-    expect(findClosest([1, 3, 5, 7], 6, { comparator: "gte" })).toBe(7)
-    expect(findClosest([1, 3, 5, 7], 8, { comparator: "gte" })).toBeUndefined()
+  it("respects cutoff", () => {
+    expect(findClosestAbs([1, 5, 9], 6, { cutoff: 2 })).toBe(5)
+    expect(findClosestAbs([1, 5, 9], 6, { cutoff: 1 })).toBeUndefined()
   })
+})
 
-  it("returns the closest object by key for lt/lte/gt/gte", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosest(arr, 6, { comparator: "lt", key: "v" })).toEqual({ v: 5 })
-    expect(findClosest(arr, 6, { comparator: "lte", key: "v" })).toEqual({ v: 5 })
-    expect(findClosest(arr, 6, { comparator: "gt", key: "v" })).toEqual({ v: 10 })
-    expect(findClosest(arr, 10, { comparator: "gte", key: "v" })).toEqual({ v: 10 })
+describe("findClosestLT", () => {
+  it("returns the closest element less than desired", () => {
+    expect(findClosestLT([1, 5, 9], 6)).toBe(5)
+    expect(findClosestLT([1, 5, 9], 2)).toBe(1)
+    expect(findClosestLT([1, 5, 9], 1)).toBeUndefined()
   })
 
-  it("respects the threshold option for abs comparator", () => {
-    expect(findClosest([1, 5, 10], 6, { threshold: 0.5 })).toBeUndefined()
-    expect(findClosest([1, 5, 10], 6, { threshold: 2 })).toBe(5)
+  it("returns first match if tie", () => {
+    expect(findClosestLT([2, 2, 1], 3)).toBe(2)
   })
 
-  it("respects the threshold option for lt/lte/gt/gte", () => {
-    expect(findClosest([1, 3, 5, 7], 6, { comparator: "lt", threshold: 4 })).toBe(5)
-    expect(findClosest([1, 3, 5, 7], 6, { comparator: "lt", threshold: 5 })).toBeUndefined()
-    expect(findClosest([1, 3, 5, 7], 6, { comparator: "gt", threshold: 7 })).toBeUndefined()
-    expect(findClosest([1, 3, 5, 7], 6, { comparator: "gt", threshold: 10 })).toBe(7)
+  it("returns undefined for empty array", () => {
+    expect(findClosestLT([], 10)).toBeUndefined()
   })
 
-  it("throws for unknown comparator", () => {
-    expect(() => findClosest([1, 2, 3], 2, { comparator: "foo" })).toThrow(
-      "Unknown comparator: foo"
-    )
+  it("supports key as function", () => {
+    const arr = [{ v: 2 }, { v: 8 }]
+    expect(findClosestLT(arr, 8, { key: (e) => e.v })).toEqual({ v: 2 })
+  })
+
+  it("supports key as string", () => {
+    const arr = [{ x: 1 }, { x: 10 }]
+    expect(findClosestLT(arr, 8, { key: "x" })).toEqual({ x: 1 })
   })
 
-  it("returns undefined if no element matches threshold/key criteria", () => {
-    expect(
-      findClosest([{ v: 1 }], 10, { comparator: "gt", key: "v", threshold: 1 })
-    ).toBeUndefined()
-    expect(
-      findClosest([{ v: 1 }], 0, { comparator: "lt", key: "v", threshold: 1 })
-    ).toBeUndefined()
-  })
-
-  it("works with negative numbers and zero", () => {
-    expect(findClosest([-10, -5, 0, 5, 10], -7)).toBe(-5)
-    expect(findClosest([-10, -5, 0, 5, 10], 0)).toBe(0)
-    expect(findClosest([-10, -5, 0, 5, 10], 7)).toBe(5)
-  })
-
-  // ISSUE: findClosestAbs and related functions do not skip NaN values in key/map modes, only in value mode.
-  it("skips NaN values in abs comparator", () => {
-    expect(findClosest([1, NaN, 5], 4)).toBe(5)
-  })
-
-  it("skips objects missing the key in key-based comparators", () => {
-    const arr = [{ v: 1 }, {}, { v: 5 }]
-    expect(findClosest(arr, 2, { key: "v" })).toEqual({ v: 1 })
-  })
-
-  it("finds the closest string using abs comparator and a custom threshold/comparator", () => {
-    // Since abs comparator expects numbers, we need to provide a custom comparator for strings.
-    // We'll use threshold and comparator: "lt", "lte", "gt", "gte" for string comparisons.
-    const arr = ["apple", "banana", "cherry", "date"]
-    // Find the closest string less than "carrot" (alphabetically)
-    expect(findClosest(arr, "carrot", { comparator: "lt", threshold: "" })).toBe("banana")
-    // Find the closest string less than or equal to "banana"
-    expect(findClosest(arr, "banana", { comparator: "lte", threshold: "" })).toBe("banana")
-    // Find the closest string greater than "carrot"
-    expect(findClosest(arr, "carrot", { comparator: "gt", threshold: "~" })).toBe("cherry")
-    // Find the closest string greater than or equal to "date"
-    expect(findClosest(arr, "date", { comparator: "gte", threshold: "~" })).toBe("date")
-    // If nothing matches, returns undefined
-    expect(findClosest(arr, "aardvark", { comparator: "lt", threshold: "" })).toBeUndefined()
-    expect(findClosest(arr, "zebra", { comparator: "gt", threshold: "~" })).toBeUndefined()
-  })
-
-  it("finds the closest string by key in array of objects", () => {
-    const arr = [{ name: "apple" }, { name: "banana" }, { name: "cherry" }]
-    expect(
-      findClosest(arr, "blueberry", { comparator: "lt", key: "name", threshold: "" })
-    ).toEqual({
-      name: "banana",
-    })
-    expect(
-      findClosest(arr, "banana", { comparator: "lte", key: "name", threshold: "" })
-    ).toEqual({
-      name: "banana",
-    })
-    expect(
-      findClosest(arr, "banana", { comparator: "gt", key: "name", threshold: "~" })
-    ).toEqual({
-      name: "cherry",
-    })
-    expect(
-      findClosest(arr, "cherry", { comparator: "gte", key: "name", threshold: "~" })
-    ).toEqual({
-      name: "cherry",
-    })
-    expect(
-      findClosest(arr, "aardvark", { comparator: "lt", key: "name", threshold: "" })
-    ).toBeUndefined()
-  })
-
-  it("returns undefined if no string matches threshold/key criteria", () => {
-    const arr = ["apple", "banana", "cherry"]
-    expect(findClosest(arr, "apple", { comparator: "lt", threshold: "" })).toBeUndefined()
-    expect(findClosest(arr, "cherry", { comparator: "gt" })).toBeUndefined()
-  })
-
-  it("can use abs comparator with string lengths", () => {
-    // This is a reasonable use-case for abs: find string with length closest to 4
-    const arr = ["a", "bb", "ccc", "dddd", "eeeee"]
-    // Map to string lengths using key
-    expect(findClosest(arr, 4, { comparator: "abs", key: "length" })).toEqual("dddd")
-    // If threshold is set so no string length is close enough
-    expect(
-      findClosest(arr, 4, { comparator: "abs", key: "length", threshold: -1 })
-    ).toBeUndefined()
-  })
-
-  it("uses transform as a function (same as map)", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    const mapFn = (el) => el.v
-    expect(findClosest(arr, 6, { transform: mapFn })).toEqual({ v: 5 })
-    // Should take precedence over key if both are present
-    expect(findClosest(arr, 6, { key: "notUsed", transform: mapFn })).toEqual({ v: 5 })
-  })
-
-  it("uses transform as a string (same as key)", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosest(arr, 6, { transform: "v" })).toEqual({ v: 5 })
-    // Should take precedence over key if both are present
-    expect(findClosest(arr, 6, { key: "notUsed", transform: "v" })).toEqual({ v: 5 })
-  })
-
-  it("uses transform as a number (same as key)", () => {
-    const arr = [[1], [5], [10]]
-    expect(findClosest(arr, 6, { transform: 0 })).toEqual([5])
-    // Should take precedence over key if both are present
-    expect(findClosest(arr, 6, { key: "notUsed", transform: 0 })).toEqual([5])
-  })
-
-  it("transform does not override key if key is already present and transform is not provided", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosest(arr, 6, { key: "v" })).toEqual({ v: 5 })
-  })
-
-  it("transform is ignored if not a function, string, or number", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    // eslint-disable-next-line no-restricted-syntax
-    expect(findClosest(arr, 6, { transform: null, key: "v" })).toEqual({ v: 5 })
-    expect(findClosest(arr, 6, { transform: {}, key: "v" })).toEqual({ v: 5 })
+  it("supports key as number", () => {
+    const arr = [[2], [8]]
+    expect(findClosestLT(arr, 7, { key: 0 })).toEqual([2])
+  })
+
+  it("respects cutoff", () => {
+    expect(findClosestLT([1, 5, 9], 6, { cutoff: 4 })).toBe(5)
+    expect(findClosestLT([1, 5, 9], 6, { cutoff: 5 })).toBeUndefined()
   })
 })
 
-describe("findClosestAbs", () => {
-  it("returns closest value by absolute difference", () => {
-    expect(findClosestAbs([1, 5, 10], 6)).toBe(5)
-    expect(findClosestAbs([1, 5, 10], 8)).toBe(10)
-    expect(findClosestAbs([1, 5, 10], 1)).toBe(1)
+describe("findClosestLTE", () => {
+  it("returns the closest element less than or equal to desired", () => {
+    expect(findClosestLTE([1, 5, 9], 5)).toBe(5)
+    expect(findClosestLTE([1, 5, 9], 6)).toBe(5)
+    expect(findClosestLTE([1, 5, 9], 1)).toBe(1)
+    expect(findClosestLTE([1, 5, 9], 0)).toBeUndefined()
+  })
+
+  it("returns first match if tie", () => {
+    expect(findClosestLTE([2, 2, 1], 2)).toBe(2)
   })
 
   it("returns undefined for empty array", () => {
-    expect(findClosestAbs([], 10)).toBeUndefined()
+    expect(findClosestLTE([], 10)).toBeUndefined()
   })
 
-  it("returns closest object by key", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosestAbs(arr, 6, { key: "v" })).toEqual({ v: 5 })
+  it("supports key as function", () => {
+    const arr = [{ v: 2 }, { v: 8 }]
+    expect(findClosestLTE(arr, 8, { key: (e) => e.v })).toEqual({ v: 8 })
   })
 
-  it("returns closest value by map", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosestAbs(arr, 6, { map: (el) => el.v })).toEqual({ v: 5 })
+  it("supports key as string", () => {
+    const arr = [{ x: 1 }, { x: 10 }]
+    expect(findClosestLTE(arr, 8, { key: "x" })).toEqual({ x: 1 })
   })
 
-  it("respects threshold", () => {
-    expect(findClosestAbs([1, 5, 10], 6, { threshold: 0.5 })).toBeUndefined()
-    expect(findClosestAbs([1, 5, 10], 6, { threshold: 2 })).toBe(5)
+  it("supports key as number", () => {
+    const arr = [[2], [8]]
+    expect(findClosestLTE(arr, 7, { key: 0 })).toEqual([2])
   })
 
-  it("skips NaN in value mode but not in key/map mode", () => {
-    expect(findClosestAbs([1, NaN, 5], 4)).toBe(5)
-    const arr = [{ v: 1 }, { v: NaN }, { v: 5 }]
-    expect(findClosestAbs(arr, 2, { key: "v" })).toEqual({ v: 1 })
-    expect(findClosestAbs(arr, 2, { map: (el) => el.v })).toEqual({ v: 1 })
+  it("respects cutoff", () => {
+    expect(findClosestLTE([1, 5, 9], 6, { cutoff: 4 })).toBe(5)
+    expect(findClosestLTE([1, 5, 9], 6, { cutoff: 5 })).toBeUndefined()
   })
 })
 
-describe("findClosestLT", () => {
-  it("returns closest value less than desired", () => {
-    expect(findClosestLT([1, 3, 5, 7], 6)).toBe(5)
-    expect(findClosestLT([1, 3, 5, 7], 1)).toBeUndefined()
+describe("findClosestGT", () => {
+  it("returns the closest element greater than desired", () => {
+    expect(findClosestGT([1, 5, 9], 6)).toBe(9)
+    expect(findClosestGT([1, 5, 9], 0)).toBe(1)
+    expect(findClosestGT([1, 5, 9], 9)).toBeUndefined()
   })
 
-  it("returns closest object by key", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosestLT(arr, 6, { key: "v" })).toEqual({ v: 5 })
+  it("returns first match if tie", () => {
+    expect(findClosestGT([8, 8, 10], 7)).toBe(8)
   })
 
-  it("returns closest object by map", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosestLT(arr, 6, { map: (el) => el.v })).toEqual({ v: 5 })
+  it("returns undefined for empty array", () => {
+    expect(findClosestGT([], 10)).toBeUndefined()
   })
 
-  it("respects threshold", () => {
-    expect(findClosestLT([1, 3, 5, 7], 6, { threshold: 4 })).toBe(5)
-    expect(findClosestLT([1, 3, 5, 7], 6, { threshold: 5 })).toBeUndefined()
+  it("supports key as function", () => {
+    const arr = [{ v: 2 }, { v: 8 }]
+    expect(findClosestGT(arr, 2, { key: (e) => e.v })).toEqual({ v: 8 })
   })
 
-  it("returns undefined for empty array", () => {
-    expect(findClosestLT([], 10)).toBeUndefined()
+  it("supports key as string", () => {
+    const arr = [{ x: 1 }, { x: 10 }]
+    expect(findClosestGT(arr, 8, { key: "x" })).toEqual({ x: 10 })
   })
-})
 
-describe("findClosestLTE", () => {
-  it("returns closest value less than or equal to desired", () => {
-    expect(findClosestLTE([1, 3, 5, 7], 5)).toBe(5)
-    expect(findClosestLTE([1, 3, 5, 7], 2)).toBe(1)
-    expect(findClosestLTE([1, 3, 5, 7], 0)).toBeUndefined()
+  it("supports key as number", () => {
+    const arr = [[2], [8]]
+    expect(findClosestGT(arr, 2, { key: 0 })).toEqual([8])
   })
 
-  it("returns closest object by key", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosestLTE(arr, 6, { key: "v" })).toEqual({ v: 5 })
+  it("respects cutoff", () => {
+    expect(findClosestGT([1, 5, 9], 6, { cutoff: 8 })).toBeUndefined()
+    expect(findClosestGT([1, 5, 9], 4, { cutoff: 8 })).toBe(5)
   })
+})
 
-  it("returns closest object by map", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosestLTE(arr, 6, { map: (el) => el.v })).toEqual({ v: 5 })
+describe("findClosestGTE", () => {
+  it("returns the closest element greater than or equal to desired", () => {
+    expect(findClosestGTE([1, 5, 9], 5)).toBe(5)
+    expect(findClosestGTE([1, 5, 9], 4)).toBe(5)
+    expect(findClosestGTE([1, 5, 9], 10)).toBeUndefined()
   })
 
-  it("respects threshold", () => {
-    expect(findClosestLTE([1, 3, 5, 7], 6, { threshold: 4 })).toBe(5)
-    expect(findClosestLTE([1, 3, 5, 7], 6, { threshold: 5 })).toBeUndefined()
+  it("returns first match if tie", () => {
+    expect(findClosestGTE([8, 8, 10], 8)).toBe(8)
   })
 
   it("returns undefined for empty array", () => {
-    expect(findClosestLTE([], 10)).toBeUndefined()
+    expect(findClosestGTE([], 10)).toBeUndefined()
+  })
+
+  it("supports key as function", () => {
+    const arr = [{ v: 2 }, { v: 8 }]
+    expect(findClosestGTE(arr, 2, { key: (e) => e.v })).toEqual({ v: 2 })
+  })
+
+  it("supports key as string", () => {
+    const arr = [{ x: 1 }, { x: 10 }]
+    expect(findClosestGTE(arr, 8, { key: "x" })).toEqual({ x: 10 })
+  })
+
+  it("supports key as number", () => {
+    const arr = [[2], [8]]
+    expect(findClosestGTE(arr, 2, { key: 0 })).toEqual([2])
+  })
+
+  it("respects cutoff", () => {
+    expect(findClosestGTE([1, 5, 9], 6, { cutoff: 8 })).toBeUndefined()
+    expect(findClosestGTE([1, 5, 9], 4, { cutoff: 8 })).toBe(5)
   })
 })
 
-describe("findClosestGT", () => {
-  it("returns closest value greater than desired", () => {
-    expect(findClosestGT([1, 3, 5, 7], 5)).toBe(7)
-    expect(findClosestGT([1, 3, 5, 7], 7)).toBeUndefined()
+describe("findClosest", () => {
+  it("defaults to abs comparator", () => {
+    expect(findClosest([1, 5, 9], 6)).toBe(5)
   })
 
-  it("returns closest object by key", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosestGT(arr, 6, { key: "v" })).toEqual({ v: 10 })
+  it("calls correct comparator", () => {
+    expect(findClosest([1, 5, 9], 6, { comparator: "lt" })).toBe(5)
+    expect(findClosest([1, 5, 9], 6, { comparator: "lte" })).toBe(5)
+    expect(findClosest([1, 5, 9], 6, { comparator: "gt" })).toBe(9)
+    expect(findClosest([1, 5, 9], 6, { comparator: "gte" })).toBe(9)
+    expect(findClosest([1, 5, 9], 6, { comparator: "abs" })).toBe(5)
   })
 
-  it("returns closest object by map", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosestGT(arr, 6, { map: (el) => el.v })).toEqual({ v: 10 })
+  it("throws on unknown comparator", () => {
+    expect(() => findClosest([1, 5, 9], 6, { comparator: "foo" })).toThrow(
+      "Unknown comparator: foo"
+    )
   })
 
-  it("respects threshold", () => {
-    expect(findClosestGT([1, 3, 5, 7], 6, { threshold: 7 })).toBeUndefined()
-    expect(findClosestGT([1, 3, 5, 7], 6, { threshold: 10 })).toBe(7)
+  it("passes options to underlying function", () => {
+    const arr = [{ x: 1 }, { x: 10 }]
+    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(findClosestGT([], 10)).toBeUndefined()
+    expect(findMin([])).toBeUndefined()
   })
-})
 
-describe("findClosestGTE", () => {
-  it("returns closest value greater than or equal to desired", () => {
-    expect(findClosestGTE([1, 3, 5, 7], 5)).toBe(5)
-    expect(findClosestGTE([1, 3, 5, 7], 6)).toBe(7)
-    expect(findClosestGTE([1, 3, 5, 7], 8)).toBeUndefined()
+  it("returns the first minimum if there are duplicates", () => {
+    expect(findMin([2, 1, 1, 3])).toBe(1)
   })
 
-  it("returns closest object by key", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosestGTE(arr, 6, { key: "v" })).toEqual({ v: 10 })
-    expect(findClosestGTE(arr, 10, { key: "v" })).toEqual({ v: 10 })
+  it("supports key as function", () => {
+    const arr = [{ v: 5 }, { v: 2 }, { v: 8 }]
+    expect(findMin(arr, { key: (e) => e.v })).toEqual({ v: 2 })
   })
 
-  it("returns closest object by map", () => {
-    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
-    expect(findClosestGTE(arr, 6, { map: (el) => el.v })).toEqual({ v: 10 })
-    expect(findClosestGTE(arr, 10, { map: (el) => el.v })).toEqual({ v: 10 })
+  it("supports key as string", () => {
+    const arr = [{ x: 5 }, { x: 2 }, { x: 8 }]
+    expect(findMin(arr, { key: "x" })).toEqual({ x: 2 })
   })
 
-  it("respects threshold", () => {
-    expect(findClosestGTE([1, 3, 5, 7], 6, { threshold: 7 })).toBeUndefined()
-    expect(findClosestGTE([1, 3, 5, 7], 6, { threshold: 10 })).toBe(7)
+  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(findClosestGTE([], 10)).toBeUndefined()
+    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()
   })
 })