@tim-code/my-util 0.5.6 → 0.5.8

package/package.json

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

package/src/array.js

@@ -185,3 +185,73 @@ 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 {Object} $1
+ * @param {number} $1.N Number of elements to return
+ * @param {Function=} $1.compare Sort function. Default is ascending sort.
+ * @param {boolean=} $1.unsorted If true, returns the final result in heap order, not sorted order, as an optimization.
+ *  Default is false.
+ * @param {boolean=} $1.force If true, will force heap-based method for small N instead of more efficient "normal" way.
+ *  Default is false.
+ * @returns {Array<T>}
+ */
+export function sortN(array, { N, compare = ascending(), unsorted = false, force = false }) {
+  if (!(N > 0)) {
+    return []
+  }
+  if (N >= array.length) {
+    return [...array].sort(compare)
+  }
+  if (!force && 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)
+    }
+  }
+  if (unsorted) {
+    return heap
+  }
+  return heap.sort(compare)
+}

package/src/array.test.js

@@ -1,7 +1,7 @@
 /* eslint-disable no-restricted-syntax */
 import { describe, expect, it, jest } from "@jest/globals"
 
-const { chunk, unique, duplicates, ascending, descending, multilevel } = await import(
+const { chunk, unique, duplicates, ascending, descending, multilevel, sortN } = await import(
   "./array.js"
 )
 
@@ -511,3 +511,45 @@ describe("multilevel", () => {
     expect(cmp("a", "b")).toBe(0)
   })
 })
+
+describe("sortN", () => {
+  it("returns empty array when N <= 0", () => {
+    expect(sortN([1, 2, 3], { N: 0, force: true })).toEqual([])
+    expect(sortN([1, 2, 3], { N: -5, force: true })).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, { N: 10, force: true })
+    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], { N: 3, force: true })).toEqual([1, 2, 3])
+    expect(sortN([3, 1, 3, 2, 2], { N: 4, force: true })).toEqual([1, 2, 2, 3])
+  })
+
+  it("respects a descending comparator (returns top N largest)", () => {
+    const arr = [5, 1, 3, 2, 4]
+    expect(sortN(arr, { N: 2, compare: descending(), force: true })).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, { N: 3, compare: ascending("v"), force: true })
+    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, { N: 3, force: true })
+    expect(out).toEqual([1, 2, 3])
+    expect(arr).toEqual([5, 1, 3, 2, 4])
+  })
+
+  it("returns the first N smallest elements (default ascending comparator)", () => {
+    expect(sortN([10, 1, 7, 3, 5], { N: 3, force: true, unsorted: true })).toEqual([5, 1, 3])
+  })
+})