@emasoft/svg-matrix 1.0.30 → 1.0.31

package/src/arc-length.js

@@ -101,7 +101,9 @@ const DEFAULT_ARC_LENGTH_TOLERANCE = "1e-30";
  * WHY: Used in adaptive quadrature to determine if subdivision has converged
  * by comparing 5-point and 10-point Gauss-Legendre results. When results
  * differ by less than this, we accept the higher-order result.
+ * NOTE: Currently unused - kept for potential future enhancement.
  */
+ 
 const _SUBDIVISION_CONVERGENCE_THRESHOLD = new Decimal("1e-15");
 
 /**
@@ -195,6 +197,17 @@ export function arcLength(points, t0 = 0, t1 = 1, options = {}) {
  * @returns {Decimal} Speed (magnitude of derivative)
  */
 function speedAtT(points, t) {
+  // INPUT VALIDATION: Ensure points array and t parameter are valid
+  // WHY: bezierDerivative will fail cryptically if points is invalid or t is not a valid number
+  if (!points || !Array.isArray(points) || points.length < 2) {
+    throw new Error(
+      "speedAtT: points must be an array with at least 2 control points",
+    );
+  }
+  if (t === null || t === undefined) {
+    throw new Error("speedAtT: t parameter is required");
+  }
+
   const [dx, dy] = bezierDerivative(points, t, 1);
   const speedSquared = dx.times(dx).plus(dy.times(dy));
 
@@ -223,6 +236,50 @@ function speedAtT(points, t) {
  * @returns {Decimal} Integral approximation
  */
 function adaptiveQuadrature(f, a, b, tol, maxDepth, minDepth, depth) {
+  // INPUT VALIDATION: Ensure all parameters are valid
+  // WHY: Invalid parameters would cause cryptic errors deep in recursion
+  if (typeof f !== "function") {
+    throw new Error("adaptiveQuadrature: f must be a function");
+  }
+  if (!a || !(a instanceof Decimal)) {
+    throw new Error("adaptiveQuadrature: a must be a Decimal");
+  }
+  if (!b || !(b instanceof Decimal)) {
+    throw new Error("adaptiveQuadrature: b must be a Decimal");
+  }
+  if (!tol || !(tol instanceof Decimal) || tol.lte(0)) {
+    throw new Error(
+      "adaptiveQuadrature: tol must be a positive Decimal",
+    );
+  }
+  if (
+    typeof maxDepth !== "number" ||
+    maxDepth < 0 ||
+    !Number.isInteger(maxDepth)
+  ) {
+    throw new Error(
+      "adaptiveQuadrature: maxDepth must be a non-negative integer",
+    );
+  }
+  if (
+    typeof minDepth !== "number" ||
+    minDepth < 0 ||
+    !Number.isInteger(minDepth)
+  ) {
+    throw new Error(
+      "adaptiveQuadrature: minDepth must be a non-negative integer",
+    );
+  }
+  if (
+    typeof depth !== "number" ||
+    depth < 0 ||
+    !Number.isInteger(depth)
+  ) {
+    throw new Error(
+      "adaptiveQuadrature: depth must be a non-negative integer",
+    );
+  }
+
   // Compute integral using 5-point and 10-point rules
   const I5 = gaussLegendre(f, a, b, 5);
   const I10 = gaussLegendre(f, a, b, 10);
@@ -273,7 +330,31 @@ function adaptiveQuadrature(f, a, b, tol, maxDepth, minDepth, depth) {
  * @returns {Decimal} Integral approximation
  */
 function gaussLegendre(f, a, b, order) {
+  // INPUT VALIDATION: Ensure order is valid
+  // WHY: GAUSS_LEGENDRE only has entries for orders 5 and 10. Invalid order would cause undefined access.
+  if (order !== 5 && order !== 10) {
+    throw new Error(
+      "gaussLegendre: order must be 5 or 10 (only supported orders)",
+    );
+  }
+
   const gl = GAUSS_LEGENDRE[order];
+
+  // INTERNAL CONSISTENCY CHECK: Verify Gauss-Legendre table has correct structure
+  // WHY: Ensures the precomputed tables haven't been corrupted or misconfigured
+  if (!gl.nodes || !gl.weights || gl.nodes.length !== order || gl.weights.length !== order) {
+    throw new Error(
+      `gaussLegendre: GAUSS_LEGENDRE[${order}] table is malformed (expected ${order} nodes and weights)`,
+    );
+  }
+
+  // DIVISION BY ZERO CHECK: Ensure a != b
+  // WHY: If a == b, the integral is zero (no width), and halfWidth would be 0.
+  // While multiplying by 0 gives correct result (0), we should handle explicitly.
+  if (a.eq(b)) {
+    return D(0);
+  }
+
   const halfWidth = b.minus(a).div(2);
   const center = a.plus(b).div(2);
 
@@ -288,6 +369,22 @@ function gaussLegendre(f, a, b, order) {
 
     // Evaluate function and add weighted contribution
     const fValue = f(t);
+
+    // VALIDATION: Ensure function returns a valid Decimal
+    // WHY: If f returns null, undefined, NaN, or non-Decimal, arithmetic operations will fail
+    if (fValue === null || fValue === undefined) {
+      throw new Error("gaussLegendre: integrand function f returned null or undefined");
+    }
+    if (!(fValue instanceof Decimal)) {
+      throw new Error("gaussLegendre: integrand function f must return a Decimal instance");
+    }
+    if (fValue.isNaN()) {
+      throw new Error(`gaussLegendre: integrand function f returned NaN at t=${t}`);
+    }
+    if (!fValue.isFinite()) {
+      throw new Error(`gaussLegendre: integrand function f returned non-finite value at t=${t}`);
+    }
+
     sum = sum.plus(weight.times(fValue));
   }
 
@@ -336,6 +433,18 @@ export function inverseArcLength(points, targetLength, options = {}) {
     initialT,
   } = options;
 
+  // INPUT VALIDATION: Ensure maxIterations is a positive integer
+  // WHY: maxIterations controls the loop; negative or zero values would prevent convergence
+  if (
+    typeof maxIterations !== "number" ||
+    maxIterations <= 0 ||
+    !Number.isInteger(maxIterations)
+  ) {
+    throw new Error(
+      "inverseArcLength: maxIterations must be a positive integer",
+    );
+  }
+
   const target = D(targetLength);
   const tol = D(tolerance);
   const lengthOpts = { tolerance: lengthTolerance };
@@ -348,6 +457,15 @@ export function inverseArcLength(points, targetLength, options = {}) {
     throw new Error("inverseArcLength: targetLength must be non-negative");
   }
 
+  // EDGE CASE: Check for NaN or Infinity in targetLength
+  // WHY: NaN or Infinity would cause Newton's method to diverge or produce nonsensical results
+  if (target.isNaN()) {
+    throw new Error("inverseArcLength: targetLength cannot be NaN");
+  }
+  if (!target.isFinite()) {
+    throw new Error("inverseArcLength: targetLength must be finite");
+  }
+
   // Handle edge case: zero length
   if (target.isZero()) {
     return { t: D(0), length: D(0), iterations: 0, converged: true };
@@ -546,9 +664,15 @@ export function createArcLengthTable(points, samples = 100, options = {}) {
       "createArcLengthTable: points must have at least 2 control points",
     );
   }
-  if (samples < 2) {
+  // TYPE CHECK: Ensure samples is a valid number
+  // WHY: samples is used in arithmetic operations and as a loop bound
+  if (
+    typeof samples !== "number" ||
+    !Number.isInteger(samples) ||
+    samples < 2
+  ) {
     throw new Error(
-      "createArcLengthTable: samples must be at least 2 (for binary search to work)",
+      "createArcLengthTable: samples must be an integer >= 2 (for binary search to work)",
     );
   }
 
@@ -580,8 +704,23 @@ export function createArcLengthTable(points, samples = 100, options = {}) {
      * @returns {Decimal} Approximate t
      */
     getT(s) {
+      // INPUT VALIDATION: Ensure s is provided and valid
+      // WHY: Without s, we cannot perform the lookup. Catching this early prevents cryptic errors.
+      if (s === null || s === undefined) {
+        throw new Error("getT: arc length parameter s is required");
+      }
+
       const sD = D(s);
 
+      // EDGE CASE: Check for NaN or Infinity
+      // WHY: Invalid arc lengths would cause incorrect lookups
+      if (sD.isNaN()) {
+        throw new Error("getT: arc length s cannot be NaN");
+      }
+      if (!sD.isFinite()) {
+        throw new Error("getT: arc length s must be finite");
+      }
+
       if (sD.lte(0)) return D(0);
       if (sD.gte(this.totalLength)) return D(1);
 
@@ -610,7 +749,15 @@ export function createArcLengthTable(points, samples = 100, options = {}) {
       const t0 = table[lo].t;
       const t1 = table[hi].t;
 
-      const fraction = sD.minus(s0).div(s1.minus(s0));
+      // DIVISION BY ZERO CHECK: Handle degenerate case where s0 == s1
+      // WHY: If two consecutive table entries have the same arc length (e.g., at a cusp),
+      // division would fail. In this case, we return the midpoint t value.
+      const denominator = s1.minus(s0);
+      if (denominator.isZero()) {
+        return t0.plus(t1).div(2);
+      }
+
+      const fraction = sD.minus(s0).div(denominator);
       return t0.plus(t1.minus(t0).times(fraction));
     },
 
@@ -621,6 +768,13 @@ export function createArcLengthTable(points, samples = 100, options = {}) {
      * @returns {Decimal} Refined t
      */
     getTRefined(s, opts = {}) {
+      // INPUT VALIDATION: Ensure s is provided and valid
+      // WHY: This method calls getT internally which will validate, but we validate
+      // here too for consistent error messages at the API boundary.
+      if (s === null || s === undefined) {
+        throw new Error("getTRefined: arc length parameter s is required");
+      }
+
       const approxT = this.getT(s);
       // Use approxT as starting point for Newton
       const { t } = inverseArcLength(points, s, { ...opts, initialT: approxT });
@@ -652,6 +806,19 @@ export function verifyArcLength(points, computedLength = null) {
     );
   }
 
+  // ARRAY ELEMENT VALIDATION: Ensure points array elements are valid [x, y] pairs
+  // WHY: We access points[i][0] and points[i][1] below. Invalid structure would cause errors.
+  if (
+    !Array.isArray(points[0]) ||
+    points[0].length < 2 ||
+    !Array.isArray(points[points.length - 1]) ||
+    points[points.length - 1].length < 2
+  ) {
+    throw new Error(
+      "verifyArcLength: each point must be an array with at least 2 coordinates [x, y]",
+    );
+  }
+
   const errors = [];
 
   // Compute arc length if not provided
@@ -669,6 +836,19 @@ export function verifyArcLength(points, computedLength = null) {
   // Control polygon length
   let polygonLength = D(0);
   for (let i = 0; i < points.length - 1; i++) {
+    // ARRAY ELEMENT VALIDATION: Check each point in the loop
+    // WHY: Ensures all intermediate points are valid before accessing coordinates
+    if (!Array.isArray(points[i]) || points[i].length < 2) {
+      throw new Error(
+        `verifyArcLength: point at index ${i} must be an array with at least 2 coordinates [x, y]`,
+      );
+    }
+    if (!Array.isArray(points[i + 1]) || points[i + 1].length < 2) {
+      throw new Error(
+        `verifyArcLength: point at index ${i + 1} must be an array with at least 2 coordinates [x, y]`,
+      );
+    }
+
     const [x1, y1] = [D(points[i][0]), D(points[i][1])];
     const [x2, y2] = [D(points[i + 1][0]), D(points[i + 1][1])];
     polygonLength = polygonLength.plus(
@@ -684,12 +864,17 @@ export function verifyArcLength(points, computedLength = null) {
     errors.push(`Arc length ${length} > polygon length ${polygonLength}`);
   }
 
+  // DIVISION BY ZERO CHECK: Handle degenerate case where chord length is zero
+  // WHY: If start and end points are identical, chordLength is 0, causing division by zero.
+  // In this case, the ratio is not meaningful, so we return 1 (or could be Infinity).
+  const ratio = chordLength.gt(0) ? length.div(chordLength) : D(1);
+
   return {
     valid: errors.length === 0,
     chordLength,
     polygonLength,
     arcLength: length,
-    ratio: chordLength.gt(0) ? length.div(chordLength) : D(1),
+    ratio,
     errors,
   };
 }
@@ -771,6 +956,18 @@ export function verifyArcLengthBySubdivision(
     );
   }
 
+  // INPUT VALIDATION: Ensure subdivisions is a positive integer
+  // WHY: subdivisions is used as a divisor and loop bound. Zero or negative would cause division by zero or invalid loops.
+  if (
+    typeof subdivisions !== "number" ||
+    subdivisions <= 0 ||
+    !Number.isInteger(subdivisions)
+  ) {
+    throw new Error(
+      "verifyArcLengthBySubdivision: subdivisions must be a positive integer",
+    );
+  }
+
   const tol = D(tolerance);
 
   // Method 1: Adaptive quadrature
@@ -871,6 +1068,18 @@ export function verifyArcLengthTable(points, samples = 50) {
     );
   }
 
+  // INPUT VALIDATION: Ensure samples is a positive integer >= 2
+  // WHY: samples is passed to createArcLengthTable which requires it to be >= 2
+  if (
+    typeof samples !== "number" ||
+    !Number.isInteger(samples) ||
+    samples < 2
+  ) {
+    throw new Error(
+      "verifyArcLengthTable: samples must be an integer >= 2",
+    );
+  }
+
   const errors = [];
   const table = createArcLengthTable(points, samples);