API गाइड

The default export is the Matrix class. Named exports include runtime helpers and global configuration.

import Matrix, {

  SIMD_REQUIRED,

  configure,

  createRuntime,

  isSimdSupported

} from "wasmatrix";

This page is generated from the TSDoc comments in index.d.ts, which is copied to dist/index.d.ts during the package build.

Runtime Helpers

`SIMD_REQUIRED`

const SIMD_REQUIRED: true

Whether this package requires WebAssembly SIMD support.

Remarks: This is always true. WASMatrix does not ship a scalar fallback.

`isSimdSupported(wasmBytes?)`

isSimdSupported(wasmBytes?: WasmBytes): boolean

Checks whether the current JavaScript runtime validates WASMatrix's SIMD WASM.

Parameter	Type	Description
`wasmBytes?`	`WasmBytes`	Optional explicit WASM bytes. When omitted, the default package WASM bytes loaded by the ESM entrypoint are used.

Returns: true when WebAssembly.validate() accepts the bytes.

`createRuntime(wasmBytes?)`

createRuntime(wasmBytes?: WasmBytes): unknown

Creates a separate WASM runtime instance.

Parameter	Type	Description
`wasmBytes?`	`WasmBytes`	Optional explicit WASM bytes. When omitted, the default package WASM bytes loaded by the ESM entrypoint are used.

Remarks: Most users should use the default runtime initialized by the package entrypoint. Separate runtimes are useful only when you intentionally want isolated WASM memories and caches.

Returns: An opaque runtime handle used internally by matrix instances.

Throws: Error if no default WASM bytes are loaded.

Throws: Error if SIMD validation or the ABI probe fails.

`configure(options?)`

configure(options?: WasmatrixOptions): void

Configures global optimization behavior.

Parameter	Type	Description
`options?`	`WasmatrixOptions`	Partial options to update.

Remarks: Existing matrices keep their data, but cache sizing changes can evict cached buffers immediately.

Configuration Options

Process-wide optimization and cache options.

Option	Type	Default	Description
`cacheLimitBytes`	`number`	`64 * 1024 * 1024`	Maximum WASM heap budget used by reusable caches. The limit covers factorization, transpose, packed operand, reduction, and expression-result caches. Set to `0` to aggressively evict reusable cache entries.
`fastMath`	`boolean`	`false`	Enables more aggressive algebraic rewrites. Keep this disabled when `NaN`, `Infinity`, `-0`, and strict floating-point rounding behavior are observable in your workflow.

`WasmBytes`

type WasmBytes = ArrayBuffer | ArrayBufferView

Raw WebAssembly module bytes accepted by runtime helpers.

`Matrix`

Dense row-major f32 matrix backed by WASM memory.

Remarks: Most operations return another Matrix. Data stays in WASM memory until you call a readback method such as Matrix.toArray, Matrix.toFloat32Array, Matrix.row, or Matrix.column.

Constructor

`new Matrix(rows, cols, data?, options?)`

new Matrix(rows: number, cols: number, data?: ArrayLike<number>, options?: { copy?: boolean })

Creates a matrix from row-major values.

Parameter	Type	Description
`rows`	`number`	Positive row count.
`cols`	`number`	Positive column count.
`data?`	`ArrayLike<number>`	Optional row-major values. Omitted values create a zero matrix.
`options?`	`{ copy?: boolean }`	Reserved construction options.

Throws: RangeError if rows, cols, or data.length are invalid.

Properties

Property	Type	Description
`byteOffset`	`readonly number`	Byte offset of the materialized matrix buffer inside WASM memory. Accessing this property can force lazy views or expressions to materialize.
`cols`	`readonly number`	Number of matrix columns.
`data`	`readonly Float32Array`	Snapshot copied from WASM memory when accessed. Mutating the returned typed array does not mutate the matrix. Use `Matrix.set` for scalar in-place writes.
`length`	`readonly number`	Total number of elements, equal to `rows * cols`.
`rows`	`readonly number`	Number of matrix rows.
`shape`	`readonly [number, number]`	Matrix shape as `[rows, cols]`.

Static Methods

`Matrix.configure(options?)`

Matrix.configure(options?: WasmatrixOptions): void

Equivalent to the top-level configure helper.

Parameter	Type	Description
`options?`	`WasmatrixOptions`	-

`Matrix.diagonal(values)`

Matrix.diagonal(values: Matrix | ArrayLike<number>): Matrix

Creates a dense diagonal matrix from vector values.

Parameter	Type	Description
`values`	`Matrix \| ArrayLike<number>`	-

