feat: add applyAlongAxis to reduce a matrix along a chosen dimension

[tayal-sarthak]

Closes #154.

Summary

ml-matrix ships fixed reductions along a dimension, such as sum, product, mean, with no way to supply a custom one. The linked issue reports having to copy a small helper between projects to collapse each row into a single value.

This adds applyAlongAxis(callback, by) on AbstractMatrix, using the signature proposed in the issue thread:

applyAlongAxis(
  callback: (vector: number[], index: number) => number,
  by: MatrixDimension,
): Matrix;

Behaviour

• by === 'row' calls the callback once per row, receiving that row as a plain array plus its index. The result is a column vector of size rows x 1.
• by === 'column' calls the callback once per column. The result is a row vector of size 1 x columns.
• The callback runs in the matrix context, matching apply.
• A callback that is not a function throws callback must be a function. An unknown dimension throws invalid option: <value>, matching sum, product, mean.
• The receiver is never mutated. The result is a plain Matrix, including when the receiver is a view, a SymmetricMatrix, a DistanceMatrix.

Defining it on AbstractMatrix means every matrix flavour picks it up.

Example

const M = new Matrix([
  [1, 2, 3],
  [4, 5, 6],
]);

const sumOf = (vector) => vector.reduce((total, value) => total + value, 0);

M.applyAlongAxis(sumOf, 'row'); // Matrix [[6], [15]]
M.applyAlongAxis(sumOf, 'column'); // Matrix [[5, 7, 9]]

The typing in matrix.d.ts is updated alongside the implementation. The README gains a short example under the existing examples section.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 68.88%. Comparing base (ee13f4b) to head (c10201a).
⚠️ Report is 2 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #214      +/-   ##
==========================================
+ Coverage   68.58%   68.88%   +0.30%     
==========================================
  Files          49       49              
  Lines        5847     5904      +57     
  Branches     1042     1060      +18     
==========================================
+ Hits         4010     4067      +57     
  Misses       1824     1824              
  Partials       13       13              

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[targos]

Code LGTM. I made a few changes to the API so it's more generic and closer to the existing axis reducer methods.

[stropitek]

Nice!