heap-typed 1.19.3

package/dist/heap.d.ts

@@ -0,0 +1,88 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import { PriorityQueue } from 'data-structure-typed';
+import type { HeapOptions } from 'data-structure-typed';
+export declare class HeapItem<T = number> {
+    /**
+     * The constructor function initializes an instance of a class with a priority and a value.
+     * @param {number} priority - The `priority` parameter is a number that represents the priority of the value. It is
+     * optional and has a default value of `NaN`.
+     * @param {T | null} [val=null] - The `val` parameter is of type `T | null`, which means it can accept a value of type
+     * `T` or `null`.
+     */
+    constructor(priority?: number, val?: T | null);
+    private _priority;
+    get priority(): number;
+    set priority(value: number);
+    private _val;
+    get val(): T | null;
+    set val(value: T | null);
+}
+export declare abstract class Heap<T = number> {
+    /**
+     * The function is a constructor for a class that initializes a priority callback function based on the
+     * options provided.
+     * @param [options] - An optional object that contains configuration options for the Heap.
+     */
+    protected constructor(options?: HeapOptions<T>);
+    protected abstract _pq: PriorityQueue<HeapItem<T>>;
+    get pq(): PriorityQueue<HeapItem<T>>;
+    protected _priorityExtractor: (val: T) => number;
+    get priorityExtractor(): (val: T) => number;
+    /**
+     * The function returns the size of a priority queue.
+     * @returns The size of the priority queue.
+     */
+    get size(): number;
+    /**
+     * The function checks if a priority queue is empty.
+     * @returns {boolean} A boolean value indicating whether the size of the priority queue is less than 1.
+     */
+    isEmpty(): boolean;
+    /**
+     * The `peek` function returns the top item in the priority queue without removing it.
+     * @returns The `peek()` method is returning either a `HeapItem<T>` object or `null`.Returns an val with the highest priority in the queue
+     */
+    peek(): HeapItem<T> | null;
+    /**
+     * The `peekLast` function returns the last item in the heap.
+     * @returns The method `peekLast()` returns either a `HeapItem<T>` object or `null`.Returns an val with the lowest priority in the queue
+     */
+    peekLast(): HeapItem<T> | null;
+    /**
+     * The `add` function adds an val to a priority queue with an optional priority value.
+     * @param {T} val - The `val` parameter represents the value that you want to add to the heap. It can be of any
+     * type.
+     * @param {number} [priority] - The `priority` parameter is an optional number that represents the priority of the
+     * val being added to the heap. If the `val` parameter is a number, then the `priority` parameter is set to
+     * the value of `val`. If the `val` parameter is not a number, then the
+     * @returns The `add` method returns the instance of the `Heap` class.
+     * @throws {Error} if priority is not a valid number
+     */
+    add(val: T, priority?: number): Heap<T>;
+    /**
+     * The `poll` function returns the top item from a priority queue or null if the queue is empty.Removes and returns an val with the highest priority in the queue
+     * @returns either a HeapItem<T> object or null.
+     */
+    poll(): HeapItem<T> | null;
+    /**
+     * The function checks if a given node or value exists in the priority queue.
+     * @param {T | HeapItem<T>} node - The parameter `node` can be of type `T` or `HeapItem<T>`.
+     * @returns a boolean value.
+     */
+    has(node: T | HeapItem<T>): boolean;
+    /**
+     * The `toArray` function returns an array of `HeapItem<T>` objects.
+     * @returns An array of HeapItem<T> objects.Returns a sorted list of vals
+     */
+    toArray(): HeapItem<T>[];
+    /**
+     * The clear function clears the priority queue.
+     */
+    clear(): void;
+}

