@tim-code/my-util 0.5.7 → 0.5.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tim-code/my-util",
-  "version": "0.5.7",
+  "version": "0.5.9",
   "description": "",
   "type": "module",
   "author": "Tim Sprowl",
@@ -29,7 +29,7 @@
   },
   "devDependencies": {
     "@jest/globals": "^29.7.0",
-    "@tim-code/eslint-config": "^1.3.3",
+    "@tim-code/eslint-config": "^1.4.0",
     "jest": "^29.7.0"
   },
   "jest": {

package/src/array.js

@@ -186,17 +186,16 @@ export function multilevel(...comparators) {
   }
 }
 
-function siftDown(heap, i, compare) {
-  const n = heap.length
+function siftDown(heap, i, compare, 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) {
+    if (left < length && compare(heap[left], heap[largest]) > 0) {
       largest = left
     }
-    if (right < n && compare(heap[right], heap[largest]) > 0) {
+    if (right < length && compare(heap[right], heap[largest]) > 0) {
       largest = right
     }
     if (largest === i) {
@@ -209,11 +208,11 @@ function siftDown(heap, i, compare) {
   }
 }
 
-function maxHeapify(heap, compare) {
+function maxHeapify(heap, compare, length) {
   // (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)
+  for (let i = (length >>> 1) - 1; i >= 0; i--) {
+    siftDown(heap, i, compare, length)
   }
 }
 
@@ -221,29 +220,53 @@ 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; must be a nonnegative integer
+ * @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.
+ * @param {boolean=} $1.mutate If true, will mutate the original array rather than copy it.
  * @returns {Array<T>}
  */
-export function sortN(array, N, compare = ascending()) {
-  if (N <= 0) {
+export function sortN(
+  array,
+  { N, compare = ascending(), unsorted = false, force = false, mutate = false }
+) {
+  if (!(N >= 0) || N % 1 !== 0) {
+    throw new Error("N must be a nonnegative integer")
+  }
+  if (N === 0) {
+    if (mutate) {
+      array.length = 0
+      return array
+    }
     return []
   }
   if (N >= array.length) {
-    return [...array].sort(compare)
+    return (mutate ? array : [...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)
+    const sorted = (mutate ? array : [...array]).sort(compare)
+    sorted.length = N
+    return sorted
   }
-  const heap = array.slice(0, N)
-  maxHeapify(heap, compare)
+  const heap = mutate ? array : array.slice(0, N)
+  maxHeapify(heap, compare, N)
   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)
+      siftDown(heap, 0, compare, N)
     }
   }
+  if (mutate) {
+    heap.length = N
+  }
+  if (unsorted) {
+    return heap
+  }
   return heap.sort(compare)
 }

package/src/array.test.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-restricted-syntax */
 import { describe, expect, it, jest } from "@jest/globals"
 
 const { chunk, unique, duplicates, ascending, descending, multilevel, sortN } = await import(
@@ -514,38 +513,121 @@ 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 })).toThrow(
+      /N must be a nonnegative integer/u
+    )
+    expect(() => sortN([1, 2, 3], { N: 1.5, force: true })).toThrow(
+      /N must be a nonnegative integer/u
+    )
   })
 
   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])
