@tim-code/my-util 0.1.2 → 0.1.4

package/package.json

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

package/src/array.js

@@ -44,38 +44,58 @@ function compareUndefinedNull(a, b) {
 /**
  * Returns an "ascending" comparator, via "<", to be used to sort an array.
  * Undefined or null values are always sorted to the end.
- * @param {String=} key If sorting objects, can specify a key to use to compare.
+ * @param {string|number|Function=} transform
+ *  If a function, calls the provided function on an element to get the value to sort on.
+ *  If a string or number, treats transform as a key and sorts on each element's value at key.
  * @returns {Function}
  */
-export function ascending(key) {
-  if (!key) {
+export function ascending(transform) {
+  if (typeof transform === "function") {
     return (a, b) => {
+      a = transform(a)
+      b = transform(b)
       return compareUndefinedNull(a, b) ?? (a < b ? -1 : b < a ? 1 : 0)
     }
   }
+  if (typeof transform === "string" || typeof transform === "number") {
+    return (a, b) => {
+      const invalid = compareUndefinedNull(a[transform], b[transform])
+      return (
+        invalid ?? (a[transform] < b[transform] ? -1 : b[transform] < a[transform] ? 1 : 0)
+      )
+    }
+  }
   return (a, b) => {
-    return (
-      compareUndefinedNull(a[key], b[key]) ?? (a[key] < b[key] ? -1 : b[key] < a[key] ? 1 : 0)
-    )
+    return compareUndefinedNull(a, b) ?? (a < b ? -1 : b < a ? 1 : 0)
   }
 }
 
 /**
  * Returns a "descending" comparator, via ">", to be used to sort an array.
  * Undefined or null values are always sorted to the end.
- * @param {String=} key If sorting objects, can specify a key to use to compare.
+ * @param {string|number|Function=} transform
+ *  If a function, calls the provided function on an element to get the value to sort on.
+ *  If a string or number, treats transform as a key and sorts on each element's value at key.
  * @returns {Function}
  */
-export function descending(key) {
-  if (!key) {
+export function descending(transform) {
+  if (typeof transform === "function") {
     return (a, b) => {
+      a = transform(a)
+      b = transform(b)
       return compareUndefinedNull(a, b) ?? (a > b ? -1 : b > a ? 1 : 0)
     }
   }
+  if (typeof transform === "string" || typeof transform === "number") {
+    return (a, b) => {
+      const invalid = compareUndefinedNull(a[transform], b[transform])
+      return (
+        invalid ?? (a[transform] > b[transform] ? -1 : b[transform] > a[transform] ? 1 : 0)
+      )
+    }
+  }
   return (a, b) => {
-    return (
-      compareUndefinedNull(a[key], b[key]) ?? (a[key] > b[key] ? -1 : b[key] > a[key] ? 1 : 0)
-    )
+    return compareUndefinedNull(a, b) ?? (a > b ? -1 : b > a ? 1 : 0)
   }
 }
 
@@ -95,140 +115,3 @@ export function multilevel(...comparators) {
     return 0
   }
 }
-
-function findClosestAbs(array, value, { key, threshold = Infinity } = {}) {
-  let closest
-  if (key) {
-    for (const element of array) {
-      const _value = element[key]
-      const diff = Math.abs(_value - value)
-      if (diff < threshold) {
-        closest = element
-        threshold = diff
-      }
-    }
-  } else {
-    for (const _value of array) {
-      const diff = Math.abs(_value - value)
-      if (diff < threshold) {
-        closest = _value
-        threshold = diff
-      }
-    }
-  }
-  return closest
-}
-
-function findClosestLT(array, value, { key, threshold = -Infinity } = {}) {
-  let closest
-  if (key) {
-    for (const element of array) {
-      const _value = element[key]
-      if (_value < value && _value > threshold) {
-        closest = element
-        threshold = _value
-      }
-    }
-  } else {
-    for (const _value of array) {
-      if (_value < value && _value > threshold) {
-        closest = _value
-        threshold = _value
-      }
-    }
-  }
-  return closest
-}
-
-function findClosestLTE(array, value, { key, threshold = -Infinity } = {}) {
-  let closest
-  if (key) {
-    for (const element of array) {
-      const _value = element[key]
-      if (_value <= value && _value > threshold) {
-        closest = element
-        threshold = _value
-      }
-    }
-  } else {
-    for (const _value of array) {
-      if (_value <= value && _value > threshold) {
-        closest = _value
-        threshold = _value
-      }
-    }
-  }
-  return closest
-}
-
-function findClosestGT(array, value, { key, threshold = Infinity } = {}) {
-  let closest
-  if (key) {
-    for (const element of array) {
-      const _value = element[key]
-      if (_value > value && _value < threshold) {
-        closest = element
-        threshold = _value
-      }
-    }
-  } else {
-    for (const _value of array) {
-      if (_value > value && _value < threshold) {
-        closest = _value
-        threshold = _value
-      }
-    }
-  }
-  return closest
-}
-
-function findClosestGTE(array, value, { key, threshold = Infinity } = {}) {
-  let closest
-  if (key) {
-    for (const element of array) {
-      const _value = element[key]
-      if (_value >= value && _value < threshold) {
-        closest = element
-        threshold = _value
-      }
-    }
-  } else {
-    for (const _value of array) {
-      if (_value >= value && _value < threshold) {
-        closest = _value
-        threshold = _value
-      }
-    }
-  }
-  return closest
-}
-
-/**
- * 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.
- * @param {Array<T>} array
- * @param {T} value
- * @param {Object} options
- * @param {string=} options.key If specified, will consider the value for each element's key instead of the element itself.
- * @param {string=} options.comparator "abs", "lt", "lte", "gt", "gte", "abs". Default is "abs" which implies T is number.
- * @param {T=} options.threshold If specified, uses a different initial min/max/difference than positive or negative infinity.
- * @returns {T|undefined}
- */
-export function findClosest(array, value, options = {}) {
-  const { comparator = "abs" } = options
-  switch (comparator) {
-    case "lt":
-      return findClosestLT(array, value, options)
-    case "lte":
-      return findClosestLTE(array, value, options)
-    case "gt":
-      return findClosestGT(array, value, options)
-    case "gte":
-      return findClosestGTE(array, value, options)
-    case "abs":
-      return findClosestAbs(array, value, options)
-    default:
-      throw new Error(`Unknown comparator: ${comparator}`)
-  }
-}

package/src/array.test.js

@@ -1,6 +1,5 @@
 /* eslint-disable no-restricted-syntax */
 import { describe, expect, it, jest } from "@jest/globals"
-import { findClosest } from "./array.js"
 
 const { chunk, unique, ascending, descending, multilevel } = await import("./array.js")
 
@@ -110,6 +109,24 @@ describe("ascending", () => {
     arr.sort(ascending("v"))
     expect(arr.map((o) => o.v)).toEqual([1, 2, undefined])
   })
+
+  it("sorts using a transform function", () => {
+    const arr = [{ v: 2 }, { v: 1 }, { v: 3 }]
+    arr.sort(ascending((o) => o.v))
+    expect(arr.map((o) => o.v)).toEqual([1, 2, 3])
+  })
+
+  it("sorts using a numeric key", () => {
+    const arr = [{ 0: 2 }, { 0: 1 }, { 0: 3 }]
+    arr.sort(ascending(0))
+    expect(arr.map((o) => o[0])).toEqual([1, 2, 3])
+  })
+
+  it("sorts using a function that returns undefined/null", () => {
+    const arr = [{ v: 2 }, {}, { v: 1 }, { v: null }]
+    arr.sort(ascending((o) => o.v))
+    expect(arr.map((o) => o.v)).toEqual([1, 2, undefined, null])
+  })
 })
 
 describe("descending", () => {
@@ -151,6 +168,24 @@ describe("descending", () => {
     arr.sort(descending("v"))
     expect(arr.map((o) => o.v)).toEqual([3, 2, undefined])
   })
+
+  it("sorts using a transform function", () => {
+    const arr = [{ v: 2 }, { v: 1 }, { v: 3 }]
+    arr.sort(descending((o) => o.v))
+    expect(arr.map((o) => o.v)).toEqual([3, 2, 1])
+  })
+
+  it("sorts using a numeric key", () => {
+    const arr = [{ 0: 2 }, { 0: 1 }, { 0: 3 }]
+    arr.sort(descending(0))
+    expect(arr.map((o) => o[0])).toEqual([3, 2, 1])
+  })
+
+  it("sorts using a function that returns undefined/null", () => {
+    const arr = [{ v: 2 }, {}, { v: 1 }, { v: null }]
+    arr.sort(descending((o) => o.v))
+    expect(arr.map((o) => o.v)).toEqual([2, 1, undefined, null])
+  })
 })
 
 describe("multilevel", () => {
@@ -219,153 +254,3 @@ describe("multilevel", () => {
     expect(cmp("a", "b")).toBe(0)
   })
 })
-
-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)
-  })
-
-  it("returns undefined if array is empty", () => {
-    expect(findClosest([], 10)).toBeUndefined()
-  })
-
-  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 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("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("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("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("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 })
-  })
-
-  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("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("throws for unknown comparator", () => {
-    expect(() => findClosest([1, 2, 3], 2, { comparator: "foo" })).toThrow(
-      "Unknown comparator: foo"
-    )
-  })
-
-  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)
-  })
-
-  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()
-  })
-})