package/dist/heap.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Heap = exports.HeapItem = void 0;
+var HeapItem = /** @class */ (function () {
+    /**
+     * The constructor function initializes an instance of a class with a priority and a value.
+     * @param {number} priority - The `priority` parameter is a number that represents the priority of the value. It is
+     * optional and has a default value of `NaN`.
+     * @param {T | null} [val=null] - The `val` parameter is of type `T | null`, which means it can accept a value of type
+     * `T` or `null`.
+     */
+    function HeapItem(priority, val) {
+        if (priority === void 0) { priority = NaN; }
+        if (val === void 0) { val = null; }
+        this._val = val;
+        this._priority = priority;
+    }
+    Object.defineProperty(HeapItem.prototype, "priority", {
+        get: function () {
+            return this._priority;
+        },
+        set: function (value) {
+            this._priority = value;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(HeapItem.prototype, "val", {
+        get: function () {
+            return this._val;
+        },
+        set: function (value) {
+            this._val = value;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    return HeapItem;
+}());
+exports.HeapItem = HeapItem;
+var Heap = /** @class */ (function () {
+    /**
+     * The function is a constructor for a class that initializes a priority callback function based on the
+     * options provided.
+     * @param [options] - An optional object that contains configuration options for the Heap.
+     */
+    function Heap(options) {
+        if (options) {
+            var priorityExtractor = options.priorityExtractor;
+            if (priorityExtractor !== undefined && typeof priorityExtractor !== 'function') {
+                throw new Error('.constructor expects a valid priority function');
+            }
+            this._priorityExtractor = priorityExtractor || (function (el) { return +el; });
+        }
+        else {
+            this._priorityExtractor = function (el) { return +el; };
+        }
+    }
+    Object.defineProperty(Heap.prototype, "pq", {
+        get: function () {
+            return this._pq;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(Heap.prototype, "priorityExtractor", {
+        get: function () {
+            return this._priorityExtractor;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    Object.defineProperty(Heap.prototype, "size", {
+        /**
+         * The function returns the size of a priority queue.
+         * @returns The size of the priority queue.
+         */
+        get: function () {
+            return this._pq.size;
+        },
+        enumerable: false,
+        configurable: true
+    });
+    /**
+     * The function checks if a priority queue is empty.
+     * @returns {boolean} A boolean value indicating whether the size of the priority queue is less than 1.
+     */
+    Heap.prototype.isEmpty = function () {
+        return this._pq.size < 1;
+    };
+    /**
+     * The `peek` function returns the top item in the priority queue without removing it.
+     * @returns The `peek()` method is returning either a `HeapItem<T>` object or `null`.Returns an val with the highest priority in the queue
+     */
+    Heap.prototype.peek = function () {
+        return this._pq.peek();
+    };
+    /**
+     * The `peekLast` function returns the last item in the heap.
+     * @returns The method `peekLast()` returns either a `HeapItem<T>` object or `null`.Returns an val with the lowest priority in the queue
+     */
+    Heap.prototype.peekLast = function () {
+        return this._pq.leaf();
+    };
+    /**
+     * The `add` function adds an val to a priority queue with an optional priority value.
+     * @param {T} val - The `val` parameter represents the value that you want to add to the heap. It can be of any
+     * type.
+     * @param {number} [priority] - The `priority` parameter is an optional number that represents the priority of the
+     * val being added to the heap. If the `val` parameter is a number, then the `priority` parameter is set to
+     * the value of `val`. If the `val` parameter is not a number, then the
+     * @returns The `add` method returns the instance of the `Heap` class.
+     * @throws {Error} if priority is not a valid number
+     */
+    Heap.prototype.add = function (val, priority) {
+        if (typeof val === 'number') {
+            priority = val;
+        }
+        else {
+            if (priority === undefined) {
+                throw new Error('.add expects a numeric priority');
+            }
+        }
+        if (priority && Number.isNaN(+priority)) {
+            throw new Error('.add expects a numeric priority');
+        }
+        if (Number.isNaN(+priority) && Number.isNaN(this._priorityExtractor(val))) {
+            throw new Error('.add expects a numeric priority '
+                + 'or a constructor callback that returns a number');
+        }
+        var _priority = !Number.isNaN(+priority) ? priority : this._priorityExtractor(val);
+        this._pq.add(new HeapItem(_priority, val));
+        return this;
+    };
+    /**
+     * The `poll` function returns the top item from a priority queue or null if the queue is empty.Removes and returns an val with the highest priority in the queue
+     * @returns either a HeapItem<T> object or null.
+     */
+    Heap.prototype.poll = function () {
+        var top = this._pq.poll();
+        if (!top) {
+            return null;
+        }
+        return top;
+    };
+    /**
+     * The function checks if a given node or value exists in the priority queue.
+     * @param {T | HeapItem<T>} node - The parameter `node` can be of type `T` or `HeapItem<T>`.
+     * @returns a boolean value.
+     */
+    Heap.prototype.has = function (node) {
+        if (node instanceof HeapItem) {
+            return this.pq.getNodes().includes(node);
+        }
+        else {
+            return this.pq.getNodes().findIndex(function (item) {
+                return item.val === node;
+            }) !== -1;
+        }
+    };
+    /**
+     * The `toArray` function returns an array of `HeapItem<T>` objects.
+     * @returns An array of HeapItem<T> objects.Returns a sorted list of vals
+     */
+    Heap.prototype.toArray = function () {
+        return this._pq.toArray();
+    };
+    /**
+     * The clear function clears the priority queue.
+     */
+    Heap.prototype.clear = function () {
+        this._pq.clear();
+    };
+    return Heap;
+}());
+exports.Heap = Heap;

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './heap';
+export * from './max-heap';
+export * from './min-heap';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./heap"), exports);
+__exportStar(require("./max-heap"), exports);
+__exportStar(require("./min-heap"), exports);

package/dist/max-heap.d.ts

@@ -0,0 +1,23 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import { Heap, HeapItem } from 'data-structure-typed';
+import { PriorityQueue } from 'data-structure-typed';
+import type { HeapOptions } from 'data-structure-typed';
+/**
+ * @class MaxHeap
+ * @extends Heap
+ */
+export declare class MaxHeap<T = number> extends Heap<T> {
+    protected _pq: PriorityQueue<HeapItem<T>>;
+    /**
+     * The constructor initializes a PriorityQueue with a custom comparator function.
+     * @param [options] - The `options` parameter is an optional object that can be passed to the constructor. It is of
+     * type `HeapOptions<T>`, which is a generic type that represents the options for the heap.
+     */
+    constructor(options?: HeapOptions<T>);
+}

package/dist/max-heap.js

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MaxHeap = void 0;
+var data_structure_typed_1 = require("data-structure-typed");
+var data_structure_typed_2 = require("data-structure-typed");
+/**
+ * @class MaxHeap
+ * @extends Heap
+ */
+var MaxHeap = /** @class */ (function (_super) {
+    __extends(MaxHeap, _super);
+    /**
+     * The constructor initializes a PriorityQueue with a custom comparator function.
+     * @param [options] - The `options` parameter is an optional object that can be passed to the constructor. It is of
+     * type `HeapOptions<T>`, which is a generic type that represents the options for the heap.
+     */
+    function MaxHeap(options) {
+        var _this = _super.call(this, options) || this;
+        _this._pq = new data_structure_typed_2.PriorityQueue({
+            comparator: function (a, b) { return b.priority - a.priority; }
+        });
+        return _this;
+    }
+    return MaxHeap;
+}(data_structure_typed_1.Heap));
+exports.MaxHeap = MaxHeap;

package/dist/min-heap.d.ts

@@ -0,0 +1,24 @@
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+import { Heap, HeapItem } from 'data-structure-typed';
+import { PriorityQueue } from 'data-structure-typed';
+import type { HeapOptions } from 'data-structure-typed';
+/**
+ * @class MinHeap
+ * @extends Heap
+ */
+export declare class MinHeap<T = number> extends Heap<T> {
+    protected _pq: PriorityQueue<HeapItem<T>>;
+    /**
+     * The constructor initializes a PriorityQueue with a comparator function that compares the priority of two HeapItem
+     * objects.
+     * @param [options] - The `options` parameter is an optional object that can be passed to the constructor. It is of
+     * type `HeapOptions<T>`, which is a generic type that represents the options for the heap.
+     */
+    constructor(options?: HeapOptions<T>);
+}

package/dist/min-heap.js

@@ -0,0 +1,49 @@
+"use strict";
+/**
+ * data-structure-typed
+ *
+ * @author Tyler Zeng
+ * @copyright Copyright (c) 2022 Tyler Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MinHeap = void 0;
+var data_structure_typed_1 = require("data-structure-typed");
+var data_structure_typed_2 = require("data-structure-typed");
+/**
+ * @class MinHeap
+ * @extends Heap
+ */
+var MinHeap = /** @class */ (function (_super) {
+    __extends(MinHeap, _super);
+    /**
+     * The constructor initializes a PriorityQueue with a comparator function that compares the priority of two HeapItem
+     * objects.
+     * @param [options] - The `options` parameter is an optional object that can be passed to the constructor. It is of
+     * type `HeapOptions<T>`, which is a generic type that represents the options for the heap.
+     */
+    function MinHeap(options) {
+        var _this = _super.call(this, options) || this;
+        _this._pq = new data_structure_typed_2.PriorityQueue({
+            comparator: function (a, b) { return a.priority - b.priority; }
+        });
+        return _this;
+    }
+    return MinHeap;
+}(data_structure_typed_1.Heap));
+exports.MinHeap = MinHeap;

package/jest.config.js

@@ -0,0 +1,5 @@
+module.exports = {
+    preset: 'ts-jest',
+    testEnvironment: 'node',
+    testMatch: ['<rootDir>/tests/**/*.test.ts'],
+};

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "heap-typed",
+  "version": "1.19.3",
+  "description": "Heap. Javascript & Typescript Data Structure.",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "rm -rf dist && npx tsc",
+    "test": "jest",
+    "build:docs": "typedoc --out docs ./src",
+    "deps:check": "dependency-cruiser src",
+    "build:publish": "npm run build && npm run build:docs && npm publish"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/zrwusa/data-structure-typed"
+  },
+  "keywords": [
+    "Binary heap",
+    "Heap data structure",
+    "Priority queue",
+    "Min-heap",
+    "Max-heap",
+    "Complete binary tree",
+    "Heap property",
+    "Insertion",
+    "Deletion",
+    "Heapify",
+    "Heap sort",
+    "Heap operations",
+    "Parent",
+    "Child",
+    "Root",
+    "Heapify up",
+    "Heapify down",
+    "Extract minimum/maximum",
+    "Decrease key",
+    "Increase key",
+    "Heap operations complexity",
+    "Binary tree",
+    "Data structure",
+    "Efficient priority management"
+  ],
+  "author": "Tyler Zeng zrwusa@gmail.com",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/zrwusa/data-structure-typed/issues"
+  },
+  "homepage": "https://github.com/zrwusa/data-structure-typed#readme",
+  "types": "dist/index.d.ts",
+  "devDependencies": {
+    "@types/jest": "^29.5.3",
+    "@types/node": "^20.4.9",
+    "dependency-cruiser": "^13.1.2",
+    "jest": "^29.6.2",
+    "ts-jest": "^29.1.1",
+    "typedoc": "^0.24.8",
+    "typescript": "^4.9.5"
+  },
+  "dependencies": {
+    "data-structure-typed": "^1.19.3",
+    "zod": "^3.22.2"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,37 @@
+{
+  "compilerOptions": {
+    "declaration": true,
+    "outDir": "./dist",
+    "module": "commonjs",
+    "target": "es5",
+    "lib": [
+      "esnext",
+    ],
+    "strict": true,
+    "esModuleInterop": true,
+    "moduleResolution": "node",
+    "declarationDir": "./dist",
+    "skipLibCheck": true,
+    "downlevelIteration": true,
+    "experimentalDecorators": true,
+    //    "allowJs": true,
+    //    "allowSyntheticDefaultImports": true,
+    //    "forceConsistentCasingInFileNames": true,
+    //    "noFallthroughCasesInSwitch": true,
+    //    "resolveJsonModule": true,
+    //    "isolatedModules": true,
+    //    "noEmit": true,
+    "typeRoots": [
+      "node_modules/@types"
+    ]
+  },
+
+  "include": [
+    "src",
+  ],
+  "exclude": [
+//    "node_modules/data-structure-typed",
+    "node_modules",
+    "dist"
+  ]
+}