heap-js - npm Package Compare versions

Comparing version 2.3.0 to 2.5.0

dist/types/Heap.d.ts

@@ -14,14 +14,22 @@ export * from './HeapAsync';
     /**
-     * Alias of add
+     * Alias of {@link add}
+     * @see add
      */
     offer: (element: T) => boolean;
     /**
-     * Alias of peek
+     * Alias of {@link peek}
+     * @see peek
      */
     element: () => T | undefined;
     /**
-     * Alias of pop
+     * Alias of {@link pop}
+     * @see pop
      */
     poll: () => T | undefined;
     /**
+     * Alias of {@link clear}
+     * @see clear
+     */
+    removeAll: () => void;
+    /**
      * Heap instance constructor.
@@ -160,4 +168,4 @@ * @param  {Function} compare Optional comparison function, defaults to Heap.minComparator<number>
     /**
-     * Adds an element to the heap. Aliases: `offer`.
-     * Same as: push(element)
+     * Adds an element to the heap. Aliases: {@link offer}.
+     * Same as: {@link push}(element).
      * @param {any} element Element to be added
@@ -169,3 +177,3 @@ * @return {Boolean} true
      * Adds an array of elements to the heap.
-     * Similar as: push(element, element, ...).
+     * Similar as: {@link push}(element, element, ...).
      * @param {Array} elements Elements to be added
@@ -204,8 +212,8 @@ * @return {Boolean} true
      * @param  {any}      o   Element to be found
-     * @param  {Function} fn  Optional comparison function, receives (element, needle)
+     * @param  {Function} callbackFn  Optional comparison function, receives (element, needle)
      * @return {Boolean}
      */
-    contains(o: T, fn?: IsEqual<T>): boolean;
+    contains(o: T, callbackFn?: IsEqual<T>): boolean;
     /**
-     * Initialise a heap, sorting nodes
+     * Initialize a heap, sorting nodes
      * @param  {Array} array Optional initial state array
@@ -220,8 +228,27 @@ */
     /**
-     * Get the leafs of the tree (no children nodes)
+     * Get the index of the first occurrence of the element in the heap (using the comparator).
+     * @param  {any}      element    Element to be found
+     * @param  {Function} callbackFn Optional comparison function, receives (element, needle)
+     * @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).
+     * @param  {any}      element    Element to be found
+     * @param  {Function} callbackFn Optional comparison function, receives (element, needle)
+     * @return {Array}               Array of indexes or empty array if not found
+     */
+    indexOfEvery(element: T, callbackFn?: IsEqual<T>): number[];
+    /**
+     * Get the leafs of the tree (no children nodes).
+     * See also: {@link getChildrenOf} and {@link bottom}.
+     * @return {Array}
+     * @see getChildrenOf
+     * @see bottom
+     */
     leafs(): Array<T>;
     /**
-     * Length of the heap.
+     * Length of the heap. Aliases: {@link size}.
      * @return {Number}
+     * @see size
      */
@@ -231,18 +258,31 @@ get length(): number;
      * Get length limit of the heap.
+     * Use {@link setLimit} or {@link limit} to set the limit.
      * @return {Number}
+     * @see setLimit
      */
     get limit(): number;
     /**
-     * Set length limit of the heap.
-     * @return {Number}
+     * Set length limit of the heap. Same as using {@link setLimit}.
+     * @description If the heap is longer than the limit, the needed amount of leafs are removed.
+     * @param {Number} _l Limit, defaults to 0 (no limit). Negative, Infinity, or NaN values set the limit to 0.
+     * @see setLimit
      */
     set limit(_l: number);
     /**
-     * Top node. Aliases: `element`.
-     * Same as: `top(1)[0]`
+     * Set length limit of the heap.
+     * Same as assigning to {@link limit} but returns NaN if the value was invalid.
+     * @param {Number} _l Limit. Negative, Infinity, or NaN values set the limit to 0.
+     * @return {Number} The limit or NaN if the value was negative, or NaN.
+     * @see limit
+     */
+    setLimit(_l: number): number;
+    /**
+     * Top node. Aliases: {@link element}.
+     * Same as: {@link top}(1)[0].
      * @return {any} Top node
+     * @see top
      */
     peek(): T | undefined;
     /**
-     * Extract the top node (root). Aliases: `poll`.
+     * Extract the top node (root). Aliases: {@link poll}.
      * @return {any} Extracted top node, undefined if empty
@@ -253,2 +293,3 @@ */
      * Pushes element(s) to the heap.
+     * See also: {@link add} and {@link addAll}.
      * @param  {...any} elements Elements to insert
@@ -265,8 +306,8 @@ * @return {Boolean} True if elements are present
     /**
-     * Remove an element from the heap.
+     * Remove the first occurrence of an element from the heap.
      * @param  {any}   o      Element to be found
-     * @param  {Function} fn  Optional function to compare
+     * @param  {Function} callbackFn  Optional equality function, receives (element, needle)
      * @return {Boolean}      True if the heap was modified
      */
