binary-tree-typed 2.4.5 → 2.5.0

package/dist/types/data-structures/matrix/matrix.d.ts

@@ -9,6 +9,89 @@ import type { MatrixOptions } from '../../types';
 /**
  *
  */
+/**
+ * Matrix — a numeric matrix with standard linear algebra operations.
+ *
+ * @example
+ * // Basic matrix arithmetic
+ *  const a = new Matrix([
+ *       [1, 2],
+ *       [3, 4]
+ *     ]);
+ *     const b = new Matrix([
+ *       [5, 6],
+ *       [7, 8]
+ *     ]);
+ *
+ *     const sum = a.add(b);
+ *     console.log(sum?.data); // [
+ *  //      [6, 8],
+ *  //      [10, 12]
+ *  //    ];
+ *
+ *     const diff = b.subtract(a);
+ *     console.log(diff?.data); // [
+ *  //      [4, 4],
+ *  //      [4, 4]
+ *  //    ];
+ * @example
+ * // Matrix multiplication for transformations
+ *  // 2x3 matrix * 3x2 matrix = 2x2 matrix
+ *     const a = new Matrix([
+ *       [1, 2, 3],
+ *       [4, 5, 6]
+ *     ]);
+ *     const b = new Matrix([
+ *       [7, 8],
+ *       [9, 10],
+ *       [11, 12]
+ *     ]);
+ *
+ *     const product = a.multiply(b);
+ *     console.log(product?.rows); // 2;
+ *     console.log(product?.cols); // 2;
+ *     // Row 0: 1*7+2*9+3*11=58, 1*8+2*10+3*12=64
+ *     // Row 1: 4*7+5*9+6*11=139, 4*8+5*10+6*12=154
+ *     console.log(product?.data); // [
+ *  //      [58, 64],
+ *  //      [139, 154]
+ *  //    ];
+ * @example
+ * // Matrix transpose (square matrix)
+ *  const m = new Matrix([
+ *       [1, 2, 3],
+ *       [4, 5, 6],
+ *       [7, 8, 9]
+ *     ]);
+ *
+ *     const transposed = m.transpose();
+ *     console.log(transposed.rows); // 3;
+ *     console.log(transposed.cols); // 3;
+ *     console.log(transposed.data); // [
+ *  //      [1, 4, 7],
+ *  //      [2, 5, 8],
+ *  //      [3, 6, 9]
+ *  //    ];
+ *
+ *     // Transpose of transpose = original
+ *     console.log(transposed.transpose().data); // m.data;
+ * @example
+ * // Get and set individual cells
+ *  const m = new Matrix([
+ *       [0, 0, 0],
+ *       [0, 0, 0]
+ *     ]);
+ *
+ *     m.set(0, 1, 42);
+ *     m.set(1, 2, 99);
+ *
+ *     console.log(m.get(0, 1)); // 42;
+ *     console.log(m.get(1, 2)); // 99;
+ *     console.log(m.get(0, 0)); // 0;
+ *
+ *     // Out of bounds returns undefined
+ *     console.log(m.get(5, 5)); // undefined;
+ */
 export declare class Matrix {
     /**
      * The constructor function initializes a matrix object with the provided data and options, or with
@@ -59,6 +142,33 @@ export declare class Matrix {
      * retrieve from the data array.
      * @returns The `get` function returns a number if the provided row and column indices are valid.
      * Otherwise, it returns `undefined`.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Get and set individual cells
+   *  const m = new Matrix([
+   *       [0, 0, 0],
+   *       [0, 0, 0]
+   *     ]);
+   *
+   *     m.set(0, 1, 42);
+   *     m.set(1, 2, 99);
+   *
+   *     console.log(m.get(0, 1)); // 42;
+   *     console.log(m.get(1, 2)); // 99;
+   *     console.log(m.get(0, 0)); // 0;
+   *
+   *     // Out of bounds returns undefined
+   *     console.log(m.get(5, 5)); // undefined;
      */
     get(row: number, col: number): number | undefined;
     /**
@@ -72,6 +182,24 @@ export declare class Matrix {
      * @returns a boolean value. It returns true if the index (row, col) is valid and the value is
      * successfully set in the data array. It returns false if the index is invalid and the value is not
      * set.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Modify individual cells
+   *  const m = Matrix.zeros(2, 2);
+   *     console.log(m.set(0, 0, 5)); // true;
+   *     console.log(m.set(1, 1, 10)); // true;
+   *     console.log(m.get(0, 0)); // 5;
+   *     console.log(m.get(1, 1)); // 10;
      */
     set(row: number, col: number, value: number): boolean;
     /**
@@ -86,6 +214,39 @@ export declare class Matrix {
      * @param {Matrix} matrix - The `matrix` parameter is an instance of the `Matrix` class.
      * @returns The `add` method returns a new `Matrix` object that represents the result of adding the
      * current matrix with the provided `matrix` parameter.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Basic matrix arithmetic
+   *  const a = new Matrix([
+   *       [1, 2],
+   *       [3, 4]
+   *     ]);
+   *     const b = new Matrix([
+   *       [5, 6],
+   *       [7, 8]
+   *     ]);
+   *
+   *     const sum = a.add(b);
+   *     console.log(sum?.data); // [
+   *  //      [6, 8],
+   *  //      [10, 12]
+   *  //    ];
+   *
+   *     const diff = b.subtract(a);
+   *     console.log(diff?.data); // [
+   *  //      [4, 4],
+   *  //      [4, 4]
+   *  //    ];
      */
     add(matrix: Matrix): Matrix | undefined;
     /**
@@ -94,6 +255,23 @@ export declare class Matrix {
      * @param {Matrix} matrix - The `matrix` parameter is an instance of the `Matrix` class. It
      * represents the matrix that you want to subtract from the current matrix.
      * @returns a new Matrix object with the result of the subtraction operation.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Element-wise subtraction
+   *  const a = Matrix.from([[5, 6], [7, 8]]);
+   *     const b = Matrix.from([[1, 2], [3, 4]]);
+   *     const result = a.subtract(b);
+   *     console.log(result?.toArray()); // [[4, 4], [4, 4]];
      */
     subtract(matrix: Matrix): Matrix | undefined;
     /**
@@ -101,23 +279,125 @@ export declare class Matrix {
      * as a new matrix.
      * @param {Matrix} matrix - The `matrix` parameter is an instance of the `Matrix` class.
      * @returns a new Matrix object.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Matrix multiplication for transformations
+   *  // 2x3 matrix * 3x2 matrix = 2x2 matrix
+   *     const a = new Matrix([
+   *       [1, 2, 3],
+   *       [4, 5, 6]
+   *     ]);
+   *     const b = new Matrix([
+   *       [7, 8],
+   *       [9, 10],
+   *       [11, 12]
+   *     ]);
+   *
+   *     const product = a.multiply(b);
+   *     console.log(product?.rows); // 2;
+   *     console.log(product?.cols); // 2;
+   *     // Row 0: 1*7+2*9+3*11=58, 1*8+2*10+3*12=64
+   *     // Row 1: 4*7+5*9+6*11=139, 4*8+5*10+6*12=154
+   *     console.log(product?.data); // [
+   *  //      [58, 64],
+   *  //      [139, 154]
+   *  //    ];
      */
     multiply(matrix: Matrix): Matrix | undefined;
     /**
      * The transpose function takes a matrix and returns a new matrix that is the transpose of the
      * original matrix.
      * @returns The transpose() function returns a new Matrix object with the transposed data.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Matrix transpose (square matrix)
+   *  const m = new Matrix([
+   *       [1, 2, 3],
+   *       [4, 5, 6],
+   *       [7, 8, 9]
+   *     ]);
+   *
+   *     const transposed = m.transpose();
+   *     console.log(transposed.rows); // 3;
+   *     console.log(transposed.cols); // 3;
+   *     console.log(transposed.data); // [
+   *  //      [1, 4, 7],
+   *  //      [2, 5, 8],
+   *  //      [3, 6, 9]
+   *  //    ];
+   *
+   *     // Transpose of transpose = original
+   *     console.log(transposed.transpose().data); // m.data;
      */
     transpose(): Matrix;
     /**
      * The `inverse` function calculates the inverse of a square matrix using Gaussian elimination.
      * @returns a Matrix object, which represents the inverse of the original matrix.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Compute the inverse of a 2x2 matrix
+   *  const m = Matrix.from([[4, 7], [2, 6]]);
+   *     const inv = m.inverse();
+   *     console.log(inv); // defined;
+   *     // A * A^-1 should ≈ Identity
+   *     const product = m.multiply(inv!);
+   *     console.log(product?.get(0, 0)); // toBeCloseTo;
+   *     console.log(product?.get(0, 1)); // toBeCloseTo;
+   *     console.log(product?.get(1, 0)); // toBeCloseTo;
+   *     console.log(product?.get(1, 1)); // toBeCloseTo;
      */
     inverse(): Matrix | undefined;
     /**
      * The dot function calculates the dot product of two matrices and returns a new matrix.
      * @param {Matrix} matrix - The `matrix` parameter is an instance of the `Matrix` class.
      * @returns a new Matrix object.
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+     
+      * @example
+   * // Dot product of two matrices
+   *  const a = Matrix.from([[1, 2], [3, 4]]);
+   *     const b = Matrix.from([[5, 6], [7, 8]]);
+   *     const result = a.dot(b);
+   *     console.log(result?.toArray()); // [[19, 22], [43, 50]];
      */
     dot(matrix: Matrix): Matrix | undefined;
     /**
@@ -136,6 +416,57 @@ export declare class Matrix {
      * and properties as the current instance.
      */
     clone(): Matrix;
+    /**
+     * Returns [rows, cols] dimensions tuple.
+     */
+    get size(): [number, number];
+    isEmpty(): boolean;
+    /**
+     * Returns a deep copy of the data as a plain 2D array.
+     */
+    toArray(): number[][];
+    /**
+     * Returns a flat row-major array.
+     */
+    flatten(): number[];
+    /**
+     * Iterates over rows.
+     */
+    [Symbol.iterator](): IterableIterator<number[]>;
+    /**
+     * Visits each element with its row and column index.
+     */
+    forEach(callback: (value: number, row: number, col: number) => void): void;
+    /**
+     * Maps each element (number → number) and returns a new Matrix.
+     */
+    map(callback: (value: number, row: number, col: number) => number): Matrix;
+    print(): void;
+    /**
+     * Creates a rows×cols zero matrix.
+     * @example
+     * ```ts
+     * const z = Matrix.zeros(2, 3); // [[0,0,0],[0,0,0]]
+     * ```
+     */
+    static zeros(rows: number, cols: number): Matrix;
+    /**
+     * Creates an n×n identity matrix.
+     * @example
+     * ```ts
+     * const I = Matrix.identity(3); // [[1,0,0],[0,1,0],[0,0,1]]
+     * ```
+     */
+    static identity(n: number): Matrix;
+    /**
+     * Creates a Matrix from a plain 2D array (deep copy).
+     * @example
+     * ```ts
+     * const m = Matrix.from([[1, 2], [3, 4]]);
+     * m.get(0, 1); // 2
+     * ```
+     */
+    static from(data: number[][]): Matrix;
     protected _addFn(a: number | undefined, b: number): number | undefined;
     protected _subtractFn(a: number, b: number): number;
     protected _multiplyFn(a: number, b: number): number;

package/dist/types/data-structures/priority-queue/max-priority-queue.d.ts

@@ -14,6 +14,63 @@ import { PriorityQueue } from './priority-queue';
  * @template E Element type stored in the queue.
  * @template R Extra record/metadata associated with each element.
  * @example
+ * // Job scheduling by priority
+ *  const jobs = new MaxPriorityQueue<number>();
+ *
+ *     jobs.add(3); // low priority
+ *     jobs.add(7); // high priority
+ *     jobs.add(5); // medium priority
+ *     jobs.add(10); // critical
+ *
+ *     // Highest priority job first
+ *     console.log(jobs.poll()); // 10;
+ *     console.log(jobs.poll()); // 7;
+ *     console.log(jobs.poll()); // 5;
+ *     console.log(jobs.poll()); // 3;
+ * @example
+ * // Auction system with highest bid tracking
+ *  interface Bid {
+ *       bidder: string;
+ *       amount: number;
+ *     }
+ *
+ *     const auction = new MaxPriorityQueue<Bid>([], {
+ *       comparator: (a, b) => b.amount - a.amount
+ *     });
+ *
+ *     auction.add({ bidder: 'Alice', amount: 100 });
+ *     auction.add({ bidder: 'Bob', amount: 250 });
+ *     auction.add({ bidder: 'Charlie', amount: 175 });
+ *
+ *     // Current highest bid
+ *     console.log(auction.peek()?.bidder); // 'Bob';
+ *     console.log(auction.peek()?.amount); // 250;
+ *
+ *     // Process winning bid
+ *     const winner = auction.poll()!;
+ *     console.log(winner.bidder); // 'Bob';
+ *     console.log(auction.peek()?.bidder); // 'Charlie';
+ * @example
+ * // CPU process scheduling
+ *  const cpuQueue = new MaxPriorityQueue<[number, string]>([], {
+ *       comparator: (a, b) => b[0] - a[0]
+ *     });
+ *
+ *     cpuQueue.add([5, 'System process']);
+ *     cpuQueue.add([1, 'Background task']);
+ *     cpuQueue.add([8, 'User interaction']);
+ *     cpuQueue.add([3, 'Network sync']);
+ *
+ *     const order = [];
+ *     while (cpuQueue.size > 0) {
+ *       order.push(cpuQueue.poll()![1]);
+ *     }
+ *     console.log(order); // [
+ *  //      'User interaction',
+ *  //      'System process',
+ *  //      'Network sync',
+ *  //      'Background task'
+ *  //    ];
  */
 export declare class MaxPriorityQueue<E = any, R = any> extends PriorityQueue<E, R> {
     /**

package/dist/types/data-structures/priority-queue/min-priority-queue.d.ts

@@ -14,6 +14,66 @@ import { PriorityQueue } from './priority-queue';
  * @template E Element type stored in the queue.
  * @template R Extra record/metadata associated with each element.
  * @example
+ * // Shortest job first scheduling
+ *  const jobs = new MinPriorityQueue<number>();
+ *
+ *     jobs.add(8);  // 8 seconds
+ *     jobs.add(2);  // 2 seconds
+ *     jobs.add(5);  // 5 seconds
+ *     jobs.add(1);  // 1 second
+ *
+ *     // Shortest job first
+ *     console.log(jobs.poll()); // 1;
+ *     console.log(jobs.poll()); // 2;
+ *     console.log(jobs.poll()); // 5;
+ *     console.log(jobs.poll()); // 8;
+ * @example
+ * // Event-driven simulation with timestamps
+ *  interface Event {
+ *       time: number;
+ *       action: string;
+ *     }
+ *
+ *     const timeline = new MinPriorityQueue<Event>([], {
+ *       comparator: (a, b) => a.time - b.time
+ *     });
+ *
+ *     timeline.add({ time: 300, action: 'Timeout' });
+ *     timeline.add({ time: 100, action: 'Request received' });
+ *     timeline.add({ time: 200, action: 'Processing done' });
+ *     timeline.add({ time: 150, action: 'Cache hit' });
+ *
+ *     const order = [];
+ *     while (timeline.size > 0) {
+ *       order.push(timeline.poll()!.action);
+ *     }
+ *     console.log(order); // [
+ *  //      'Request received',
+ *  //      'Cache hit',
+ *  //      'Processing done',
+ *  //      'Timeout'
+ *  //    ];
+ * @example
+ * // Huffman coding frequency selection
+ *  // Character frequencies for Huffman tree building
+ *     const freq = new MinPriorityQueue<[number, string]>([], {
+ *       comparator: (a, b) => a[0] - b[0]
+ *     });
+ *
+ *     freq.add([5, 'a']);
+ *     freq.add([9, 'b']);
+ *     freq.add([12, 'c']);
+ *     freq.add([2, 'd']);
+ *
+ *     // Always pick two lowest frequencies
+ *     const first = freq.poll()!;
+ *     const second = freq.poll()!;
+ *     console.log(first[1]); // 'd';  // freq 2
+ *     console.log(second[1]); // 'a'; // freq 5
+ *
+ *     // Combined node goes back
+ *     freq.add([first[0] + second[0], first[1] + second[1]]);
+ *     console.log(freq.peek()![0]); // 7;
  */
 export declare class MinPriorityQueue<E = any, R = any> extends PriorityQueue<E, R> {
     /**

package/dist/types/data-structures/priority-queue/priority-queue.d.ts

@@ -9,6 +9,66 @@ import type { PriorityQueueOptions } from '../../types';
 import { Heap } from '../heap';
 /**
  * @example
+ * // Hospital emergency room triage
+ *  interface Patient {
+ *       name: string;
+ *       severity: number; // 1 = critical, 5 = minor
+ *     }
+ *
+ *     const er = new PriorityQueue<Patient>([], {
+ *       comparator: (a, b) => a.severity - b.severity
+ *     });
+ *
+ *     er.add({ name: 'Flu symptoms', severity: 4 });
+ *     er.add({ name: 'Heart attack', severity: 1 });
+ *     er.add({ name: 'Broken arm', severity: 3 });
+ *     er.add({ name: 'Stroke', severity: 1 });
+ *
+ *     // Most critical patients first
+ *     console.log(er.poll()?.severity); // 1;
+ *     console.log(er.poll()?.severity); // 1;
+ *     console.log(er.poll()?.severity); // 3;
+ *     console.log(er.poll()?.severity); // 4;
+ * @example
+ * // Task scheduler with deadlines
+ *  interface Task {
+ *       name: string;
+ *       deadline: number; // hours until due
+ *     }
+ *
+ *     const scheduler = new PriorityQueue<Task>([], {
+ *       comparator: (a, b) => a.deadline - b.deadline
+ *     });
+ *
+ *     scheduler.add({ name: 'Report', deadline: 24 });
+ *     scheduler.add({ name: 'Email', deadline: 2 });
+ *     scheduler.add({ name: 'Meeting prep', deadline: 4 });
+ *     scheduler.add({ name: 'Code review', deadline: 8 });
+ *
+ *     // Process most urgent first
+ *     console.log(scheduler.peek()?.name); // 'Email';
+ *     console.log(scheduler.size); // 4;
+ *
+ *     const order = [];
+ *     while (scheduler.size > 0) {
+ *       order.push(scheduler.poll()!.name);
+ *     }
+ *     console.log(order); // ['Email', 'Meeting prep', 'Code review', 'Report'];
+ * @example
+ * // Bandwidth allocation with priorities
+ *  const bandwidth = new PriorityQueue<[number, string]>([], {
+ *       comparator: (a, b) => a[0] - b[0]
+ *     });
+ *
+ *     bandwidth.add([1, 'Video call']);     // highest priority
+ *     bandwidth.add([3, 'File download']);
+ *     bandwidth.add([2, 'Web browsing']);
+ *     bandwidth.add([1, 'Voice call']);
+ *
+ *     // Allocate bandwidth to highest priority first
+ *     console.log(bandwidth.poll()?.[1]); // 'Video call';
+ *     console.log(bandwidth.poll()?.[1]); // 'Voice call';
+ *     console.log(bandwidth.size); // 2;
  */
 export declare class PriorityQueue<E = any, R = any> extends Heap<E, R> {
     constructor(elements?: Iterable<E> | Iterable<R>, options?: PriorityQueueOptions<E, R>);