Remarks: Diagonal structure is tracked for determinant, solve, inverse, and diagonal matrix multiplication shortcuts.

`Matrix.from(rows, cols, values)`

Matrix.from(rows: number, cols: number, values: ArrayLike<number>): Matrix

Creates a matrix from row-major values.

Parameter	Type	Description
`rows`	`number`	Positive row count.
`cols`	`number`	Positive column count.
`values`	`ArrayLike<number>`	Row-major values with length `rows * cols`.

`Matrix.identity(size)`

Matrix.identity(size: number): Matrix

Creates an identity matrix.

Parameter	Type	Description
`size`	`number`	-

Remarks: Identity structure is tracked so operations such as I.matmul(A) can use structural shortcuts.

`Matrix.matmulChain(...matrices)`

Matrix.matmulChain(...matrices: Matrix[]): Matrix

Multiplies a compatible chain of matrices using a shape-based cost model.

Parameter	Type	Description
`matrices`	`Matrix[]`	-

Remarks: The chain order is chosen by dynamic programming over matrix dimensions. Intermediate products are materialized and disposed where possible.

`Matrix.matmulChain(matrices)`

Matrix.matmulChain(matrices: Matrix[]): Matrix

Multiplies a compatible chain of matrices using a shape-based cost model.

Parameter	Type	Description
`matrices`	`Matrix[]`	-

Remarks: Array overload for callers that already hold the chain in a collection.

`Matrix.ones(rows, cols)`

Matrix.ones(rows: number, cols: number): Matrix

Creates a one-filled matrix.

Parameter	Type	Description
`rows`	`number`	-
`cols`	`number`	-

`Matrix.outer(a, b)`

Matrix.outer(a: Matrix | ArrayLike<number>, b: Matrix | ArrayLike<number>): Matrix

Computes the outer product of two vectors.

Parameter	Type	Description
`a`	`Matrix \| ArrayLike<number>`	Left vector.
`b`	`Matrix \| ArrayLike<number>`	Right vector.

Returns: A matrix with shape a.length x b.length.

`Matrix.random(rows, cols, rng?)`

Matrix.random(rows: number, cols: number, rng?: () => number): Matrix

Creates a matrix using a random value generator.

Parameter	Type	Description
`rows`	`number`	Positive row count.
`cols`	`number`	Positive column count.
`rng?`	`() => number`	Function returning each generated element. Defaults to `Math.random`.

`Matrix.zeros(rows, cols)`

Matrix.zeros(rows: number, cols: number): Matrix

Creates a zero-filled matrix.

Parameter	Type	Description
`rows`	`number`	-
`cols`	`number`	-

Reading And Writing

`at(row, col)`

at(row: number, col: number): number

Reads one scalar value from row, col.

Parameter	Type	Description
`row`	`number`	-
`col`	`number`	-

`set(row, col, value)`

set(row: number, col: number, value: number): this

Writes one scalar value in place.

Parameter	Type	Description
`row`	`number`	-
`col`	`number`	-
`value`	`number`	-

Remarks: This increments the matrix version and invalidates cached factorizations, reductions, materialized views, and packed operands.

Returns: This matrix.

`row(index)`

row(index: number): Float32Array

Copies one row into a JavaScript Float32Array.

Parameter	Type	Description
`index`	`number`	-

`column(index)`

column(index: number): Float32Array

Copies one column into a JavaScript Float32Array.

Parameter	Type	Description
`index`	`number`	-

`diagonal()`

diagonal(): Float32Array

Copies the main diagonal into a JavaScript Float32Array.

Remarks: The diagonal snapshot is cached by matrix version.

`reshape(rows, cols)`

reshape(rows: number, cols: number): Matrix

Creates a reshaped copy with the same element count.

Parameter	Type	Description
`rows`	`number`	-
`cols`	`number`	-

Throws: RangeError if rows * cols !== this.length.

`toFloat32Array()`

toFloat32Array(): Float32Array

Copies matrix contents into a JavaScript Float32Array.

`toFlatArray()`

toFlatArray(): number[]

Copies matrix contents into a row-major JavaScript number array.

`toArray()`

toArray(): number[][]

Copies matrix contents into nested JavaScript row arrays.

Elementwise Operations

`add(other)`

add(other: number | Matrix): Matrix

Adds a scalar, full matrix, row vector, or column vector.

Parameter	Type	Description
`other`	`number \| Matrix`	-

Remarks: Row vectors have shape 1 x cols; column vectors have shape rows x 1. Elementwise chains are represented lazily and fused when materialized.

`addScalar(value)`

addScalar(value: number): Matrix

Adds a scalar to every element lazily.

