@tim-code/my-util 0.5.5 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.5.5",
+  "version": "0.5.7",
   "description": "",
   "type": "module",
   "author": "Tim Sprowl",
@@ -28,8 +28,8 @@
     ]
   },
   "devDependencies": {
-    "@tim-code/eslint-config": "^1.3.3",
     "@jest/globals": "^29.7.0",
+    "@tim-code/eslint-config": "^1.3.3",
     "jest": "^29.7.0"
   },
   "jest": {
@@ -37,5 +37,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@tim-code/my-util": "^0.5.5"
   }
 }

package/src/array.js

@@ -54,6 +54,50 @@ export function unique(array, { key } = {}) {
   return result
 }
 
+/**
+ * Returns groups of duplicate elements in an array.
+ * Each group is an array of elements that share the same key or callback result.
+ * Only groups with more than one element are returned. Returns an empty array if no duplicates.
+ * @param {Array} array
+ * @param {Object} $1
+ * @param {string|number|Function=} $1.key
+ *  If a function, calls the provided function on an element to get the value for grouping.
+ *  If a string or number, uses element[key].
+ *  If omitted, compares elements directly.
+ * @returns {Array<Array>}
+ */
+export function duplicates(array, { key } = {}) {
+  const groups = new Map()
+
+  if (typeof key === "function") {
+    for (let i = 0; i < array.length; i++) {
+      const element = array[i]
+      const value = key(element, i, array)
+      if (!groups.has(value)) {
+        groups.set(value, [])
+      }
+      groups.get(value).push(element)
+    }
+  } else if (typeof key === "string" || typeof key === "number") {
+    for (const element of array) {
+      const value = element[key]
+      if (!groups.has(value)) {
+        groups.set(value, [])
+      }
+      groups.get(value).push(element)
+    }
+  } else {
+    for (const element of array) {
+      if (!groups.has(element)) {
+        groups.set(element, [])
+      }
+      groups.get(element).push(element)
+    }
+  }
+  const results = [...groups.values()].filter((group) => group.length > 1)
+  return results
+}
+
 // sorts undefined and null to the end if applicable
 function compareUndefinedNull(a, b) {
   if (b === undefined || b === null) {
@@ -141,3 +185,65 @@ export function multilevel(...comparators) {
     return 0
   }
 }
+
+function siftDown(heap, i, compare) {
+  const n = heap.length
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const left = 2 * i + 1
+    const right = left + 1
+    let largest = i
+    if (left < n && compare(heap[left], heap[largest]) > 0) {
+      largest = left
+    }
+    if (right < n && compare(heap[right], heap[largest]) > 0) {
+      largest = right
+    }
+    if (largest === i) {
+      break
+    }
+    const swap = heap[largest]
+    heap[largest] = heap[i]
+    heap[i] = swap
+    i = largest
+  }
+}
+
+function maxHeapify(heap, compare) {
+  // (heap.length >>> 1) is equivalent to Math.floor(heap.length / 2)
+  // eslint-disable-next-line no-bitwise
+  for (let i = (heap.length >>> 1) - 1; i >= 0; i--) {
+    siftDown(heap, i, compare)
+  }
+}
+
+/**
+ * Get the first N elements of the sorted array efficiently.
+ * @template T
+ * @param {Array<T>} array
+ * @param {number} N
+ * @param {Function} compare
+ * @returns {Array<T>}
+ */
+export function sortN(array, N, compare = ascending()) {
+  if (N <= 0) {
+    return []
+  }
+  if (N >= array.length) {
+    return [...array].sort(compare)
+  }
+  if (array.length <= 100 && N / array.length >= 0.1) {
+    // seems to be faster to do it the "normal" way in this case
+    return [...array].sort(compare).slice(0, N)
+  }
+  const heap = array.slice(0, N)
+  maxHeapify(heap, compare)
+  for (let i = N; i < array.length; i++) {
+    const element = array[i]
+    if (compare(element, heap[0]) < 0) {
+      heap[0] = element
+      siftDown(heap, 0, compare)
+    }
+  }
+  return heap.sort(compare)
+}

