feat: bump version to 3.0.0 and update README with breaking changes and new features

This release introduces significant changes, including:
- `setLimit` and `_applyLimit` methods in the HeapAsync class are now async.
- Constructors for Heap and HeapAsync now accept options objects for custom comparison and equality functions.
- New `isEqual` property added to both classes.
- Enhanced eviction logic to maintain the best N elements in the heap.

Author: ignlg

README.md

@@ -43,6 +43,16 @@ heap vs array: push + top(50) of 100
 
 ## Changelog
 
+### 3.0.0
+
+The main breaking changes are that `setLimit` and `_applyLimit` methods of the HeapAsync class are now async, and that setting the `limit` property will NOT apply the limit asynchronously; use the `setLimit` method instead.
+
+- Constructor now accepts an options object, `HeapOptions` and `HeapAsyncOptions`, with the `compare` and `isEqual` options.
+- Adds the `isEqual` property to the `Heap` and `HeapAsync` classes to support custom equality functions to override the default equality function.
+- Custom comparison callbacks trigger O(n) full scan vs O(log n) average for default equality. Addressing [#669](https://github.com/ignlg/heap-js/issues/669).
+- Setting a limit makes the heap evict the worst elements to keep the best N elements. Addressing [#656](https://github.com/ignlg/heap-js/issues/656).
+- HeapAsync limit should be set with the `setLimit` method to support async limit application. Setting only the `limit` property will not apply the limit asynchronously.
+
 ### 2.7.1
 
 - Optimize loop condition in HeapAsync init method.

dist/heap-js.es5.js

@@ -1,15 +1,32 @@
 export * from './HeapAsync';
 export type Comparator<T> = (a: T, b: T) => number;
 export type IsEqual<T> = (e: T, o: T) => boolean;
+/**
+ * Heap configuration options.
+ */
+export interface HeapOptions<T> {
+    /**
+     * Comparison function for heap ordering.
+     * @default Heap.minComparator
+     */
+    compare?: Comparator<T>;
+    /**
+     * Default equality function for indexOf, contains, and remove.
+     * When provided, these methods use heap-optimized search.
+     * @default Heap.defaultIsEqual
+     */
+    isEqual?: IsEqual<T>;
+}
 export declare const toInt: (n: number) => number;
 /**
  * Heap
  * @type {Class}
  */
 export declare class Heap<T> implements Iterable<T> {
-    compare: Comparator<T>;
     heapArray: Array<T>;
     _limit: number;
+    isEqual: IsEqual<T>;
+    compare: Comparator<T>;
     /**
      * Alias of {@link add}
      * @see add
@@ -32,9 +49,9 @@ export declare class Heap<T> implements Iterable<T> {
     removeAll: () => void;
     /**
      * Heap instance constructor.
-     * @param  {Function} compare Optional comparison function, defaults to Heap.minComparator<number>
+     * @param  {Function | HeapOptions} compareOrOptions Optional comparison function or options object
      */
-    constructor(compare?: Comparator<T>);
+    constructor(compareOrOptions?: Comparator<T> | HeapOptions<T>);
     /**
      * Gets children indices for given index.
      * @param  {Number} idx     Parent index
@@ -167,7 +184,7 @@ export declare class Heap<T> implements Iterable<T> {
      * Adds an element to the heap. Aliases: {@link offer}.
      * Same as: {@link push}(element).
      * @param {any} element Element to be added
-     * @return {Boolean} true
+     * @return {Boolean} true if added, false if limit exceeded and element not good enough
      */
     add(element: T): boolean;
     /**
@@ -221,16 +238,16 @@ export declare class Heap<T> implements Iterable<T> {
      */
     isEmpty(): boolean;
     /**
-     * Get the index of the first occurrence of the element in the heap (using the comparator).
+     * Get the index of the first occurrence of the element in the heap.
      * @param  {any}      element    Element to be found
-     * @param  {Function} callbackFn Optional comparison function, receives (element, needle)
+     * @param  {Function} callbackFn Optional comparison function, receives (element, needle). Note: Custom callbacks trigger O(n) full scan vs O(log n) average for default equality.
      * @return {Number}              Index or -1 if not found
      */
     indexOf(element: T, callbackFn?: IsEqual<T>): number;
     /**
-     * Get the indexes of the every occurrence of the element in the heap (using the comparator).
+     * Get the indexes of every occurrence of the element in the heap.
      * @param  {any}      element    Element to be found
-     * @param  {Function} callbackFn Optional comparison function, receives (element, needle)
+     * @param  {Function} callbackFn Optional comparison function, receives (element, needle). Note: Custom callbacks trigger O(n) full scan vs optimized heap search for default equality.
      * @return {Array}               Array of indexes or empty array if not found
      */
     indexOfEvery(element: T, callbackFn?: IsEqual<T>): number[];
@@ -357,7 +374,7 @@ export declare class Heap<T> implements Iterable<T> {
      */
     iterator(): Iterable<T>;
     /**
-     * Limit heap size if needed
+     * Limit heap size if needed, removing worst elements to keep best N
      */
     _applyLimit(): void;
     /**
@@ -422,5 +439,11 @@ export declare class Heap<T> implements Iterable<T> {
      * @param list
      */
     _topOf(...list: Array<T>): T | undefined;
+    /**
+     * Find index of the worst element (for eviction when at limit).
+     * Worst is always among leaves (second half of array).
+     * @return {number} Index of worst element, -1 if empty
+     */
+    _worstIndex(): number;
 }
 export default Heap;

dist/heap-js.umd.js

@@ -1,13 +1,29 @@
 export type AsyncComparator<T> = (a: T, b: T) => Promise<number>;
 export type AsyncIsEqual<T> = (e: T, o: T) => Promise<boolean>;
+/**
+ * HeapAsync configuration options.
+ */
+export interface HeapAsyncOptions<T> {
+    /**
+     * Comparison function for heap ordering.
+     * @default HeapAsync.minComparator
+     */
+    compare?: AsyncComparator<T>;
+    /**
+     * Default equality function for contains and remove.
+     * @default HeapAsync.defaultIsEqual
+     */
+    isEqual?: AsyncIsEqual<T>;
+}
 /**
  * Heap
  * @type {Class}
  */
 export declare class HeapAsync<T> implements Iterable<Promise<T>> {
-    compare: AsyncComparator<T>;
     heapArray: Array<T>;
     _limit: number;
+    isEqual: AsyncIsEqual<T>;
+    compare: AsyncComparator<T>;
     /**
      * Alias of add
      */
@@ -22,9 +38,9 @@ export declare class HeapAsync<T> implements Iterable<Promise<T>> {
     poll: () => Promise<T | undefined>;
     /**
      * Heap instance constructor.
-     * @param  {Function} compare Optional comparison function, defaults to Heap.minComparator<number>
+     * @param  {Function | HeapAsyncOptions} compareOrOptions Optional comparison function or options object
      */
-    constructor(compare?: AsyncComparator<T>);
+    constructor(compareOrOptions?: AsyncComparator<T> | HeapAsyncOptions<T>);
     /**
      * Gets children indices for given index.
      * @param  {Number} idx     Parent index
@@ -157,7 +173,7 @@ export declare class HeapAsync<T> implements Iterable<Promise<T>> {
      * Adds an element to the heap. Aliases: `offer`.
      * Same as: push(element)
      * @param {any} element Element to be added
-     * @return {Boolean} true
+     * @return {Boolean} true if added, false if limit exceeded and element not good enough
      */
     add(element: T): Promise<boolean>;
     /**
@@ -225,10 +241,17 @@ export declare class HeapAsync<T> implements Iterable<Promise<T>> {
      */
     get limit(): number;
     /**
-     * Set length limit of the heap.
-     * @return {Number}
+     * Set length limit of the heap without eviction.
+     * Note: Use setLimit() for async limit application with proper eviction.
+     * @param {Number} _l Limit value
      */
     set limit(_l: number);
+    /**
+     * Set length limit of the heap with async limit application.
+     * @param {Number} _l Limit value
+     * @return {Promise<number>} The limit value
+     */
+    setLimit(_l: number): Promise<number>;
     /**
      * Top node. Aliases: `element`.
      * Same as: `top(1)[0]`
@@ -314,9 +337,9 @@ export declare class HeapAsync<T> implements Iterable<Promise<T>> {
      */
     iterator(): Iterable<Promise<T>>;
     /**
-     * Limit heap size if needed
+     * Limit heap size if needed, removing worst elements to keep best N
      */
-    _applyLimit(): void;
+    _applyLimit(): Promise<void>;
     /**
      * Return the bottom (lowest value) N elements of the heap, without corner cases, unsorted
      *
@@ -379,5 +402,11 @@ export declare class HeapAsync<T> implements Iterable<Promise<T>> {
      * @param list
      */
     _topOf(...list: Array<T>): Promise<T | undefined>;
+    /**
+     * Find index of the worst element (for eviction when at limit).
+     * Worst is always among leaves (second half of array).
+     * @return {number} Index of worst element, -1 if empty
+     */
+    _worstIndex(): Promise<number>;
 }
 export default HeapAsync;