data-structure-typed 2.5.3 → 2.6.1

package/src/data-structures/matrix/matrix.ts

@@ -116,7 +116,6 @@ export class Matrix {
       this._rows = data.length;
       this._cols = data[0]?.length ?? 0;
     }
-
     if (data.length > 0) {
       this._data = data;
     } else {
@@ -181,6 +180,51 @@ export class Matrix {
     return this._multiplyFn;
   }
 
+  /**
+   * Returns [rows, cols] dimensions tuple.
+   */
+  get size(): [number, number] {
+    return [this._rows, this._cols];
+  }
+
+  /**
+   * 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 {
+    const data: number[][] = Array.from({ length: rows }, () => new Array(cols).fill(0));
+    return new Matrix(data);
+  }
+
+  /**
+   * 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 {
+    const data: number[][] = Array.from({ length: n }, (_, i) =>
+      Array.from({ length: n }, (_, j) => (i === j ? 1 : 0))
+    );
+    return new Matrix(data);
+  }
+
+  /**
+   * 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 {
+    return new Matrix(data.map(row => [...row]));
+  }
+
   /**
    * The `get` function returns the value at the specified row and column index if it is a valid index.
    * @param {number} row - The `row` parameter represents the row index of the element you want to
@@ -189,61 +233,22 @@ export 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;
+   * @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 {
     if (this.isValidIndex(row, col)) {
@@ -262,52 +267,13 @@ export 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;
+   * @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 {
     if (this.isValidIndex(row, col)) {
@@ -332,73 +298,33 @@ export 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]
- *  //    ];
+   * @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 {
     if (!this.isMatchForCalculate(matrix)) {
       raise(Error, ERR.matrixDimensionMismatch('addition'));
     }
-
     const resultData: number[][] = [];
     for (let i = 0; i < this.rows; i++) {
       resultData[i] = [];
@@ -410,7 +336,6 @@ export class Matrix {
         }
       }
     }
-
     return new Matrix(resultData, {
       rows: this.rows,
       cols: this.cols,
@@ -426,57 +351,26 @@ export 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]];
+   * @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 {
     if (!this.isMatchForCalculate(matrix)) {
       raise(Error, ERR.matrixDimensionMismatch('subtraction'));
     }
-
     const resultData: number[][] = [];
     for (let i = 0; i < this.rows; i++) {
       resultData[i] = [];
@@ -488,7 +382,6 @@ export class Matrix {
         }
       }
     }
-
     return new Matrix(resultData, {
       rows: this.rows,
       cols: this.cols,
@@ -503,73 +396,33 @@ export 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]
- *  //    ];
+   * @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 {
     if (this.cols !== matrix.rows) {
       raise(Error, ERR.matrixDimensionMismatch('multiplication (A.cols must equal B.rows)'));
     }
-
     const resultData: number[][] = [];
     for (let i = 0; i < this.rows; i++) {
       resultData[i] = [];
@@ -588,7 +441,6 @@ export class Matrix {
         if (sum !== undefined) resultData[i][j] = sum;
       }
     }
-
     return new Matrix(resultData, {
       rows: this.rows,
       cols: matrix.cols,
@@ -602,72 +454,31 @@ export class Matrix {
    * 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;
+   * @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 {
     if (this.data.some(row => row.length !== this.cols)) {
       raise(Error, ERR.matrixNotRectangular());
     }
-
     const resultData: number[][] = [];
-
     for (let j = 0; j < this.cols; j++) {
       resultData[j] = [];
       for (let i = 0; i < this.rows; i++) {
@@ -675,7 +486,6 @@ export class Matrix {
         if (trans !== undefined) resultData[j][i] = trans;
       }
     }
-
     return new Matrix(resultData, {
       rows: this.cols,
       cols: this.rows,
@@ -685,66 +495,31 @@ export class Matrix {
     });
   }
 
+  // ─── Standard interface ─────────────────────────────────────
+
   /**
    * 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;
+   * @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 {
     // Check if the matrix is square
     if (this.rows !== this.cols) {
       raise(Error, ERR.matrixNotSquare());
     }
-
     // Create an augmented matrix [this | I]
     const augmentedMatrixData: number[][] = [];
     for (let i = 0; i < this.rows; i++) {
@@ -753,7 +528,6 @@ export class Matrix {
         augmentedMatrixData[i][this.cols + j] = i === j ? 1 : 0; // Append the identity matrix
       }
     }
-
     const augmentedMatrix = new Matrix(augmentedMatrixData, {
       rows: this.rows,
       cols: this.cols * 2,
@@ -761,7 +535,6 @@ export class Matrix {
       subtractFn: this.subtractFn,
       multiplyFn: this.multiplyFn
     });
-
     // Apply Gaussian elimination to transform the left half into the identity matrix
     for (let i = 0; i < this.rows; i++) {
       // Find pivot
@@ -769,42 +542,33 @@ export class Matrix {
       while (pivotRow < this.rows && augmentedMatrix.get(pivotRow, i) === 0) {
         pivotRow++;
       }
-
       if (pivotRow === this.rows) {
         // Matrix is singular, and its inverse does not exist
         raise(Error, ERR.matrixSingular());
       }
-
       // Swap rows to make the pivot the current row
       augmentedMatrix._swapRows(i, pivotRow);
-
       // Scale the pivot row to make the pivot element 1
       const pivotElement = augmentedMatrix.get(i, i) ?? 1;
-
       if (pivotElement === 0) {
         // Handle division by zero
         raise(Error, ERR.matrixSingular());
       }
-
       augmentedMatrix._scaleRow(i, 1 / pivotElement);
-
       // Eliminate other rows to make elements in the current column zero
       for (let j = 0; j < this.rows; j++) {
         if (j !== i) {
           let factor = augmentedMatrix.get(j, i);
           if (factor === undefined) factor = 0;
-
           augmentedMatrix._addScaledRow(j, i, -factor);
         }
       }
     }
-
     // Extract the right half of the augmented matrix as the inverse
     const inverseData: number[][] = [];
     for (let i = 0; i < this.rows; i++) {
       inverseData[i] = augmentedMatrix.data[i].slice(this.cols);
     }
-
     return new Matrix(inverseData, {
       rows: this.rows,
       cols: this.cols,
@@ -818,57 +582,26 @@ export class Matrix {
    * 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]];
+   * @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 {
     if (this.cols !== matrix.rows) {
       raise(Error, ERR.matrixDimensionMismatch('dot product (A.cols must equal B.rows)'));
     }
-
     const resultData: number[][] = [];
     for (let i = 0; i < this.rows; i++) {
       resultData[i] = [];
@@ -887,7 +620,6 @@ export class Matrix {
         if (sum !== undefined) resultData[i][j] = sum;
       }
     }
-
     return new Matrix(resultData, {
       rows: this.rows,
       cols: matrix.cols,
@@ -928,15 +660,6 @@ export class Matrix {
     );
   }
 
-  // ─── Standard interface ─────────────────────────────────────
-
-  /**
-   * Returns [rows, cols] dimensions tuple.
-   */
-  get size(): [number, number] {
-    return [this._rows, this._cols];
-  }
-
   isEmpty(): boolean {
     return this._rows === 0 || this._cols === 0;
   }
@@ -978,6 +701,8 @@ export class Matrix {
     };
   }
 
+  // ─── Factory methods ────────────────────────────────────────
+
   /**
    * Visits each element with its row and column index.
    */
@@ -1015,46 +740,6 @@ export class Matrix {
     }
   }
 
-  // ─── Factory methods ────────────────────────────────────────
-
-  /**
-   * 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 {
-    const data: number[][] = Array.from({ length: rows }, () => new Array(cols).fill(0));
-    return new Matrix(data);
-  }
-
-  /**
-   * 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 {
-    const data: number[][] = Array.from({ length: n }, (_, i) =>
-      Array.from({ length: n }, (_, j) => (i === j ? 1 : 0))
-    );
-    return new Matrix(data);
-  }
-
-  /**
-   * 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 {
-    return new Matrix(data.map(row => [...row]));
-  }
-
   protected _addFn(a: number | undefined, b: number): number | undefined {
     if (a === undefined) return b;
     return a + b;