package/src/find.js

@@ -0,0 +1,190 @@
+export function findClosestAbs(array, desired, { key, map, threshold = Infinity } = {}) {
+  let closest
+  if (map) {
+    for (let i = 0; i < array.length; i++) {
+      const element = array[i]
+      const value = map(element, i, array)
+      const diff = Math.abs(value - desired)
+      if (diff < threshold) {
+        closest = element
+        threshold = diff
+      }
+    }
+  } else if (key) {
+    for (const element of array) {
+      const value = element[key]
+      const diff = Math.abs(value - desired)
+      if (diff < threshold) {
+        closest = element
+        threshold = diff
+      }
+    }
+  } else {
+    for (const value of array) {
+      const diff = Math.abs(value - desired)
+      if (diff < threshold) {
+        closest = value
+        threshold = diff
+      }
+    }
+  }
+  return closest
+}
+
+export function findClosestLT(array, desired, { key, map, threshold = -Infinity } = {}) {
+  let closest
+  if (map) {
+    for (let i = 0; i < array.length; i++) {
+      const element = array[i]
+      const value = map(element, i, array)
+      if (value < desired && value > threshold) {
+        closest = element
+        threshold = value
+      }
+    }
+  } else if (key) {
+    for (const element of array) {
+      const value = element[key]
+      if (value < desired && value > threshold) {
+        closest = element
+        threshold = value
+      }
+    }
+  } else {
+    for (const value of array) {
+      if (value < desired && value > threshold) {
+        closest = value
+        threshold = value
+      }
+    }
+  }
+  return closest
+}
+
+export function findClosestLTE(array, desired, { key, map, threshold = -Infinity } = {}) {
+  let closest
+  if (map) {
+    for (let i = 0; i < array.length; i++) {
+      const element = array[i]
+      const value = map(element, i, array)
+      if (value <= desired && value > threshold) {
+        closest = element
+        threshold = value
+      }
+    }
+  } else if (key) {
+    for (const element of array) {
+      const value = element[key]
+      if (value <= desired && value > threshold) {
+        closest = element
+        threshold = value
+      }
+    }
+  } else {
+    for (const value of array) {
+      if (value <= desired && value > threshold) {
+        closest = value
+        threshold = value
+      }
+    }
+  }
+  return closest
+}
+
+export function findClosestGT(array, desired, { key, map, threshold = Infinity } = {}) {
+  let closest
+  if (map) {
+    for (let i = 0; i < array.length; i++) {
+      const element = array[i]
+      const value = map(element, i, array)
+      if (value > desired && value < threshold) {
+        closest = element
+        threshold = value
+      }
+    }
+  } else if (key) {
+    for (const element of array) {
+      const value = element[key]
+      if (value > desired && value < threshold) {
+        closest = element
+        threshold = value
+      }
+    }
+  } else {
+    for (const value of array) {
+      if (value > desired && value < threshold) {
+        closest = value
+        threshold = value
+      }
+    }
+  }
+  return closest
+}
+
+export function findClosestGTE(array, desired, { key, map, threshold = Infinity } = {}) {
+  let closest
+  if (map) {
+    for (let i = 0; i < array.length; i++) {
+      const element = array[i]
+      const value = map(element, i, array)
+      if (value >= desired && value < threshold) {
+        closest = element
+        threshold = value
+      }
+    }
+  } else if (key) {
+    for (const element of array) {
+      const value = element[key]
+      if (value >= desired && value < threshold) {
+        closest = element
+        threshold = value
+      }
+    }
+  } else {
+    for (const value of array) {
+      if (value >= desired && value < threshold) {
+        closest = value
+        threshold = value
+      }
+    }
+  }
+  return closest
+}
+
+/**
+ * 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.
+ * @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=} 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.
+ * @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 }
+  }
+  switch (comparator) {
+    case "lt":
+      return findClosestLT(array, value, options)
+    case "lte":
+      return findClosestLTE(array, value, options)
+    case "gt":
+      return findClosestGT(array, value, options)
+    case "gte":
+      return findClosestGTE(array, value, options)
+    case "abs":
+      return findClosestAbs(array, value, options)
+    default:
+      throw new Error(`Unknown comparator: ${comparator}`)
+  }
+}

package/src/find.test.js

@@ -0,0 +1,335 @@
+import {
+  findClosest,
+  findClosestAbs,
+  findClosestGT,
+  findClosestGTE,
+  findClosestLT,
+  findClosestLTE,
+} from "./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)
+  })
+
+  it("returns undefined if array is empty", () => {
+    expect(findClosest([], 10)).toBeUndefined()
+  })
+
+  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 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("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("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("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("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 })
+  })
+
+  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("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("throws for unknown comparator", () => {
+    expect(() => findClosest([1, 2, 3], 2, { comparator: "foo" })).toThrow(
+      "Unknown comparator: foo"
+    )
+  })
+
+  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 })
+  })
+})
+
+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)
+  })
+
+  it("returns undefined for empty array", () => {
+    expect(findClosestAbs([], 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("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("respects threshold", () => {
+    expect(findClosestAbs([1, 5, 10], 6, { threshold: 0.5 })).toBeUndefined()
+    expect(findClosestAbs([1, 5, 10], 6, { threshold: 2 })).toBe(5)
+  })
+
+  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 })
+  })
+})
+
+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()
+  })
+
+  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 closest object by map", () => {
+    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
+    expect(findClosestLT(arr, 6, { map: (el) => el.v })).toEqual({ v: 5 })
+  })
+
+  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("returns undefined for empty array", () => {
+    expect(findClosestLT([], 10)).toBeUndefined()
+  })
+})
+
+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("returns closest object by key", () => {
+    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
+    expect(findClosestLTE(arr, 6, { key: "v" })).toEqual({ v: 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 })
+  })
+
+  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 undefined for empty array", () => {
+    expect(findClosestLTE([], 10)).toBeUndefined()
+  })
+})
+
+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()
+  })
+
+  it("returns closest object by key", () => {
+    const arr = [{ v: 1 }, { v: 5 }, { v: 10 }]
+    expect(findClosestGT(arr, 6, { key: "v" })).toEqual({ v: 10 })
+  })
+
+  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("respects threshold", () => {
+    expect(findClosestGT([1, 3, 5, 7], 6, { threshold: 7 })).toBeUndefined()
+    expect(findClosestGT([1, 3, 5, 7], 6, { threshold: 10 })).toBe(7)
+  })
+
+  it("returns undefined for empty array", () => {
+    expect(findClosestGT([], 10)).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 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("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("respects threshold", () => {
+    expect(findClosestGTE([1, 3, 5, 7], 6, { threshold: 7 })).toBeUndefined()
+    expect(findClosestGTE([1, 3, 5, 7], 6, { threshold: 10 })).toBe(7)
+  })
+
+  it("returns undefined for empty array", () => {
+    expect(findClosestGTE([], 10)).toBeUndefined()
+  })
+})

package/src/index.js

@@ -1,4 +1,5 @@
 export * from "./array.js"
+export { findClosest } from "./find.js"
 export * from "./math.js"
 export * from "./object.js"
 export * from "./promise.js"

package/src/time.js

@@ -152,7 +152,7 @@ export function getTimeRange(start, end, { hours = 0, minutes = 1 } = {}) {
  * @param {number} days
  * @returns {string}
  */