package/src/array.test.js

@@ -1,7 +1,9 @@
 /* eslint-disable no-restricted-syntax */
 import { describe, expect, it, jest } from "@jest/globals"
 
-const { chunk, unique, ascending, descending, multilevel } = await import("./array.js")
+const { chunk, unique, duplicates, ascending, descending, multilevel, sortN } = await import(
+  "./array.js"
+)
 
 describe("chunk", () => {
   it("splits array into chunks of specified size", () => {
@@ -162,6 +164,169 @@ describe("unique", () => {
   })
 })
 
+describe("duplicates", () => {
+  it("returns empty array if there are no duplicates", () => {
+    expect(duplicates([1, 2, 3])).toEqual([])
+    expect(duplicates([], {})).toEqual([])
+  })
+
+  it("returns groups of duplicate primitives", () => {
+    expect(duplicates([1, 2, 1, 3, 2, 1])).toEqual([
+      [1, 1, 1],
+      [2, 2],
+    ])
+    expect(duplicates(["a", "b", "a", "c", "b"])).toEqual([
+      ["a", "a"],
+      ["b", "b"],
+    ])
+  })
+
+  it("returns groups of duplicate objects by reference", () => {
+    const a = {}
+    const b = {}
+    expect(duplicates([a, b, a, b, a])).toEqual([
+      [a, a, a],
+      [b, b],
+    ])
+  })
+
+  it("returns groups of duplicates by key (string)", () => {
+    const arr = [
+      { id: 1, name: "a" },
+      { id: 2, name: "b" },
+      { id: 1, name: "c" },
+      { id: 3, name: "d" },
+      { id: 2, name: "e" },
+      { id: 1, name: "f" },
+    ]
+    expect(duplicates(arr, { key: "id" })).toEqual([
+      [
+        { id: 1, name: "a" },
+        { id: 1, name: "c" },
+        { id: 1, name: "f" },
+      ],
+      [
+        { id: 2, name: "b" },
+        { id: 2, name: "e" },
+      ],
+    ])
+  })
+
+  it("returns groups of duplicates by key (number)", () => {
+    const arr = [
+      { 0: "a", v: 1 },
+      { 0: "b", v: 2 },
+      { 0: "a", v: 3 },
+      { 0: "c", v: 4 },
+      { 0: "b", v: 5 },
+    ]
+    expect(duplicates(arr, { key: 0 })).toEqual([
+      [
+        { 0: "a", v: 1 },
+        { 0: "a", v: 3 },
+      ],
+      [
+        { 0: "b", v: 2 },
+        { 0: "b", v: 5 },
+      ],
+    ])
+  })
+
+  it("returns groups of duplicates by function", () => {
+    const arr = [
+      { id: 1, name: "a" },
+      { id: 2, name: "b" },
+      { id: 1, name: "c" },
+      { id: 3, name: "d" },
+      { id: 2, name: "e" },
+      { id: 1, name: "f" },
+    ]
+    expect(
+      duplicates(arr, {
+        key: (el) => el.id % 2, // group by odd/even id
+      })
+    ).toEqual([
+      [
+        { id: 1, name: "a" },
+        { id: 1, name: "c" },
+        { id: 3, name: "d" },
+        { id: 1, name: "f" },
+      ],
+      [
+        { id: 2, name: "b" },
+        { id: 2, name: "e" },
+      ],
+    ])
+  })
+
+  it("returns groups of duplicates by function using index and array", () => {
+    const arr = ["a", "b", "c", "a", "c"]
+    expect(
+      duplicates(arr, {
+        key: (el, i, array) => array.indexOf(el), // group by first occurrence index
+      })
+    ).toEqual([
+      ["a", "a"],
+      ["c", "c"],
+    ])
+  })
+
+  it("returns groups of duplicates by key when some elements lack the key", () => {
+    const arr = [{ id: 1 }, {}, { id: 1 }, { id: 2 }, {}, { id: 2 }]
+    expect(duplicates(arr, { key: "id" })).toEqual([
+      [{ id: 1 }, { id: 1 }],
+      [{}, {}],
+      [{ id: 2 }, { id: 2 }],
+    ])
+  })
+
+  it("returns groups of duplicates by function when function returns undefined/null", () => {
+    const arr = [{ id: 1 }, {}, { id: 2 }, { id: null }, {}, { id: null }]
+    expect(
+      duplicates(arr, {
+        key: (el) => el.id,
+      })
+    ).toEqual([
+      [{}, {}],
+      [{ id: null }, { id: null }],
+    ])
+  })
+
+  it("returns groups of duplicates by key when key value is undefined/null", () => {
+    const arr = [
+      { id: 1 },
+      { id: undefined },
+      { id: 2 },
+      { id: null },
+      { id: undefined },
+      { id: null },
+    ]
+    expect(duplicates(arr, { key: "id" })).toEqual([
+      [{ id: undefined }, { id: undefined }],
+      [{ id: null }, { id: null }],
+    ])
+  })
+
+  it("returns empty array if all elements are unique by key or function", () => {
+    const arr = [{ id: 1 }, { id: 2 }, { id: 3 }]
+    expect(duplicates(arr, { key: "id" })).toEqual([])
+    expect(
+      duplicates(arr, {
+        key: (el) => el.id,
+      })
+    ).toEqual([])
+  })
+
+  it("returns empty array for empty input with key or function", () => {
+    expect(duplicates([], { key: "id" })).toEqual([])
+    expect(
+      duplicates([], {
+        key: (el) => el,
+      })
+    ).toEqual([])
+  })
+})
+
 describe("ascending", () => {
   it("sorts primitives ascending, undefined/null at end", () => {
     const arr = [undefined, null, 3, 1, 2]
@@ -346,3 +511,41 @@ describe("multilevel", () => {
     expect(cmp("a", "b")).toBe(0)
   })
 })
+
+describe("sortN", () => {
+  it("returns empty array when N <= 0", () => {
+    expect(sortN([1, 2, 3], 0)).toEqual([])
+    expect(sortN([1, 2, 3], -5)).toEqual([])
+  })
+
+  it("returns the entire array sorted when N >= array.length and does not mutate original", () => {
+    const arr = [3, 1, 2]
+    const result = sortN(arr, 10)
+    expect(result).toEqual([1, 2, 3])
+    expect(arr).toEqual([3, 1, 2])
+    expect(result).not.toBe(arr)
+  })
+
+  it("returns the first N smallest elements (default ascending comparator)", () => {
+    expect(sortN([5, 1, 3, 2, 4], 3)).toEqual([1, 2, 3])
+    expect(sortN([3, 1, 3, 2, 2], 4)).toEqual([1, 2, 2, 3])
+  })
+
+  it("respects a descending comparator (returns top N largest)", () => {
+    const arr = [5, 1, 3, 2, 4]
+    expect(sortN(arr, 2, descending())).toEqual([5, 4])
+  })
+
+  it("works with key-based comparator and defers undefined/null values to the end", () => {
+    const arr = [{ v: 3 }, {}, { v: 1 }, { v: null }, { v: 2 }, { v: undefined }]
+    const out = sortN(arr, 3, ascending("v"))
+    expect(out.map((o) => o.v)).toEqual([1, 2, 3])
+  })
+
+  it("does not mutate the original array when N < array.length", () => {
+    const arr = [5, 1, 3, 2, 4]
+    const out = sortN(arr, 3)
+    expect(out).toEqual([1, 2, 3])
+    expect(arr).toEqual([5, 1, 3, 2, 4])
+  })
+})