Parameter	Type	Description
`value`	`number`	-

`subtract(other)`

subtract(other: number | Matrix): Matrix

Subtracts a scalar, full matrix, row vector, or column vector.

Parameter	Type	Description
`other`	`number \| Matrix`	-

Remarks: Scalar subtraction lowers to an affine lazy expression.

`scale(value)`

scale(value: number): Matrix

Multiplies every element by a scalar lazily.

Parameter	Type	Description
`value`	`number`	-

`multiply(other)`

multiply(other: number | Matrix): Matrix

Multiplies by another value.

Parameter	Type	Description
`other`	`number \| Matrix`	-

Remarks: A numeric argument scales elementwise. A broadcast-compatible matrix uses elementwise multiplication. Other matrix arguments use matrix multiplication.

`divide(other)`

divide(other: number | Matrix): Matrix

Divides by a scalar, full matrix, row vector, or column vector.

Parameter	Type	Description
`other`	`number \| Matrix`	-

Remarks: Division follows JavaScript/WASM floating-point behavior for zero, NaN, and infinities.

`hadamard(other)`

hadamard(other: Matrix): Matrix

Elementwise matrix multiplication.

Parameter	Type	Description
`other`	`Matrix`	-

Remarks: Supports full-shape operands and row/column broadcasts.

`elementMultiply(other)`

elementMultiply(other: Matrix): Matrix

Alias for Matrix.hadamard.

Parameter	Type	Description
`other`	`Matrix`	-

`min(other)`

min(other: Matrix): Matrix

Elementwise minimum with a full or broadcast-compatible matrix.

Parameter	Type	Description
`other`	`Matrix`	-

`max(other)`

max(other: Matrix): Matrix

Elementwise maximum with a full or broadcast-compatible matrix.

Parameter	Type	Description
`other`	`Matrix`	-

`negate()`

negate(): Matrix

Negates every element lazily.

`abs()`

abs(): Matrix

Applies absolute value lazily.

`sqrt()`

sqrt(): Matrix

Applies square root lazily.

`floor()`

floor(): Matrix

Applies floor lazily.

`ceil()`

ceil(): Matrix

Applies ceiling lazily.

`clamp(minValue, maxValue)`

clamp(minValue: number, maxValue: number): Matrix

Clamps every element into [minValue, maxValue] lazily.

Parameter	Type	Description
`minValue`	`number`	-
`maxValue`	`number`	-

Throws: RangeError if minValue > maxValue.

`map(fn)`

map(fn: (value: number, row: number, col: number) => number): Matrix

Applies a JavaScript callback to every element.

Parameter	Type	Description
`fn`	`(value: number, row: number, col: number) => number`	-

Remarks: This reads the matrix into JavaScript and writes a new WASM-backed matrix. Prefer built-in elementwise methods when possible.

Matrix Operations

`transpose()`

transpose(): Matrix

Returns a lazy transpose view.

Remarks: The transposed buffer is materialized only when an operation requires a concrete layout. A.transpose().transpose() collapses back to A.

`matmul(other)`

matmul(other: Matrix): Matrix

Matrix multiplication.

Parameter	Type	Description
`other`	`Matrix`	-

Remarks: Transpose-aware kernels, diagonal shortcuts, identity/zero propagation, inverse-view solves, Gram/SPD tags, and packed operand caches may be used according to shape and structure.

`matvec(vector)`

matvec(vector: Matrix | ArrayLike<number>): Float32Array

Multiplies this matrix by a vector.

Parameter	Type	Description
`vector`	`Matrix \| ArrayLike<number>`	Array-like or matrix vector with length equal to `cols`.

Returns: A copied JavaScript Float32Array with length rows.

`dot(other)`

dot(other: Matrix | ArrayLike<number>): number

Computes the dot product with another vector-like value.

Parameter	Type	Description
`other`	`Matrix \| ArrayLike<number>`	-

Remarks: Both operands are flattened row-major and must have the same length.

`clone()`

clone(): Matrix

Creates a deep copy with its own WASM buffer.

Remarks: Lazy views are materialized before copying.

Reductions

`sum()`

sum(): number

Sums all elements, cached by matrix version.

`minValue()`

minValue(): number

Returns the minimum element, cached by matrix version.

`maxValue()`

maxValue(): number

Returns the maximum element, cached by matrix version.

`trace()`

trace(): number

Returns the trace of the matrix.

Remarks: For some lazy products, the trace can be computed without materializing the full dense product.

`frobeniusNorm()`

frobeniusNorm(): number

Returns the Frobenius norm, cached by matrix version.

Linear Algebra

