@tim-code/my-util 0.4.8 → 0.4.10

package/package.json

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

package/src/find.js

@@ -271,39 +271,83 @@ export function findMax(array, { key, cutoff = -Infinity } = {}) {
 
 /**
  * Find the first truthy value in an array.
- * Supports "from" and "to" being reversed to "find last truthy".
+ * Supports "from" and "to"/"until" being reversed to "find last truthy" if "reverse" is true.
  * @template T
  * @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 {number=} $1.from Numeric index to start from: inclusive, defaults to 0
+ * @param {number=} $1.from Numeric index to start from: inclusive, defaults to `0`
  * @param {number=} $1.until Numeric index to end at: exclusive, defaults to `array.length`
+ * @param {number=} $1.to Numeric index to end at: inclusive, defaults to `array.length - 1`; takes precedence over "until"
+ * @param {boolean=} $1.reverse If true, looks through the array in reverse. Default is false.
+ *  When true, findTruthy() will still start from "from" and end at "to"/"until".
+ *  When true, changes the default values of "from", "until", "to" to `array.length - 1`, `-1`, `0`.
  * @returns {T}
  */
-export function findTruthy(array, { key, from = 0, until = array.length } = {}) {
+// eslint-disable-next-line complexity
+export function findTruthy(
+  array,
+  {
+    key,
+    reverse = false,
+    from = reverse ? array.length - 1 : 0,
+    until = reverse ? -1 : array.length,
+    to = reverse ? until + 1 : until - 1,
+  } = {}
+) {
   if (typeof key === "function") {
-    for (let i = from; i < until; i++) {
-      const element = array[i]
-      const value = key(element, i, array)
-      if (value) {
-        return element
+    if (reverse) {
+      for (let i = from; i >= to; i--) {
+        const element = array[i]
+        const value = key(element, i, array)
+        if (value) {
+          return element
+        }
+      }
+    } else {
+      for (let i = from; i <= to; i++) {
+        const element = array[i]
+        const value = key(element, i, array)
+        if (value) {
+          return element
+        }
       }
     }
   } else if (typeof key === "number" || typeof key === "string") {
-    for (let i = from; i < until; i++) {
-      const element = array[i]
-      const value = element[key]
-      if (value) {
-        return element
+    if (reverse) {
+      for (let i = from; i >= to; i--) {
+        const element = array[i]
+        const value = element[key]
+        if (value) {
+          return element
+        }
+      }
+    } else {
+      for (let i = from; i <= to; i++) {
+        const element = array[i]
+        const value = element[key]
+        if (value) {
+          return element
+        }
       }
     }
   } else {
-    for (let i = from; i < until; i++) {
-      const value = array[i]
-      if (value) {
-        return value
+    // eslint-disable-next-line no-lonely-if
+    if (reverse) {
+      for (let i = from; i >= to; i--) {
+        const value = array[i]
+        if (value) {
+          return value
+        }
+      }
+    } else {
+      for (let i = from; i <= to; i++) {
+        const value = array[i]
+        if (value) {
+          return value
+        }
       }
     }
   }

package/src/find.test.js

@@ -323,4 +323,116 @@ describe("findTruthy", () => {
     expect(findTruthy([0, 1, 2], { from: 2, until: 2 })).toBeUndefined()
     expect(findTruthy([0, 1, 2], { from: 3, until: 2 })).toBeUndefined()
   })
+
+  it("respects the new 'to' option (inclusive end)", () => {
+    const arr = [0, 1, 2, 3]
+    expect(findTruthy(arr, { from: 1, to: 2 })).toBe(1)
+    expect(findTruthy(arr, { from: 2, to: 3 })).toBe(2)
+    expect(findTruthy(arr, { from: 2, to: 2 })).toBe(2)
+    expect(findTruthy(arr, { from: 2, to: 1 })).toBeUndefined()
+    expect(findTruthy(arr, { from: 0, to: 0 })).toBeUndefined()
+    expect(findTruthy(arr, { from: 1, to: 1 })).toBe(1)
+  })
+
+  it("prefers 'to' over 'until' if both are given", () => {
+    const arr = [0, 1, 2, 3]
+    // 'to' = 1, so only index 1 is checked, even though until=4
+    expect(findTruthy(arr, { from: 1, until: 4, to: 1 })).toBe(1)
+    // 'to' = 2, so indices 1 and 2 checked, even though until=2 (which would skip 2)
+    expect(findTruthy(arr, { from: 1, until: 2, to: 2 })).toBe(1)
+  })
+
+  it("works with key as function and 'to'", () => {
+    const arr = [{ v: 0 }, { v: 0 }, { v: 2 }, { v: 3 }]
+    expect(findTruthy(arr, { key: (e) => e.v, from: 1, to: 2 })).toEqual({ v: 2 })
+    expect(findTruthy(arr, { key: (e) => e.v, from: 1, to: 1 })).toBeUndefined()
+  })
+
+  it("works with key as string and 'to'", () => {
+    const arr = [{ x: 0 }, { x: 2 }, { x: 0 }]
+    expect(findTruthy(arr, { key: "x", from: 0, to: 1 })).toEqual({ x: 2 })
+    expect(findTruthy(arr, { key: "x", from: 1, to: 1 })).toEqual({ x: 2 })
+    expect(findTruthy(arr, { key: "x", from: 2, to: 1 })).toBeUndefined()
+  })
+
+  it("works with key as number and 'to'", () => {
+    const arr = [[0], [2], [0]]
+    expect(findTruthy(arr, { key: 0, from: 0, to: 1 })).toEqual([2])
+    expect(findTruthy(arr, { key: 0, from: 1, to: 1 })).toEqual([2])
+    expect(findTruthy(arr, { key: 0, from: 2, to: 1 })).toBeUndefined()
+  })
+
+  // New tests for reverse mode and its interaction with from, to, until
+  it("finds last truthy value with reverse=true and default from/to", () => {
+    const arr = [0, 1, 2, 3, 0]
+    expect(findTruthy(arr, { reverse: true })).toBe(3)
+  })
+
+  it("finds last truthy value with reverse=true and custom from/to", () => {
+    const arr = [0, 1, 2, 3, 4]
+    // from=3, to=1 (reverse), should check indices 3,2,1
+    expect(findTruthy(arr, { reverse: true, from: 3, to: 1 })).toBe(3)
+    // from=4, to=2, should check 4,3,2
+    expect(findTruthy(arr, { reverse: true, from: 4, to: 2 })).toBe(4)
+    // from=2, to=0, should check 2,1,0
+    expect(findTruthy(arr, { reverse: true, from: 2, to: 0 })).toBe(2)
+    // from=2, to=2, should check only 2
+    expect(findTruthy(arr, { reverse: true, from: 2, to: 2 })).toBe(2)
+    // from=2, to=3, should check 2,1,0 (since to > from, loop doesn't run)
+    expect(findTruthy(arr, { reverse: true, from: 2, to: 3 })).toBeUndefined()
+  })
+
+  it("finds last truthy value with reverse=true and until", () => {
+    const arr = [0, 1, 2, 3, 0]
+    // until=1, so to=until+1=2, from=4, should check 4,3,2
+    expect(findTruthy(arr, { reverse: true, until: 1 })).toBe(3)
+    expect(findTruthy(arr, { reverse: true, until: 2 })).toBe(3)
+    expect(findTruthy(arr, { reverse: true, until: 3 })).toBe(undefined)
+  })
+
+  it("finds last truthy value with reverse=true and key as function", () => {
+    const arr = [{ v: 0 }, { v: 2 }, { v: 0 }]
+    expect(findTruthy(arr, { key: (e) => e.v, reverse: true })).toEqual({ v: 2 })
+  })
+
+  it("finds last truthy value with reverse=true and key as string", () => {
+    const arr = [{ x: 0 }, { x: 2 }, { x: 0 }]
+    expect(findTruthy(arr, { key: "x", reverse: true })).toEqual({ x: 2 })
+  })
+
+  it("finds last truthy value with reverse=true and key as number", () => {
+    const arr = [[0], [2], [0]]
+    expect(findTruthy(arr, { key: 0, reverse: true })).toEqual([2])
+  })
+
+  it("returns undefined if no truthy value in reverse mode", () => {
+    expect(findTruthy([0, 0, 0], { reverse: true })).toBeUndefined()
+  })
+
+  it("returns undefined if reverse=true and from < to", () => {
+    expect(findTruthy([0, 1, 2], { reverse: true, from: 0, to: 2 })).toBeUndefined()
+  })
+
+  it("reverse=true with custom from/to and key as function", () => {
+    const arr = [{ v: 0 }, { v: 2 }, { v: 0 }, { v: 3 }]
+    expect(findTruthy(arr, { key: (e) => e.v, reverse: true, from: 2, to: 1 })).toEqual({
+      v: 2,
+    })
+    expect(findTruthy(arr, { key: (e) => e.v, reverse: true, from: 1, to: 1 })).toEqual({
+      v: 2,
+    })
+    expect(findTruthy(arr, { key: (e) => e.v, reverse: true, from: 1, to: 2 })).toBeUndefined()
+  })
+
+  it("reverse=true with custom from/to and key as string", () => {
+    const arr = [{ x: 0 }, { x: 2 }, { x: 0 }]
+    expect(findTruthy(arr, { key: "x", reverse: true, from: 1, to: 1 })).toEqual({ x: 2 })
+    expect(findTruthy(arr, { key: "x", reverse: true, from: 1, to: 2 })).toBeUndefined()
+  })
+
+  it("reverse=true with custom from/to and key as number", () => {
+    const arr = [[0], [2], [0]]
+    expect(findTruthy(arr, { key: 0, reverse: true, from: 1, to: 1 })).toEqual([2])
+    expect(findTruthy(arr, { key: 0, reverse: true, from: 1, to: 2 })).toBeUndefined()
+  })
 })

package/src/object.js

@@ -89,3 +89,37 @@ export function deepMerge(target, ...sources) {
   }
   return target
 }
+
+/**
+ * Deeply compares two values to determine if they are equal.
+ * Objects and arrays are compared recursively by their properties and elements.
+ * Primitives are compared with strict equality.
+ * Caveats:
+ *  Does not check class: [1] is considered equal to {0: 1}.
+ *  Any Symbol keys in the arguments are ignored (Object.keys only returns string keys).
+ * @param {any} a The first value to compare.
+ * @param {any} b The second value to compare.
+ * @returns {boolean} True if the values are deeply equal, false otherwise.
+ */
+export function deepEqual(a, b) {
+  if (a === b) {
+    return true
+  }
+  if (typeof a !== "object" || typeof b !== "object" || !a || !b) {
+    return false
+  }
+  const keysA = Object.keys(a)
+  const keysB = Object.keys(b)
+  if (keysA.length !== keysB.length) {
+    return false
+  }
+  for (const key of keysA) {
+    if (!Object.hasOwn(b, key)) {
+      return false
+    }
+    if (!deepEqual(a[key], b[key])) {
+      return false
+    }
+  }
+  return true
+}

package/src/object.test.js

@@ -1,6 +1,13 @@
 /* eslint-disable no-restricted-syntax */
 import { jest } from "@jest/globals"
-import { deepMerge, deleteUndefinedValues, like, mutateValues, via } from "./object.js"
+import {
+  deepEqual,
+  deepMerge,
+  deleteUndefinedValues,
+  like,
+  mutateValues,
+  via,
+} from "./object.js"
 
 describe("mutateValues", () => {
   it("mutates values in the object using the callback", () => {
@@ -257,3 +264,106 @@ describe("deepMerge", () => {
     expect(result).toBe(target)
   })
 })
+
+describe("deepEqual", () => {
+  it("returns true for strictly equal primitives", () => {
+    expect(deepEqual(1, 1)).toBe(true)
+    expect(deepEqual("foo", "foo")).toBe(true)
+    expect(deepEqual(true, true)).toBe(true)
+    expect(deepEqual(null, null)).toBe(true)
+    expect(deepEqual(undefined, undefined)).toBe(true)
+  })
+
+  it("returns false for different primitives", () => {
+    expect(deepEqual(1, 2)).toBe(false)
+    expect(deepEqual("foo", "bar")).toBe(false)
+    expect(deepEqual(true, false)).toBe(false)
+    expect(deepEqual(null, undefined)).toBe(false)
+  })
+
+  it("returns true for deeply equal objects", () => {
+    expect(deepEqual({ a: 1, b: 2 }, { a: 1, b: 2 })).toBe(true)
+    expect(deepEqual({ a: { b: 2 } }, { a: { b: 2 } })).toBe(true)
+    expect(deepEqual({}, {})).toBe(true)
+  })
+
+  it("returns false for objects with different keys or values", () => {
+    expect(deepEqual({ a: 1 }, { a: 2 })).toBe(false)
+    expect(deepEqual({ a: 1 }, { b: 1 })).toBe(false)
+    expect(deepEqual({ a: 1 }, {})).toBe(false)
+    expect(deepEqual({}, { a: 1 })).toBe(false)
+  })
+
+  it("returns true for deeply equal arrays", () => {
+    expect(deepEqual([1, 2, 3], [1, 2, 3])).toBe(true)
+    expect(deepEqual([], [])).toBe(true)
+    expect(deepEqual([[1], [2]], [[1], [2]])).toBe(true)
+  })
+
+  it("returns false for arrays with different elements or lengths", () => {
+    expect(deepEqual([1, 2], [1, 2, 3])).toBe(false)
+    expect(deepEqual([1, 2, 3], [1, 2])).toBe(false)
+    expect(deepEqual([1, 2, 3], [3, 2, 1])).toBe(false)
+  })
+
+  it("returns true if one is array and one is object", () => {
+    expect(deepEqual([1, 2], { 0: 1, 1: 2 })).toBe(true)
+    expect(deepEqual({ 0: 1, 1: 2 }, [1, 2])).toBe(true)
+  })
+
+  it("returns true for objects with same keys in different order", () => {
+    expect(deepEqual({ a: 1, b: 2 }, { b: 2, a: 1 })).toBe(true)
+  })
+
+  it("returns true for nested objects and arrays", () => {
+    const a = { foo: [1, { bar: 2 }], baz: { qux: [3] } }
+    const b = { foo: [1, { bar: 2 }], baz: { qux: [3] } }
+    expect(deepEqual(a, b)).toBe(true)
+  })
+
+  it("returns false for nested difference", () => {
+    const a = { foo: [1, { bar: 2 }], baz: { qux: [3] } }
+    const b = { foo: [1, { bar: 3 }], baz: { qux: [3] } }
+    expect(deepEqual(a, b)).toBe(false)
+  })
+
+  it("returns false if keys differ in nested objects", () => {
+    expect(deepEqual({ a: { b: 1 } }, { a: { c: 1 } })).toBe(false)
+  })
+
+  it("returns false if one is null or undefined and the other is object", () => {
+    expect(deepEqual(null, {})).toBe(false)
+    expect(deepEqual({}, null)).toBe(false)
+    expect(deepEqual(undefined, {})).toBe(false)
+    expect(deepEqual({}, undefined)).toBe(false)
+  })
+
+  it("returns true for self-references (same object)", () => {
+    const obj = { a: 1 }
+    expect(deepEqual(obj, obj)).toBe(true)
+    const arr = [1, 2]
+    expect(deepEqual(arr, arr)).toBe(true)
+  })
+
+  it("returns false for objects with different number of keys", () => {
+    expect(deepEqual({ a: 1, b: 2 }, { a: 1 })).toBe(false)
+    expect(deepEqual({ a: 1 }, { a: 1, b: 2 })).toBe(false)
+  })
+
+  it("returns true if object keys match but values are objects of different types", () => {
+    expect(deepEqual({ a: [1, 2] }, { a: { 0: 1, 1: 2 } })).toBe(true)
+  })
+
+  it("returns false for objects with missing keys", () => {
+    expect(deepEqual({ a: 1, b: 2 }, { a: 1 })).toBe(false)
+  })
+
+  it("returns true for objects with undefined values if both have them", () => {
+    expect(deepEqual({ a: undefined }, { a: undefined })).toBe(true)
+  })
+
+  it("returns false if one object has undefined key and the other doesn't", () => {
+    expect(deepEqual({ a: undefined }, {})).toBe(false)
+    expect(deepEqual({}, { a: undefined })).toBe(false)
+  })
+})