-    remove(o?: T, fn?: IsEqual<T>): boolean;
+    remove(o?: T, callbackFn?: IsEqual<T>): boolean;
     /**
@@ -273,0 +314,0 @@ * Pop the current peek value, and add the new item.

package.json

 {
   "name": "heap-js",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "description": "Efficient Binary heap (priority queue, binary tree) data structure for JavaScript / TypeScript. Includes JavaScript methods, Python's heapq module methods, and Java's PriorityQueue methods.",
@@ -72,30 +72,30 @@ "keywords": [
   "devDependencies": {
-    "@rollup/plugin-commonjs": "^24.1.0",
-    "@rollup/plugin-node-resolve": "^15.0.2",
+    "@rollup/plugin-commonjs": "^25.0.4",
+    "@rollup/plugin-node-resolve": "^15.2.1",
     "@types/benchmark": "^2.1.2",
-    "@types/jest": "^29.5.0",
-    "@types/node": "^18.15.11",
-    "@typescript-eslint/eslint-plugin": "5.58.0",
-    "@typescript-eslint/parser": "^5.58.0",
+    "@types/jest": "^29.5.3",
+    "@types/node": "^20.5.2",
+    "@typescript-eslint/eslint-plugin": "6.4.1",
+    "@typescript-eslint/parser": "^6.4.1",
     "benchmark": "^2.1.4",
     "coveralls": "^3.1.1",
     "cross-env": "^7.0.3",
-    "eslint": "8.38.0",
-    "eslint-config-prettier": "^8.8.0",
-    "eslint-plugin-prettier": "^4.2.1",
+    "eslint": "8.47.0",
+    "eslint-config-prettier": "^9.0.0",
+    "eslint-plugin-prettier": "^5.0.0",
     "husky": "^8.0.3",
-    "jest": "^29.5.0",
-    "lint-staged": "^13.2.1",
+    "jest": "^29.6.3",
+    "lint-staged": "^14.0.1",
     "lodash.camelcase": "^4.3.0",
-    "prettier": "^2.8.7",
+    "prettier": "^3.0.2",
     "prettier-eslint": "^15.0.1",
-    "rimraf": "^5.0.0",
-    "rollup": "^3.20.2",
+    "rimraf": "^5.0.1",
+    "rollup": "^3.28.1",
     "rollup-plugin-sourcemaps": "^0.6.3",
-    "ts-jest": "^29.1.0",
+    "ts-jest": "^29.1.1",
     "ts-node": "^10.9.1",
-    "tsc-watch": "^6.0.0",
-    "typedoc": "^0.24.1",
-    "typescript": "^5.0.4"
+    "tsc-watch": "^6.0.4",
+    "typedoc": "^0.24.8",
+    "typescript": "^5.1.6"
   }
 }

README.md

@@ -46,5 +46,19 @@ # ![Heap.js](assets/heap-js.png) Heap.js
 
+### 2.5
+
+- Improves the `limit` property to support negative, Infinity, and NaN values. They will be set as `0` and the heap will not be limited.
+- Adds the `setLimit` method to set the limit of the heap. It returns `NaN` if the limit is negative, or NaN. This method is useful to check if the limit was set as expected.
+- Improves tests and documentation.
+
+### 2.4
+
+- Adds the `indexOf` method to find the first index of an element in the heap.
+- Adds the `indexOfEvery` method to find all indexes of an element in the heap.
+- Changes the `remove` method to use the `indexOf` method.
+- Changes the `contains` method to use the `indexOf` method.
+- Improves documentation.
+
 ### 2.3
 
-- Adds the `HeapAsync` class, with async methods and supporting async comparators. It is a drop-in replacement for `Heap` class with Promises.
+- Adds the `HeapAsync` class, with async methods and supporting async comparators. It is a drop-in replacement for the `Heap` class with Promises.
 
@@ -61,4 +75,4 @@ ### 2.2
 
-- Adds `Heap.nlargest` as `heapq`.
-- Adds `Heap.nsmallest` as `heapq`.
+- Adds `Heap.nlargest` as in `heapq`.
+- Adds `Heap.nsmallest` as in `heapq`.
 - Sanitizes `top` / `bottom` input to force an integer.
@@ -69,3 +83,3 @@ - Linted with Eslint.
 
-The main breaking change is that now _`top(N)` does NOT sort the output_. It should not be part of the spec for a priority queue, the output should be the top N elements. It will be _partially ordered_ with the peek at index `0` by definition, that is all.
+The main breaking change is that now _`top(N)` does NOT sort the output_, because sorting should not be part of the spec for a priority queue. The output is the top N elements, and they will be _partially ordered_ with the peek at index `0` by definition.
 
@@ -271,2 +285,4 @@ - `top(N)` is unordered, only the first element is guaranteed to be the top priority element.
 - `bottom(number?)` least valuable elements from the heap.
+- `indexOf(element, fn?)` returns the internal index of the first occurrence of the element in the heap.
+- `indexOfEvery(element, fn?)` returns an array with the internal indexes of all occurrences of the element in the heap.
 
@@ -273,0 +289,0 @@ ## Implements Java's `PriorityQueue` interface

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

224577

increased by5.37%

Lines of code

5443

increased by4.39%

Number of lines in readme file

359

increased by4.66%

No dependency changes