@tim-code/my-util 0.4.10 → 0.5.1

package/package.json

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

package/src/find.js

@@ -1,11 +1,37 @@
-export function findClosestAbs(array, desired, { key, cutoff = Infinity } = {}) {
+export function findEq(array, desired, { key } = {}) {
+  if (typeof key === "function") {
+    for (let i = 0; i < array.length; i++) {
+      const element = array[i]
+      const value = key(element, i, array)
+      if (value === desired) {
+        return value
+      }
+    }
+  } else if (typeof key === "number" || typeof key === "string") {
+    for (const element of array) {
+      const value = element[key]
+      if (value === desired) {
+        return value
+      }
+    }
+  } else {
+    for (const value of array) {
+      if (value === desired) {
+        return value
+      }
+    }
+  }
+  return undefined
+}
+
+export function findSmallestDiff(array, desired, { 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)
       const diff = Math.abs(value - desired)
-      if (diff < cutoff) {
+      if (diff < cutoff || (diff === cutoff && !closest)) {
         closest = element
         cutoff = diff
       }
@@ -14,7 +40,7 @@ export function findClosestAbs(array, desired, { key, cutoff = Infinity } = {})
     for (const element of array) {
       const value = element[key]
       const diff = Math.abs(value - desired)
-      if (diff < cutoff) {
+      if (diff < cutoff || (diff === cutoff && !closest)) {
         closest = element
         cutoff = diff
       }
@@ -22,7 +48,7 @@ export function findClosestAbs(array, desired, { key, cutoff = Infinity } = {})
   } else {
     for (const value of array) {
       const diff = Math.abs(value - desired)
-      if (diff < cutoff) {
+      if (diff < cutoff || (diff === cutoff && !closest)) {
         closest = value
         cutoff = diff
       }
@@ -37,7 +63,7 @@ export function findClosestLT(array, desired, { key, cutoff = -Infinity } = {})
     for (let i = 0; i < array.length; i++) {
       const element = array[i]
       const value = key(element, i, array)
-      if (value < desired && value > cutoff) {
+      if (value < desired && (value > cutoff || (value === cutoff && !closest))) {
         closest = element
         cutoff = value
       }
@@ -45,14 +71,14 @@ export function findClosestLT(array, desired, { key, cutoff = -Infinity } = {})
   } else if (typeof key === "number" || typeof key === "string") {
     for (const element of array) {
       const value = element[key]
-      if (value < desired && value > cutoff) {
+      if (value < desired && (value > cutoff || (value === cutoff && !closest))) {
         closest = element
         cutoff = value
       }
     }
   } else {
     for (const value of array) {
-      if (value < desired && value > cutoff) {
+      if (value < desired && (value > cutoff || (value === cutoff && !closest))) {
         closest = value
         cutoff = value
       }
@@ -67,7 +93,7 @@ export function findClosestLTE(array, desired, { key, cutoff = -Infinity } = {})
     for (let i = 0; i < array.length; i++) {
       const element = array[i]
       const value = key(element, i, array)
-      if (value <= desired && value > cutoff) {
+      if (value <= desired && (value > cutoff || (value === cutoff && !closest))) {
         closest = element
         cutoff = value
       }
@@ -75,14 +101,14 @@ export function findClosestLTE(array, desired, { key, cutoff = -Infinity } = {})
   } else if (typeof key === "number" || typeof key === "string") {
     for (const element of array) {
       const value = element[key]
-      if (value <= desired && value > cutoff) {
+      if (value <= desired && (value > cutoff || (value === cutoff && !closest))) {
         closest = element
         cutoff = value
       }
     }
   } else {
     for (const value of array) {
-      if (value <= desired && value > cutoff) {
+      if (value <= desired && (value > cutoff || (value === cutoff && !closest))) {
         closest = value
         cutoff = value
       }
@@ -97,7 +123,7 @@ export function findClosestGT(array, desired, { key, cutoff = Infinity } = {}) {
     for (let i = 0; i < array.length; i++) {
       const element = array[i]
       const value = key(element, i, array)
-      if (value > desired && value < cutoff) {
+      if (value > desired && (value < cutoff || (value === cutoff && !closest))) {
         closest = element
         cutoff = value
       }
@@ -105,14 +131,14 @@ export function findClosestGT(array, desired, { key, cutoff = Infinity } = {}) {
   } else if (typeof key === "number" || typeof key === "string") {
     for (const element of array) {
       const value = element[key]
-      if (value > desired && value < cutoff) {
+      if (value > desired && (value < cutoff || (value === cutoff && !closest))) {
         closest = element
         cutoff = value
       }
     }
   } else {
     for (const value of array) {
-      if (value > desired && value < cutoff) {
+      if (value > desired && (value < cutoff || (value === cutoff && !closest))) {
         closest = value
         cutoff = value
       }
@@ -127,7 +153,7 @@ export function findClosestGTE(array, desired, { key, cutoff = Infinity } = {})
     for (let i = 0; i < array.length; i++) {
       const element = array[i]
       const value = key(element, i, array)
-      if (value >= desired && value < cutoff) {
+      if (value >= desired && (value < cutoff || (value === cutoff && !closest))) {
         closest = element
         cutoff = value
       }
@@ -135,14 +161,14 @@ export function findClosestGTE(array, desired, { key, cutoff = Infinity } = {})
   } else if (typeof key === "number" || typeof key === "string") {
     for (const element of array) {
       const value = element[key]
-      if (value >= desired && value < cutoff) {
+      if (value >= desired && (value < cutoff || (value === cutoff && !closest))) {
         closest = element
         cutoff = value
       }
     }
   } else {
     for (const value of array) {
-      if (value >= desired && value < cutoff) {
+      if (value >= desired && (value < cutoff || (value === cutoff && !closest))) {
         closest = value
         cutoff = value
       }
@@ -163,14 +189,16 @@ export function findClosestGTE(array, desired, { key, cutoff = Infinity } = {})
  * @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 {string=} options.comparator "diff", "lt", "lte", "gt", "gte", "eq". Default is "diff" which implies T is number.
  * @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.
+ *  If used with lt, lte, value must be greater than or equal to cutoff.
+ *  If used with gt, gte, value must be less than or equal to cutoff.
+ *  If used with diff, value's difference with desired must be less than or equal to cutoff.
+ *  No effect with eq.
  * @returns {T|undefined}
  */
 export function findClosest(array, value, options = {}) {
-  const { comparator = "abs" } = options
+  const { comparator = "diff" } = options
   switch (comparator) {
     case "lt":
       return findClosestLT(array, value, options)
@@ -180,15 +208,17 @@ export function findClosest(array, value, options = {}) {
       return findClosestGT(array, value, options)
     case "gte":
       return findClosestGTE(array, value, options)
-    case "abs":
-      return findClosestAbs(array, value, options)
+    case "diff":
+      return findSmallestDiff(array, value, options)
+    case "eq":
+      return findEq(array, value, options)
     default:
       throw new Error(`unknown comparator: ${comparator}`)
   }
 }
 
 /**
- * Find the minimum value in an array.
+ * Find the minimum value in an array. undefined or null values are ignored.
  * @template T, V
  * @param {Array<T>} array
  * @param {Object} $1
@@ -196,7 +226,7 @@ export function findClosest(array, value, options = {}) {
  *  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}
+ * @returns {T|undefined}
  */
 export function findMin(array, { key, cutoff = Infinity } = {}) {
   let closest
@@ -229,7 +259,7 @@ export function findMin(array, { key, cutoff = Infinity } = {}) {
 }
 
 /**
- * Find the maximum value in an array.
+ * Find the maximum value in an array. undefined or null values are ignored.
  * @template T, V
  * @param {Array<T>} array
  * @param {Object} $1
@@ -237,7 +267,7 @@ export function findMin(array, { key, cutoff = Infinity } = {}) {
  *  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}
+ * @returns {T|undefined}
  */
 export function findMax(array, { key, cutoff = -Infinity } = {}) {
   let closest

package/src/find.test.js

@@ -2,7 +2,8 @@
 import { describe, expect, it } from "@jest/globals"
 
 const {
-  findClosestAbs,
+  findEq,
+  findSmallestDiff,
   findClosestLT,
   findClosestLTE,
   findClosestGT,
@@ -13,39 +14,75 @@ const {
   findTruthy,
 } = await import("./find.js")
 
-describe("findClosestAbs", () => {
+describe("findEq", () => {
+  it("returns the first element equal to desired (no key)", () => {
+    expect(findEq([1, 2, 3, 2], 2)).toBe(2)
+    expect(findEq([1, 2, 3], 4)).toBeUndefined()
+  })
+
+  it("returns the first value from key function equal to desired", () => {
+    const arr = [{ v: 1 }, { v: 2 }, { v: 3 }]
+    expect(findEq(arr, 2, { key: (e) => e.v })).toBe(2)
+    expect(findEq(arr, 4, { key: (e) => e.v })).toBeUndefined()
+  })
+
+  it("returns the first value from key string equal to desired", () => {
+    const arr = [{ x: 1 }, { x: 2 }, { x: 3 }]
+    expect(findEq(arr, 2, { key: "x" })).toBe(2)
+    expect(findEq(arr, 4, { key: "x" })).toBeUndefined()
+  })
+
+  it("returns the first value from key number equal to desired", () => {
+    const arr = [[1], [2], [3]]
+    expect(findEq(arr, 2, { key: 0 })).toBe(2)
+    expect(findEq(arr, 4, { key: 0 })).toBeUndefined()
+  })
+
+  it("returns undefined for empty array", () => {
+    expect(findEq([], 1)).toBeUndefined()
+  })
+
+  it("returns first matching value if there are duplicates", () => {
+    expect(findEq([2, 2, 3], 2)).toBe(2)
+    const arr = [{ v: 2 }, { v: 2 }]
+    expect(findEq(arr, 2, { key: (e) => e.v })).toBe(2)
+  })
+})
+
+describe("findSmallestDiff", () => {
   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)
+    expect(findSmallestDiff([1, 5, 9], 6)).toBe(5)
+    expect(findSmallestDiff([1, 5, 9], 8)).toBe(9)
+    expect(findSmallestDiff([1, 5, 9], 1)).toBe(1)
   })
 
   it("returns the first element in case of tie", () => {
-    expect(findClosestAbs([4, 8], 6)).toBe(4)
+    expect(findSmallestDiff([4, 8], 6)).toBe(4)
   })
 
   it("returns undefined for empty array", () => {
-    expect(findClosestAbs([], 10)).toBeUndefined()
+    expect(findSmallestDiff([], 10)).toBeUndefined()
   })
 
   it("supports key as function", () => {
     const arr = [{ v: 2 }, { v: 8 }]
-    expect(findClosestAbs(arr, 5, { key: (e) => e.v })).toEqual({ v: 2 })
+    expect(findSmallestDiff(arr, 5, { key: (e) => e.v })).toEqual({ v: 2 })
   })
 
   it("supports key as string", () => {
     const arr = [{ x: 1 }, { x: 10 }]
-    expect(findClosestAbs(arr, 8, { key: "x" })).toEqual({ x: 10 })
+    expect(findSmallestDiff(arr, 8, { key: "x" })).toEqual({ x: 10 })
   })
 
   it("supports key as number", () => {
     const arr = [[2], [8]]
-    expect(findClosestAbs(arr, 7, { key: 0 })).toEqual([8])
+    expect(findSmallestDiff(arr, 7, { key: 0 })).toEqual([8])
   })
 
   it("respects cutoff", () => {
-    expect(findClosestAbs([1, 5, 9], 6, { cutoff: 2 })).toBe(5)
-    expect(findClosestAbs([1, 5, 9], 6, { cutoff: 1 })).toBeUndefined()
+    expect(findSmallestDiff([1, 5, 9], 6, { cutoff: 2 })).toBe(5)
+    expect(findSmallestDiff([1, 5, 9], 6, { cutoff: 1 })).toBe(5)
+    expect(findSmallestDiff([1, 5, 9], 6, { cutoff: 0 })).toBeUndefined()
   })
 })
 
@@ -81,7 +118,8 @@ describe("findClosestLT", () => {
 
   it("respects cutoff", () => {
     expect(findClosestLT([1, 5, 9], 6, { cutoff: 4 })).toBe(5)
-    expect(findClosestLT([1, 5, 9], 6, { cutoff: 5 })).toBeUndefined()
+    expect(findClosestLT([1, 5, 9], 6, { cutoff: 5 })).toBe(5)
+    expect(findClosestLT([1, 5, 9], 6, { cutoff: 6 })).toBe(undefined)
   })
 })
 
@@ -118,7 +156,8 @@ describe("findClosestLTE", () => {
 
   it("respects cutoff", () => {
     expect(findClosestLTE([1, 5, 9], 6, { cutoff: 4 })).toBe(5)
-    expect(findClosestLTE([1, 5, 9], 6, { cutoff: 5 })).toBeUndefined()
+    expect(findClosestLTE([1, 5, 9], 6, { cutoff: 5 })).toBe(5)
+    expect(findClosestLTE([1, 5, 9], 6, { cutoff: 6 })).toBe(undefined)
   })
 })
 
@@ -153,8 +192,9 @@ describe("findClosestGT", () => {
   })
 
   it("respects cutoff", () => {
-    expect(findClosestGT([1, 5, 9], 6, { cutoff: 8 })).toBeUndefined()
-    expect(findClosestGT([1, 5, 9], 4, { cutoff: 8 })).toBe(5)
+    expect(findClosestGTE([1, 5, 9], 6, { cutoff: 10 })).toBe(9)
+    expect(findClosestGTE([1, 5, 9], 6, { cutoff: 9 })).toBe(9)
+    expect(findClosestGTE([1, 5, 9], 6, { cutoff: 8 })).toBeUndefined()
   })
 })
 
@@ -189,13 +229,14 @@ describe("findClosestGTE", () => {
   })
 
   it("respects cutoff", () => {
+    expect(findClosestGTE([1, 5, 9], 6, { cutoff: 10 })).toBe(9)
+    expect(findClosestGTE([1, 5, 9], 6, { cutoff: 9 })).toBe(9)
     expect(findClosestGTE([1, 5, 9], 6, { cutoff: 8 })).toBeUndefined()
-    expect(findClosestGTE([1, 5, 9], 4, { cutoff: 8 })).toBe(5)
   })
 })
 
 describe("findClosest", () => {
-  it("defaults to abs comparator", () => {
+  it("defaults to diff comparator", () => {
     expect(findClosest([1, 5, 9], 6)).toBe(5)
   })
 
@@ -204,7 +245,9 @@ describe("findClosest", () => {
     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)
+    expect(findClosest([1, 5, 9], 6, { comparator: "diff" })).toBe(5)
+    expect(findClosest([1, 5, 9], 6, { comparator: "eq" })).toBeUndefined()
+    expect(findClosest([1, 5, 9], 5, { comparator: "eq" })).toBe(5)
   })
 
   it("throws on unknown comparator", () => {
@@ -215,7 +258,8 @@ describe("findClosest", () => {
 
   it("passes options to underlying function", () => {
     const arr = [{ x: 1 }, { x: 10 }]
-    expect(findClosest(arr, 8, { comparator: "abs", key: "x" })).toEqual({ x: 10 })
+    expect(findClosest(arr, 8, { comparator: "diff", key: "x" })).toEqual({ x: 10 })
+    expect(findClosest(arr, 10, { comparator: "eq", key: "x" })).toBe(10)
   })
 })