-export function addDays(dateString, days = 0) {
+export function addDays(dateString, { days = 0 } = {}) {
   const [year, month, day] = dateString.split("-").map(Number)
   const date = new Date(Date.UTC(year, month - 1, day))
   date.setUTCDate(date.getUTCDate() + days)
@@ -169,7 +169,7 @@ export function getDateRange(start, end, { limit = 1000 } = {}) {
   const dates = []
   while (start <= end) {
     dates.push(start)
-    start = addDays(start, 1)
+    start = addDays(start, { days: 1 })
     if (dates.length >= limit) {
       break
     }

package/src/time.test.js

@@ -364,53 +364,49 @@ describe("getTimeRange", () => {
 })
 
 describe("addDays", () => {
-  test("adds days within the same month", () => {
-    expect(addDays("2024-06-01", 5)).toBe("2024-06-06")
-    expect(addDays("2024-06-10", 0)).toBe("2024-06-10")
+  test("adds days within the same month (object param)", () => {
+    expect(addDays("2024-06-01", { days: 5 })).toBe("2024-06-06")
+    expect(addDays("2024-06-10", { days: 0 })).toBe("2024-06-10")
   })
 
-  test("adds days with month rollover", () => {
-    expect(addDays("2024-06-28", 5)).toBe("2024-07-03")
+  test("adds days with month rollover (object param)", () => {
+    expect(addDays("2024-06-28", { days: 5 })).toBe("2024-07-03")
   })
 
-  test("adds days with year rollover", () => {
-    expect(addDays("2024-12-30", 5)).toBe("2025-01-04")
+  test("adds days with year rollover (object param)", () => {
+    expect(addDays("2024-12-30", { days: 5 })).toBe("2025-01-04")
   })
 
-  test("subtracts days", () => {
-    expect(addDays("2024-06-10", -10)).toBe("2024-05-31")
+  test("subtracts days (object param)", () => {
+    expect(addDays("2024-06-10", { days: -10 })).toBe("2024-05-31")
   })
 
-  test("handles leap years", () => {
-    expect(addDays("2024-02-28", 1)).toBe("2024-02-29")
-    expect(addDays("2024-02-28", 2)).toBe("2024-03-01")
-    expect(addDays("2023-02-28", 1)).toBe("2023-03-01")
+  test("handles leap years (object param)", () => {
+    expect(addDays("2024-02-28", { days: 1 })).toBe("2024-02-29")
+    expect(addDays("2024-02-28", { days: 2 })).toBe("2024-03-01")
+    expect(addDays("2023-02-28", { days: 1 })).toBe("2023-03-01")
   })
 
-  test("handles negative result across year boundary", () => {
-    expect(addDays("2024-01-01", -1)).toBe("2023-12-31")
+  test("handles negative result across year boundary (object param)", () => {
+    expect(addDays("2024-01-01", { days: -1 })).toBe("2023-12-31")
   })
 
   // DST boundary: adding days across US DST start (spring forward)
-  test("adds days across DST start (spring forward)", () => {
-    // DST starts in US/Eastern on 2024-03-10
-    // Adding 1 day to 2024-03-09 should yield 2024-03-10
-    expect(addDays("2024-03-09", 1)).toBe("2024-03-10")
-    // Adding 2 days to 2024-03-09 should yield 2024-03-11
-    expect(addDays("2024-03-09", 2)).toBe("2024-03-11")
-    // Subtracting 1 day from 2024-03-10 should yield 2024-03-09
-    expect(addDays("2024-03-10", -1)).toBe("2024-03-09")
+  test("adds days across DST start (spring forward) (object param)", () => {
+    expect(addDays("2024-03-09", { days: 1 })).toBe("2024-03-10")
+    expect(addDays("2024-03-09", { days: 2 })).toBe("2024-03-11")
+    expect(addDays("2024-03-10", { days: -1 })).toBe("2024-03-09")
   })
 
   // DST boundary: adding days across US DST end (fall back)
-  test("adds days across DST end (fall back)", () => {
-    // DST ends in US/Eastern on 2024-11-03
-    // Adding 1 day to 2024-11-02 should yield 2024-11-03
-    expect(addDays("2024-11-02", 1)).toBe("2024-11-03")
-    // Adding 2 days to 2024-11-02 should yield 2024-11-04
-    expect(addDays("2024-11-02", 2)).toBe("2024-11-04")
-    // Subtracting 1 day from 2024-11-03 should yield 2024-11-02
-    expect(addDays("2024-11-03", -1)).toBe("2024-11-02")
+  test("adds days across DST end (fall back) (object param)", () => {
+    expect(addDays("2024-11-02", { days: 1 })).toBe("2024-11-03")
+    expect(addDays("2024-11-02", { days: 2 })).toBe("2024-11-04")
+    expect(addDays("2024-11-03", { days: -1 })).toBe("2024-11-02")
+  })
+
+  test("accepts missing options argument (defaults to days = 0)", () => {
+    expect(addDays("2024-06-10")).toBe("2024-06-10")
   })
 })