`determinant()`

determinant(): number

Computes the determinant of a square matrix.

Remarks: Uses structural shortcuts, Cholesky for SPD-tagged matrices when available, and LU factorization otherwise. Results are cached by matrix version.

Throws: RangeError if the matrix is not square.

`logDet()`

logDet(): number

Computes the natural log of a positive determinant.

Remarks: Returns NaN when the available path determines that the determinant is not positive.

`inverse()`

inverse(): Matrix

Returns an inverse view where possible.

Remarks: The dense inverse is avoided until required. Expressions such as A.inverse().matmul(B) lower to A.solve(B).

`solve(rhs)`

solve(rhs: Matrix | ArrayLike<number>): Matrix

Solves this * X = rhs.

Parameter	Type	Description
`rhs`	`Matrix \| ArrayLike<number>`	-

Remarks: Square systems use diagonal, Cholesky, or LU paths depending on structure. Factorizations are cached by matrix version and reused across compatible determinant, solve, and inverse operations.

Throws: RangeError if the matrix is not square, the RHS shape is invalid, or the system is singular.

`leastSquares(rhs)`

leastSquares(rhs: Matrix | ArrayLike<number>): Matrix

Solves a least-squares system for tall or square matrices.

Parameter	Type	Description
`rhs`	`Matrix \| ArrayLike<number>`	-

Remarks: Uses QR factorization and shares the QR cache with Matrix.rank.

Throws: RangeError if rows < cols, the RHS shape is invalid, or the matrix is rank deficient.

`rank(epsilon?)`

rank(epsilon?: number): number

Estimates matrix rank with a QR factorization.

Parameter	Type	Description
`epsilon?`	`number`	Absolute threshold for nonzero diagonal entries of `R`.

Memory Management

`dispose()`

dispose(): void

Releases WASM memory and cached resources owned by this matrix.

Remarks: Calling dispose() more than once is safe. Do not use the matrix after it has been disposed.

`[Symbol.dispose]()`

[Symbol.dispose](): void

Integrates with runtimes that support explicit resource management.

Utilities

`equalsApprox(other, epsilon?)`

equalsApprox(other: Matrix, epsilon?: number): boolean

Compares matrices with an absolute tolerance.

Parameter	Type	Description
`other`	`Matrix`	Matrix with the same shape.
`epsilon?`	`number`	Absolute tolerance. Defaults to `1e-6`.

`toString()`

toString(): string

Formats the matrix as tab-separated rows.

Runtime Helpers
Configuration Options
WasmBytes
Matrix
Constructor
- new Matrix(rows, cols, data?, options?)
Properties
Static Methods
Reading And Writing
Elementwise Operations
Matrix Operations
Reductions
Linear Algebra
Memory Management
- dispose()
- [Symbol.dispose]()
Utilities
- equalsApprox(other, epsilon?)
- toString()

Runtime Helpers​

SIMD_REQUIRED​

isSimdSupported(wasmBytes?)​

createRuntime(wasmBytes?)​

configure(options?)​

Configuration Options​

WasmBytes​

Matrix​

Constructor​

new Matrix(rows, cols, data?, options?)​

Properties​

Static Methods​

Matrix.configure(options?)​

Matrix.diagonal(values)​

Matrix.from(rows, cols, values)​

Matrix.identity(size)​

Matrix.matmulChain(...matrices)​

Matrix.matmulChain(matrices)​

Matrix.ones(rows, cols)​

Matrix.outer(a, b)​

Matrix.random(rows, cols, rng?)​

Matrix.zeros(rows, cols)​

Reading And Writing​

at(row, col)​

set(row, col, value)​

row(index)​

column(index)​

diagonal()​

reshape(rows, cols)​

toFloat32Array()​

toFlatArray()​

toArray()​

Elementwise Operations​

add(other)​

addScalar(value)​

subtract(other)​

scale(value)​

multiply(other)​

divide(other)​

hadamard(other)​

elementMultiply(other)​

min(other)​

max(other)​

negate()​

abs()​

sqrt()​

floor()​

ceil()​

clamp(minValue, maxValue)​

map(fn)​

Matrix Operations​

transpose()​

matmul(other)​

matvec(vector)​

dot(other)​

clone()​

Reductions​

sum()​

minValue()​

maxValue()​

trace()​

frobeniusNorm()​

Linear Algebra​

determinant()​

logDet()​

inverse()​

solve(rhs)​

leastSquares(rhs)​

rank(epsilon?)​

Memory Management​

dispose()​

[Symbol.dispose]()​

Utilities​

equalsApprox(other, epsilon?)​

toString()​