@tim-code/my-util 0.5.7 → 0.5.8

package/package.json

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

package/src/array.js

@@ -221,18 +221,23 @@ function maxHeapify(heap, compare) {
  * Get the first N elements of the sorted array efficiently.
  * @template T
  * @param {Array<T>} array
- * @param {number} N
- * @param {Function} compare
+ * @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()) {
-  if (N <= 0) {
+export function sortN(array, { N, compare = ascending(), unsorted = false, force = false }) {
+  if (!(N > 0)) {
     return []
   }
   if (N >= array.length) {
     return [...array].sort(compare)
   }
-  if (array.length <= 100 && N / array.length >= 0.1) {
+  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)
   }
@@ -245,5 +250,8 @@ export function sortN(array, N, compare = ascending()) {
       siftDown(heap, 0, compare)
     }
   }
+  if (unsorted) {
+    return heap
+  }
   return heap.sort(compare)
 }

package/src/array.test.js

@@ -514,38 +514,42 @@ describe("multilevel", () => {
 
 describe("sortN", () => {
   it("returns empty array when N <= 0", () => {
-    expect(sortN([1, 2, 3], 0)).toEqual([])
-    expect(sortN([1, 2, 3], -5)).toEqual([])
+    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, 10)
+    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], 3)).toEqual([1, 2, 3])
-    expect(sortN([3, 1, 3, 2, 2], 4)).toEqual([1, 2, 2, 3])
+    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, 2, descending())).toEqual([5, 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, 3, ascending("v"))
+    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, 3)
+    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])
+  })
 })