data-structure-typed 2.5.0 → 2.5.1

package/dist/esm/matrix.mjs

@@ -0,0 +1,1038 @@
+var __defProp = Object.defineProperty;
+var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
+
+// src/common/error.ts
+var ERR = {
+  // Range / index
+  indexOutOfRange: /* @__PURE__ */ __name((index, min, max, ctx) => `${ctx ? ctx + ": " : ""}Index ${index} is out of range [${min}, ${max}].`, "indexOutOfRange"),
+  invalidIndex: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Index must be an integer.`, "invalidIndex"),
+  // Type / argument
+  invalidArgument: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidArgument"),
+  comparatorRequired: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Comparator is required for non-number/non-string/non-Date keys.`, "comparatorRequired"),
+  invalidKey: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidKey"),
+  notAFunction: /* @__PURE__ */ __name((name, ctx) => `${ctx ? ctx + ": " : ""}${name} must be a function.`, "notAFunction"),
+  invalidEntry: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Each entry must be a [key, value] tuple.`, "invalidEntry"),
+  invalidNaN: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}NaN is not a valid key.`, "invalidNaN"),
+  invalidDate: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Invalid Date key.`, "invalidDate"),
+  reduceEmpty: /* @__PURE__ */ __name((ctx) => `${ctx ? ctx + ": " : ""}Reduce of empty structure with no initial value.`, "reduceEmpty"),
+  callbackReturnType: /* @__PURE__ */ __name((expected, got, ctx) => `${ctx ? ctx + ": " : ""}Callback must return ${expected}; got ${got}.`, "callbackReturnType"),
+  // State / operation
+  invalidOperation: /* @__PURE__ */ __name((reason, ctx) => `${ctx ? ctx + ": " : ""}${reason}`, "invalidOperation"),
+  // Matrix
+  matrixDimensionMismatch: /* @__PURE__ */ __name((op) => `Matrix: Dimensions must be compatible for ${op}.`, "matrixDimensionMismatch"),
+  matrixSingular: /* @__PURE__ */ __name(() => "Matrix: Singular matrix, inverse does not exist.", "matrixSingular"),
+  matrixNotSquare: /* @__PURE__ */ __name(() => "Matrix: Must be square for inversion.", "matrixNotSquare"),
+  matrixNotRectangular: /* @__PURE__ */ __name(() => "Matrix: Must be rectangular for transposition.", "matrixNotRectangular"),
+  matrixRowMismatch: /* @__PURE__ */ __name((expected, got) => `Matrix: Expected row length ${expected}, but got ${got}.`, "matrixRowMismatch")
+};
+
+// src/data-structures/matrix/matrix.ts
+var Matrix = class _Matrix {
+  static {
+    __name(this, "Matrix");
+  }
+  /**
+   * The constructor function initializes a matrix object with the provided data and options, or with
+   * default values if no options are provided.
+   * @param {number[][]} data - A 2D array of numbers representing the data for the matrix.
+   * @param [options] - The `options` parameter is an optional object that can contain the following
+   * properties:
+   */
+  constructor(data, options) {
+    if (options) {
+      const { rows, cols, addFn, subtractFn, multiplyFn } = options;
+      if (typeof rows === "number" && rows > 0) this._rows = rows;
+      else this._rows = data.length;
+      if (typeof cols === "number" && cols > 0) this._cols = cols;
+      else this._cols = data[0]?.length || 0;
+      if (addFn) this._addFn = addFn;
+      if (subtractFn) this._subtractFn = subtractFn;
+      if (multiplyFn) this._multiplyFn = multiplyFn;
+    } else {
+      this._rows = data.length;
+      this._cols = data[0]?.length ?? 0;
+    }
+    if (data.length > 0) {
+      this._data = data;
+    } else {
+      this._data = [];
+      for (let i = 0; i < this.rows; i++) {
+        this._data[i] = new Array(this.cols).fill(0);
+      }
+    }
+  }
+  _rows = 0;
+  /**
+   * The function returns the number of rows.
+   * @returns The number of rows.
+   */
+  get rows() {
+    return this._rows;
+  }
+  _cols = 0;
+  /**
+   * The function returns the value of the protected variable _cols.
+   * @returns The number of columns.
+   */
+  get cols() {
+    return this._cols;
+  }
+  _data;
+  /**
+   * The function returns a two-dimensional array of numbers.
+   * @returns The data property, which is a two-dimensional array of numbers.
+   */
+  get data() {
+    return this._data;
+  }
+  /**
+   * The above function returns the value of the _addFn property.
+   * @returns The value of the property `_addFn` is being returned.
+   */
+  get addFn() {
+    return this._addFn;
+  }
+  /**
+   * The function returns the value of the _subtractFn property.
+   * @returns The `_subtractFn` property is being returned.
+   */
+  get subtractFn() {
+    return this._subtractFn;
+  }
+  /**
+   * The function returns the value of the _multiplyFn property.
+   * @returns The `_multiplyFn` property is being returned.
+   */
+  get multiplyFn() {
+    return this._multiplyFn;
+  }
+  /**
+    * 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
+    * retrieve from the data array.
+    * @param {number} col - The parameter "col" represents the column number of the element you want to
+    * 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, col) {
+    if (this.isValidIndex(row, col)) {
+      return this.data[row][col];
+    }
+  }
+  /**
+    * The set function updates the value at a specified row and column in a two-dimensional array.
+    * @param {number} row - The "row" parameter represents the row index of the element in a
+    * two-dimensional array or matrix. It specifies the row where the value will be set.
+    * @param {number} col - The "col" parameter represents the column index of the element in a
+    * two-dimensional array.
+    * @param {number} value - The value parameter represents the number that you want to set at the
+    * specified row and column in the data array.
+    * @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, col, value) {
+    if (this.isValidIndex(row, col)) {
+      this.data[row][col] = value;
+      return true;
+    }
+    return false;
+  }
+  /**
+   * The function checks if the dimensions of the given matrix match the dimensions of the current
+   * matrix.
+   * @param {Matrix} matrix - The parameter `matrix` is of type `Matrix`.
+   * @returns a boolean value.
+   */
+  isMatchForCalculate(matrix) {
+    return this.rows === matrix.rows && this.cols === matrix.cols;
+  }
+  /**
+    * The `add` function adds two matrices together, returning a new matrix with the result.
+    * @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) {
+    if (!this.isMatchForCalculate(matrix)) {
+      throw new Error(ERR.matrixDimensionMismatch("addition"));
+    }
+    const resultData = [];
+    for (let i = 0; i < this.rows; i++) {
+      resultData[i] = [];
+      for (let j = 0; j < this.cols; j++) {
+        const a = this.get(i, j), b = matrix.get(i, j);
+        if (a !== void 0 && b !== void 0) {
+          resultData[i][j] = this._addFn(a, b) ?? 0;
+        }
+      }
+    }
+    return new _Matrix(resultData, {
+      rows: this.rows,
+      cols: this.cols,
+      addFn: this.addFn,
+      subtractFn: this.subtractFn,
+      multiplyFn: this.multiplyFn
+    });
+  }
+  /**
+    * The `subtract` function performs element-wise subtraction between two matrices and returns a new
+    * matrix with the result.
+    * @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) {
+    if (!this.isMatchForCalculate(matrix)) {
+      throw new Error(ERR.matrixDimensionMismatch("subtraction"));
+    }
+    const resultData = [];
+    for (let i = 0; i < this.rows; i++) {
+      resultData[i] = [];
+      for (let j = 0; j < this.cols; j++) {
+        const a = this.get(i, j), b = matrix.get(i, j);
+        if (a !== void 0 && b !== void 0) {
+          resultData[i][j] = this._subtractFn(a, b) ?? 0;
+        }
+      }
+    }
+    return new _Matrix(resultData, {
+      rows: this.rows,
+      cols: this.cols,
+      addFn: this.addFn,
+      subtractFn: this.subtractFn,
+      multiplyFn: this.multiplyFn
+    });
+  }
+  /**
+    * The `multiply` function performs matrix multiplication between two matrices and returns the result
+    * 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) {
+    if (this.cols !== matrix.rows) {
+      throw new Error(ERR.matrixDimensionMismatch("multiplication (A.cols must equal B.rows)"));
+    }
+    const resultData = [];
+    for (let i = 0; i < this.rows; i++) {
+      resultData[i] = [];
+      for (let j = 0; j < matrix.cols; j++) {
+        let sum;
+        for (let k = 0; k < this.cols; k++) {
+          const a = this.get(i, k), b = matrix.get(k, j);
+          if (a !== void 0 && b !== void 0) {
+            const multiplied = this.multiplyFn(a, b);
+            if (multiplied !== void 0) {
+              sum = this.addFn(sum, multiplied);
+            }
+          }
+        }
+        if (sum !== void 0) resultData[i][j] = sum;
+      }
+    }
+    return new _Matrix(resultData, {
+      rows: this.rows,
+      cols: matrix.cols,
+      addFn: this.addFn,
+      subtractFn: this.subtractFn,
+      multiplyFn: this.multiplyFn
+    });
+  }
+  /**
+    * 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() {
+    if (this.data.some((row) => row.length !== this.cols)) {
+      throw new Error(ERR.matrixNotRectangular());
+    }
+    const resultData = [];
+    for (let j = 0; j < this.cols; j++) {
+      resultData[j] = [];
+      for (let i = 0; i < this.rows; i++) {
+        const trans = this.get(i, j);
+        if (trans !== void 0) resultData[j][i] = trans;
+      }
+    }
+    return new _Matrix(resultData, {
+      rows: this.cols,
+      cols: this.rows,
+      addFn: this.addFn,
+      subtractFn: this.subtractFn,
+      multiplyFn: this.multiplyFn
+    });
+  }
+  /**
+    * 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() {
+    if (this.rows !== this.cols) {
+      throw new Error(ERR.matrixNotSquare());
+    }
+    const augmentedMatrixData = [];
+    for (let i = 0; i < this.rows; i++) {
+      augmentedMatrixData[i] = this.data[i].slice();
+      for (let j = 0; j < this.cols; j++) {
+        augmentedMatrixData[i][this.cols + j] = i === j ? 1 : 0;
+      }
+    }
+    const augmentedMatrix = new _Matrix(augmentedMatrixData, {
+      rows: this.rows,
+      cols: this.cols * 2,
+      addFn: this.addFn,
+      subtractFn: this.subtractFn,
+      multiplyFn: this.multiplyFn
+    });
+    for (let i = 0; i < this.rows; i++) {
+      let pivotRow = i;
+      while (pivotRow < this.rows && augmentedMatrix.get(pivotRow, i) === 0) {
+        pivotRow++;
+      }
+      if (pivotRow === this.rows) {
+        throw new Error(ERR.matrixSingular());
+      }
+      augmentedMatrix._swapRows(i, pivotRow);
+      const pivotElement = augmentedMatrix.get(i, i) ?? 1;
+      if (pivotElement === 0) {
+        throw new Error(ERR.matrixSingular());
+      }
+      augmentedMatrix._scaleRow(i, 1 / pivotElement);
+      for (let j = 0; j < this.rows; j++) {
+        if (j !== i) {
+          let factor = augmentedMatrix.get(j, i);
+          if (factor === void 0) factor = 0;
+          augmentedMatrix._addScaledRow(j, i, -factor);
+        }
+      }
+    }
+    const inverseData = [];
+    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,
+      addFn: this.addFn,
+      subtractFn: this.subtractFn,
+      multiplyFn: this.multiplyFn
+    });
+  }
+  /**
+    * 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) {
+    if (this.cols !== matrix.rows) {
+      throw new Error(ERR.matrixDimensionMismatch("dot product (A.cols must equal B.rows)"));
+    }
+    const resultData = [];
+    for (let i = 0; i < this.rows; i++) {
+      resultData[i] = [];
+      for (let j = 0; j < matrix.cols; j++) {
+        let sum;
+        for (let k = 0; k < this.cols; k++) {
+          const a = this.get(i, k), b = matrix.get(k, j);
+          if (a !== void 0 && b !== void 0) {
+            const multiplied = this.multiplyFn(a, b);
+            if (multiplied !== void 0) {
+              sum = this.addFn(sum, multiplied);
+            }
+          }
+        }
+        if (sum !== void 0) resultData[i][j] = sum;
+      }
+    }
+    return new _Matrix(resultData, {
+      rows: this.rows,
+      cols: matrix.cols,
+      addFn: this.addFn,
+      subtractFn: this.subtractFn,
+      multiplyFn: this.multiplyFn
+    });
+  }
+  /**
+   * The function checks if a given row and column index is valid within a specified range.
+   * @param {number} row - The `row` parameter represents the row index of a two-dimensional array or
+   * matrix. It is a number that indicates the specific row in the matrix.
+   * @param {number} col - The "col" parameter represents the column index in a two-dimensional array
+   * or grid. It is used to check if the given column index is valid within the bounds of the grid.
+   * @returns A boolean value is being returned.
+   */
+  isValidIndex(row, col) {
+    return row >= 0 && row < this.rows && col >= 0 && col < this.cols;
+  }
+  /**
+   * The `clone` function returns a new instance of the Matrix class with the same data and properties
+   * as the original instance.
+   * @returns The `clone()` method is returning a new instance of the `Matrix` class with the same data
+   * and properties as the current instance.
+   */
+  clone() {
+    return new _Matrix(
+      this._data.map((row) => [...row]),
+      {
+        rows: this.rows,
+        cols: this.cols,
+        addFn: this.addFn,
+        subtractFn: this.subtractFn,
+        multiplyFn: this.multiplyFn
+      }
+    );
+  }
+  // ─── Standard interface ─────────────────────────────────────
+  /**
+   * Returns [rows, cols] dimensions tuple.
+   */
+  get size() {
+    return [this._rows, this._cols];
+  }
+  isEmpty() {
+    return this._rows === 0 || this._cols === 0;
+  }
+  /**
+   * Returns a deep copy of the data as a plain 2D array.
+   */
+  toArray() {
+    return this._data.map((row) => [...row]);
+  }
+  /**
+   * Returns a flat row-major array.
+   */
+  flatten() {
+    const result = [];
+    for (const row of this._data) {
+      for (const v of row) result.push(v);
+    }
+    return result;
+  }
+  /**
+   * Iterates over rows.
+   */
+  [Symbol.iterator]() {
+    const data = this._data;
+    let i = 0;
+    return {
+      [Symbol.iterator]() {
+        return this;
+      },
+      next() {
+        if (i < data.length) {
+          return { value: [...data[i++]], done: false };
+        }
+        return { value: void 0, done: true };
+      }
+    };
+  }
+  /**
+   * Visits each element with its row and column index.
+   */
+  forEach(callback) {
+    for (let i = 0; i < this._rows; i++) {
+      for (let j = 0; j < this._cols; j++) {
+        callback(this._data[i][j], i, j);
+      }
+    }
+  }
+  /**
+   * Maps each element (number → number) and returns a new Matrix.
+   */
+  map(callback) {
+    const resultData = [];
+    for (let i = 0; i < this._rows; i++) {
+      resultData[i] = [];
+      for (let j = 0; j < this._cols; j++) {
+        resultData[i][j] = callback(this._data[i][j], i, j);
+      }
+    }
+    return new _Matrix(resultData, {
+      rows: this._rows,
+      cols: this._cols,
+      addFn: this.addFn,
+      subtractFn: this.subtractFn,
+      multiplyFn: this.multiplyFn
+    });
+  }
+  print() {
+    for (const row of this._data) {
+      console.log(row.join("	"));
+    }
+  }
+  // ─── 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, cols) {
+    const data = 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) {
+    const data = Array.from(
+      { length: n },
+      (_, i) => Array.from({ length: n }, (_2, 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) {
+    return new _Matrix(data.map((row) => [...row]));
+  }
+  _addFn(a, b) {
+    if (a === void 0) return b;
+    return a + b;
+  }
+  _subtractFn(a, b) {
+    return a - b;
+  }
+  _multiplyFn(a, b) {
+    return a * b;
+  }
+  /**
+   * The function `_swapRows` swaps the positions of two rows in an array.
+   * @param {number} row1 - The `row1` parameter is the index of the first row that you want to swap.
+   * @param {number} row2 - The `row2` parameter is the index of the second row that you want to swap
+   * with the first row.
+   */
+  _swapRows(row1, row2) {
+    const temp = this.data[row1];
+    this.data[row1] = this.data[row2];
+    this.data[row2] = temp;
+  }
+  /**
+   * The function scales a specific row in a matrix by a given scalar value.
+   * @param {number} row - The `row` parameter represents the index of the row in the matrix that you
+   * want to scale. It is a number that indicates the position of the row within the matrix.
+   * @param {number} scalar - The scalar parameter is a number that is used to multiply each element in
+   * a specific row of a matrix.
+   */
+  _scaleRow(row, scalar) {
+    for (let j = 0; j < this.cols; j++) {
+      let multiplied = this.multiplyFn(this.data[row][j], scalar);
+      if (multiplied === void 0) multiplied = 0;
+      this.data[row][j] = multiplied;
+    }
+  }
+  /**
+   * The function `_addScaledRow` multiplies a row in a matrix by a scalar value and adds it to another
+   * row.
+   * @param {number} targetRow - The targetRow parameter represents the index of the row in which the
+   * scaled values will be added.
+   * @param {number} sourceRow - The sourceRow parameter represents the index of the row from which the
+   * values will be scaled and added to the targetRow.
+   * @param {number} scalar - The scalar parameter is a number that is used to scale the values in the
+   * source row before adding them to the target row.
+   */
+  _addScaledRow(targetRow, sourceRow, scalar) {
+    for (let j = 0; j < this.cols; j++) {
+      let multiplied = this.multiplyFn(this.data[sourceRow][j], scalar);
+      if (multiplied === void 0) multiplied = 0;
+      const scaledValue = multiplied;
+      let added = this.addFn(this.data[targetRow][j], scaledValue);
+      if (added === void 0) added = 0;
+      this.data[targetRow][j] = added;
+    }
+  }
+};
+
+// src/data-structures/matrix/navigator.ts
+var Character = class _Character {
+  static {
+    __name(this, "Character");
+  }
+  direction;
+  turn;
+  /**
+   * The constructor function takes in a direction and turning object and sets the direction and turn properties of the
+   * Character class.
+   * @param {Direction} direction - The direction parameter is used to specify the current direction of the character. It
+   * can be any value that represents a direction, such as "north", "south", "east", or "west".
+   * @param {Turning} turning - The `turning` parameter is an object that maps each direction to the corresponding
+   * turning direction. It is used to determine the new direction when the character turns.
+   */
+  constructor(direction, turning) {
+    this.direction = direction;
+    this.turn = () => new _Character(turning[direction], turning);
+  }
+};
+var Navigator = class {
+  static {
+    __name(this, "Navigator");
+  }
+  onMove;
+  _matrix;
+  _cur;
+  _character;
+  _VISITED;
+  /**
+   * The constructor initializes the Navigator object with the given parameters and sets the current position as visited
+   * in the matrix.
+   * @param  - - `matrix`: a 2D array representing the grid or map
+   */
+  constructor({ matrix, turning, onMove, init: { cur, charDir, VISITED } }) {
+    this._matrix = matrix;
+    this._cur = cur;
+    this._character = new Character(charDir, turning);
+    this.onMove = onMove;
+    if (this.onMove) this.onMove(this._cur);
+    this._VISITED = VISITED;
+    this._matrix[this._cur[0]][this._cur[1]] = this._VISITED;
+  }
+  /**
+   * The "start" function moves the character in its current direction until it encounters an obstacle, then it turns the
+   * character and repeats the process.
+   */
+  start() {
+    while (this.check(this._character.direction) || this.check(this._character.turn().direction)) {
+      const { direction } = this._character;
+      if (this.check(direction)) {
+        this.move(direction);
+      } else if (this.check(this._character.turn().direction)) {
+        this._character = this._character.turn();
+      }
+    }
+  }
+  /**
+   * The function checks if there is a valid move in the specified direction in a matrix.
+   * @param {Direction} direction - The direction parameter is a string that represents the direction in which to check.
+   * It can be one of the following values: 'up', 'right', 'down', or 'left'.
+   * @returns a boolean value.
+   */
+  check(direction) {
+    let forward, row;
+    const matrix = this._matrix;
+    const [i, j] = this._cur;
+    switch (direction) {
+      case "up":
+        row = matrix[i - 1];
+        if (!row) return false;
+        forward = row[j];
+        break;
+      case "right":
+        forward = matrix[i][j + 1];
+        break;
+      case "down":
+        row = matrix[i + 1];
+        if (!row) return false;
+        forward = row[j];
+        break;
+      case "left":
+        forward = matrix[i][j - 1];
+        break;
+    }
+    return forward !== void 0 && forward !== this._VISITED;
+  }
+  /**
+   * The `move` function updates the current position based on the given direction and updates the matrix accordingly.
+   * @param {Direction} direction - The `direction` parameter is a string that represents the direction in which to move.
+   * It can have one of the following values: 'up', 'right', 'down', or 'left'.
+   */
+  move(direction) {
+    switch (direction) {
+      case "up":
+        this._cur[0]--;
+        break;
+      case "right":
+        this._cur[1]++;
+        break;
+      case "down":
+        this._cur[0]++;
+        break;
+      case "left":
+        this._cur[1]--;
+        break;
+    }
+    const [i, j] = this._cur;
+    this._matrix[i][j] = this._VISITED;
+    if (this.onMove) this.onMove(this._cur);
+  }
+};
+/**
+ * data-structure-typed
+ *
+ * @author Pablo Zeng
+ * @copyright Copyright (c) 2022 Pablo Zeng <zrwusa@gmail.com>
+ * @license MIT License
+ */
+
+export { Character, Matrix, Navigator };
+//# sourceMappingURL=matrix.mjs.map
+//# sourceMappingURL=matrix.mjs.map