+  it("returns the first N smallest elements (default ascending comparator, heap path)", () => {
+    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", () => {
+  it("does not mutate the original array when N < array.length (heap path)", () => {
     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 N elements in heap order when unsorted=true (heap path)", () => {
+    expect(sortN([10, 1, 7, 3, 5], { N: 3, force: true, unsorted: true })).toEqual([5, 1, 3])
+  })
+
+  it("uses the 'normal' sort+truncate path when force=false and does not mutate original", () => {
+    const arr = [4, 2, 5, 1, 3] // small array and N/len >= 0.1 -> normal path
+    const out = sortN(arr, { N: 2 })
+    expect(out).toEqual([1, 2])
+    expect(arr).toEqual([4, 2, 5, 1, 3])
+    expect(out).not.toBe(arr)
+  })
+})
+
+describe("sortN mutate", () => {
+  it("returns empty array when N <= 0", () => {
+    const a = [1, 2, 3]
+    const result = sortN(a, { N: 0, force: true, mutate: true })
+    expect(a).toEqual([])
+    expect(result).toBe(a)
+    const b = [1, 2, 3]
+    expect(() => sortN(b, { N: -5, force: true, mutate: true })).toThrow(
+      /N must be a nonnegative integer/u
+    )
+    expect(() => sortN(b, { N: -1.5, force: true, mutate: true })).toThrow(
+      /N must be a nonnegative integer/u
+    )
+  })
+
+  it("returns the entire array sorted when N >= array.length", () => {
+    const array = [3, 1, 2]
+    const result = sortN(array, { N: 10, force: true, mutate: true })
+    expect(array).toEqual([1, 2, 3])
+    expect(result).toBe(array)
+  })
+
+  it("returns the first N smallest elements and mutates in-place (heap path)", () => {
+    const arr = [5, 1, 3, 2, 4]
+    const out = sortN(arr, { N: 3, force: true, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr).toEqual([1, 2, 3])
+  })
+
+  it("respects a descending comparator and mutates in-place (heap path)", () => {
+    const arr = [5, 1, 3, 2, 4]
+    const out = sortN(arr, { N: 2, compare: descending(), force: true, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr).toEqual([5, 4])
+  })
+
+  it("works with key-based comparator, mutating and truncating in-place (heap path)", () => {
+    const arr = [{ v: 3 }, {}, { v: 1 }, { v: null }, { v: 2 }, { v: undefined }]
+    const out = sortN(arr, { N: 3, compare: ascending("v"), force: true, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr.length).toBe(3)
+    expect(out.map((o) => o.v)).toEqual([1, 2, 3])
+  })
+
+  it("mutates the original array when mutate=true and N < array.length (heap path)", () => {
+    const arr = [5, 1, 3, 2, 4]
+    const out = sortN(arr, { N: 3, force: true, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr).toEqual([1, 2, 3])
+  })
+
+  it("returns the first N elements in heap order when unsorted=true (heap path, mutate=true)", () => {
+    const arr = [10, 1, 7, 3, 5]
+    const out = sortN(arr, { N: 3, force: true, unsorted: true, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr).toEqual([5, 1, 3])
+  })
+
+  it("uses the 'normal' sort+truncate path when force=false and mutates in-place", () => {
+    const arr = [4, 2, 5, 1, 3] // small array and N/len >= 0.1 -> normal path
+    const out = sortN(arr, { N: 2, mutate: true })
+    expect(out).toBe(arr)
+    expect(arr).toEqual([1, 2])
+  })
 })

package/src/find.test.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-restricted-syntax */
 import { describe, expect, it } from "@jest/globals"
 
 const {

package/src/math.test.js

@@ -248,7 +248,6 @@ describe("formatPlus", () => {
 
   it("returns undefined for non-number, non-string input", () => {
     expect(formatPlus(undefined)).toBeUndefined()
-    // eslint-disable-next-line no-restricted-syntax
     expect(formatPlus(null)).toBeUndefined()
     expect(formatPlus({})).toBeUndefined()
     expect(formatPlus([])).toBeUndefined()
@@ -323,7 +322,6 @@ describe("isNumber", () => {
   it("returns false for non-number types", () => {
     expect(isNumber("123")).toBe(false)
     expect(isNumber(undefined)).toBe(false)
-    // eslint-disable-next-line no-restricted-syntax
     expect(isNumber(null)).toBe(false)
     expect(isNumber({})).toBe(false)
     expect(isNumber([])).toBe(false)

package/src/object.test.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-restricted-syntax */
 import { jest } from "@jest/globals"
 import {
   deepCopy,

package/src/promise.test.js

@@ -1,4 +1,3 @@
-/* eslint-disable no-restricted-syntax */
 /* eslint-disable prefer-promise-reject-errors */
 import { jest } from "@jest/globals"