@emasoft/svg-matrix 1.0.30 → 1.0.31

package/src/bezier-analysis.js

@@ -28,7 +28,14 @@ Decimal.set({ precision: 80 });
  * @param {number|string|Decimal} x - Value to convert
  * @returns {Decimal}
  */
-const D = (x) => (x instanceof Decimal ? x : new Decimal(x));
+const D = (x) => {
+  // INPUT VALIDATION: Ensure input is not null or undefined
+  // WHY: Passing null/undefined to Decimal constructor throws cryptic errors
+  if (x == null) {
+    throw new Error(`D(): cannot convert null or undefined to Decimal`);
+  }
+  return x instanceof Decimal ? x : new Decimal(x);
+};
 
 /**
  * Validate that a value is a finite number (not NaN or Infinity).
@@ -39,6 +46,13 @@ const D = (x) => (x instanceof Decimal ? x : new Decimal(x));
  * @throws {Error} If value is not finite
  */
 function _assertFinite(val, context) {
+  // INPUT VALIDATION: Ensure val is a Decimal instance
+  // WHY: Calling .isFinite() on null/undefined/non-Decimal throws errors
+  if (!val || !(val instanceof Decimal)) {
+    throw new Error(
+      `${context}: expected Decimal instance, got ${typeof val}`,
+    );
+  }
   if (!val.isFinite()) {
     throw new Error(`${context}: encountered non-finite value ${val}`);
   }
@@ -135,6 +149,22 @@ export function bezierPoint(points, t) {
     );
   }
 
+  // POINT VALIDATION: Ensure each point is a valid [x, y] array
+  // WHY: Invalid point structure causes crashes when accessing indices
+  for (let i = 0; i < points.length; i++) {
+    if (
+      !points[i] ||
+      !Array.isArray(points[i]) ||
+      points[i].length < 2 ||
+      points[i][0] == null ||
+      points[i][1] == null
+    ) {
+      throw new Error(
+        `bezierPoint: points[${i}] must be a valid [x, y] array with non-null coordinates`,
+      );
+    }
+  }
+
   const tD = D(t);
   // PARAMETER VALIDATION: Warn if t is outside [0,1] but still compute
   // WHY: Values slightly outside [0,1] may occur in numerical algorithms
@@ -184,6 +214,22 @@ export function bezierPointHorner(points, t) {
     );
   }
 
+  // POINT VALIDATION: Ensure each point is a valid [x, y] array
+  // WHY: Invalid point structure causes crashes when accessing indices
+  for (let i = 0; i < points.length; i++) {
+    if (
+      !points[i] ||
+      !Array.isArray(points[i]) ||
+      points[i].length < 2 ||
+      points[i][0] == null ||
+      points[i][1] == null
+    ) {
+      throw new Error(
+        `bezierPointHorner: points[${i}] must be a valid [x, y] array with non-null coordinates`,
+      );
+    }
+  }
+
   const tD = D(t);
   const n = points.length - 1; // Degree
 
@@ -268,6 +314,14 @@ export function bezierDerivative(points, t, n = 1) {
     );
   }
 
+  // PARAMETER VALIDATION: Ensure n is a non-negative integer
+  // WHY: Negative or non-integer derivative orders are not meaningful
+  if (typeof n !== "number" || n < 0 || !Number.isInteger(n)) {
+    throw new Error(
+      `bezierDerivative: n must be a non-negative integer, got ${n}`,
+    );
+  }
+
   if (n === 0) {
     return bezierPoint(points, t);
   }
@@ -625,6 +679,15 @@ export function bezierCrop(points, t0, t1) {
     throw new Error("bezierCrop: t1 must be in range [0, 1]");
   }
 
+  // DIVISION BY ZERO PROTECTION: Check if t0 is too close to 1
+  // WHY: When t0 approaches 1, the denominator (1 - t0) approaches zero,
+  // causing division by zero in the parameter adjustment calculation
+  if (D(1).minus(t0D).abs().lt(NEAR_ZERO_THRESHOLD)) {
+    throw new Error(
+      "bezierCrop: t0 too close to 1, would cause division by zero in parameter adjustment",
+    );
+  }
+
   // First split at t0, take the right portion
   const { right: afterT0 } = bezierSplit(points, t0);
 
@@ -713,6 +776,14 @@ function findBezierRoots1D(points, component) {
     return []; // No roots possible for empty input
   }
 
+  // PARAMETER VALIDATION: Ensure component is valid
+  // WHY: Invalid component values would cause incorrect index access
+  if (component !== "x" && component !== "y") {
+    throw new Error(
+      `findBezierRoots1D: component must be 'x' or 'y', got '${component}'`,
+    );
+  }
+
   const idx = component === "x" ? 0 : 1;
   const roots = [];
 
@@ -776,37 +847,56 @@ function findBezierRoots1D(points, component) {
  * @returns {Decimal[]} Real roots
  */
 function solveQuadratic(a, b, c) {
+  // INPUT VALIDATION: Ensure all coefficients are valid Decimal instances
+  // WHY: Invalid inputs cause cryptic errors in arithmetic operations
+  if (a == null || b == null || c == null) {
+    throw new Error(
+      "solveQuadratic: coefficients a, b, c must not be null or undefined",
+    );
+  }
+  // Convert to Decimal if needed (use local variables to avoid param reassignment)
+  const aD = a instanceof Decimal ? a : D(a);
+  const bD = b instanceof Decimal ? b : D(b);
+  const cD = c instanceof Decimal ? c : D(c);
+
+  // Check for non-finite values
+  if (!aD.isFinite() || !bD.isFinite() || !cD.isFinite()) {
+    throw new Error(
+      "solveQuadratic: coefficients must be finite numbers, got non-finite values",
+    );
+  }
+
   // NUMERICAL STABILITY: Use threshold relative to coefficient magnitudes
   // to determine if 'a' is effectively zero (degenerate to linear equation)
   // WHY: Absolute thresholds fail when coefficients are scaled; relative threshold adapts
-  const coeffMag = Decimal.max(a.abs(), b.abs(), c.abs());
+  const coeffMag = Decimal.max(aD.abs(), bD.abs(), cD.abs());
 
   if (
     coeffMag.gt(0) &&
-    a.abs().div(coeffMag).lt(QUADRATIC_DEGENERATE_THRESHOLD)
+    aD.abs().div(coeffMag).lt(QUADRATIC_DEGENERATE_THRESHOLD)
   ) {
     // Linear equation: bx + c = 0
-    if (b.isZero()) return [];
-    return [c.neg().div(b)];
+    if (bD.isZero()) return [];
+    return [cD.neg().div(bD)];
   }
 
-  if (a.isZero()) {
-    if (b.isZero()) return [];
-    return [c.neg().div(b)];
+  if (aD.isZero()) {
+    if (bD.isZero()) return [];
+    return [cD.neg().div(bD)];
   }
 
-  const discriminant = b.times(b).minus(a.times(c).times(4));
+  const discriminant = bD.times(bD).minus(aD.times(cD).times(4));
 
   if (discriminant.lt(0)) {
     return []; // No real roots
   }
 
   if (discriminant.isZero()) {
-    return [b.neg().div(a.times(2))];
+    return [bD.neg().div(aD.times(2))];
   }
 
   const sqrtD = discriminant.sqrt();
-  const twoA = a.times(2);
+  const twoA = aD.times(2);
 
   // NUMERICAL STABILITY: Use Vieta's formula to compute the second root
   // when catastrophic cancellation would occur in the standard formula.
@@ -817,16 +907,28 @@ function solveQuadratic(a, b, c) {
   // x1 * x2 = c/a, so x2 = (c/a) / x1
 
   let root1, root2;
-  if (b.isNegative()) {
+  if (bD.isNegative()) {
     // -b is positive, so -b + sqrt(D) is well-conditioned
-    root1 = b.neg().plus(sqrtD).div(twoA);
+    root1 = bD.neg().plus(sqrtD).div(twoA);
     // Use Vieta's formula: x1 * x2 = c/a
-    root2 = c.div(a).div(root1);
+    // DIVISION BY ZERO PROTECTION: Check if root1 is zero before dividing
+    // WHY: When root1 is zero, Vieta's formula degenerates; use direct formula instead
+    if (root1.abs().lt(NEAR_ZERO_THRESHOLD)) {
+      root2 = bD.neg().minus(sqrtD).div(twoA);
+    } else {
+      root2 = cD.div(aD).div(root1);
+    }
   } else {
     // -b is negative or zero, so -b - sqrt(D) is well-conditioned
-    root1 = b.neg().minus(sqrtD).div(twoA);
+    root1 = bD.neg().minus(sqrtD).div(twoA);
     // Use Vieta's formula: x1 * x2 = c/a
-    root2 = c.div(a).div(root1);
+    // DIVISION BY ZERO PROTECTION: Check if root1 is zero before dividing
+    // WHY: When root1 is zero, Vieta's formula degenerates; use direct formula instead
+    if (root1.abs().lt(NEAR_ZERO_THRESHOLD)) {
+      root2 = bD.neg().plus(sqrtD).div(twoA);
+    } else {
+      root2 = cD.div(aD).div(root1);
+    }
   }
 
   return [root1, root2];
@@ -842,6 +944,45 @@ function solveQuadratic(a, b, c) {
  * @returns {Decimal[]} Roots in interval
  */
 function findRootsBySubdivision(coeffs, t0, t1, maxDepth) {
+  // INPUT VALIDATION: Ensure coeffs is valid and maxDepth is non-negative
+  // WHY: Empty coeffs would cause errors; negative maxDepth could cause infinite recursion
+  if (!coeffs || !Array.isArray(coeffs) || coeffs.length === 0) {
+    return []; // No roots possible for empty input
+  }
+  if (typeof maxDepth !== "number" || maxDepth < 0) {
+    throw new Error(
+      `findRootsBySubdivision: maxDepth must be non-negative number, got ${maxDepth}`,
+    );
+  }
+
+  // PARAMETER VALIDATION: Ensure t0 and t1 are valid
+  // WHY: Invalid interval bounds cause arithmetic errors
+  if (t0 == null || t1 == null) {
+    throw new Error(
+      "findRootsBySubdivision: t0 and t1 must not be null or undefined",
+    );
+  }
+  const t0D = t0 instanceof Decimal ? t0 : D(t0);
+  const t1D = t1 instanceof Decimal ? t1 : D(t1);
+  if (!t0D.isFinite() || !t1D.isFinite()) {
+    throw new Error(
+      "findRootsBySubdivision: t0 and t1 must be finite numbers",
+    );
+  }
+  if (t1D.lte(t0D)) {
+    throw new Error("findRootsBySubdivision: t1 must be greater than t0");
+  }
+
+  // COEFFICIENT VALIDATION: Ensure all coefficients are valid Decimals
+  // WHY: Sign checking requires .isNegative() and .isZero() methods
+  for (let i = 0; i < coeffs.length; i++) {
+    if (!coeffs[i] || !(coeffs[i] instanceof Decimal)) {
+      throw new Error(
+        `findRootsBySubdivision: coeffs[${i}] must be a Decimal instance`,
+      );
+    }
+  }
+
   // Check if interval might contain a root (sign change in convex hull)
   const signs = coeffs.map((c) => (c.isNegative() ? -1 : c.isZero() ? 0 : 1));
   const minSign = Math.min(...signs);
@@ -853,19 +994,19 @@ function findRootsBySubdivision(coeffs, t0, t1, maxDepth) {
   }
 
   // WHY: Use named constant for subdivision convergence check
-  if (maxDepth <= 0 || t1.minus(t0).lt(SUBDIVISION_CONVERGENCE_THRESHOLD)) {
+  if (maxDepth <= 0 || t1D.minus(t0D).lt(SUBDIVISION_CONVERGENCE_THRESHOLD)) {
     // Converged, return midpoint
-    return [t0.plus(t1).div(2)];
+    return [t0D.plus(t1D).div(2)];
   }
 
   // Subdivide at midpoint
-  const tMid = t0.plus(t1).div(2);
+  const tMid = t0D.plus(t1D).div(2);
 
   // Compute subdivided control points using de Casteljau
   const { left, right } = subdivideBezier1D(coeffs);
 
-  const leftRoots = findRootsBySubdivision(left, t0, tMid, maxDepth - 1);
-  const rightRoots = findRootsBySubdivision(right, tMid, t1, maxDepth - 1);
+  const leftRoots = findRootsBySubdivision(left, t0D, tMid, maxDepth - 1);
+  const rightRoots = findRootsBySubdivision(right, tMid, t1D, maxDepth - 1);
 
   return leftRoots.concat(rightRoots);
 }
@@ -880,6 +1021,14 @@ function findRootsBySubdivision(coeffs, t0, t1, maxDepth) {
  * @returns {{left: Decimal[], right: Decimal[]}} Two 1D Bezier curves representing left and right halves
  */
 function subdivideBezier1D(coeffs) {
+  // INPUT VALIDATION: Ensure coeffs is valid and non-empty
+  // WHY: Empty coeffs would cause errors in de Casteljau iteration
+  if (!coeffs || !Array.isArray(coeffs) || coeffs.length === 0) {
+    throw new Error(
+      "subdivideBezier1D: coeffs must be a non-empty array of control values",
+    );
+  }
+
   const half = D(0.5);
   let pts = coeffs.map((c) => D(c));
 
@@ -926,6 +1075,22 @@ export function bezierToPolynomial(points) {
     );
   }
 
+  // POINT VALIDATION: Ensure each point is a valid [x, y] array
+  // WHY: Destructuring and index access fail on invalid point structures
+  for (let i = 0; i < points.length; i++) {
+    if (
+      !points[i] ||
+      !Array.isArray(points[i]) ||
+      points[i].length < 2 ||
+      points[i][0] == null ||
+      points[i][1] == null
+    ) {
+      throw new Error(
+        `bezierToPolynomial: points[${i}] must be a valid [x, y] array with non-null coordinates`,
+      );
+    }
+  }
+
   const n = points.length - 1;
   const xCoeffs = [];
   const yCoeffs = [];
@@ -1003,6 +1168,21 @@ export function polynomialToBezier(xCoeffs, yCoeffs) {
     );
   }
 
+  // COEFFICIENT VALIDATION: Ensure all coefficients are valid (not null/undefined)
+  // WHY: Arithmetic operations fail on null/undefined values
+  for (let i = 0; i < xCoeffs.length; i++) {
+    if (xCoeffs[i] == null) {
+      throw new Error(
+        `polynomialToBezier: xCoeffs[${i}] is null or undefined`,
+      );
+    }
+    if (yCoeffs[i] == null) {
+      throw new Error(
+        `polynomialToBezier: yCoeffs[${i}] is null or undefined`,
+      );
+    }
+  }
+
   const n = xCoeffs.length - 1;
 
   if (n === 1) {
@@ -1487,6 +1667,14 @@ export function verifyBoundingBox(points, samples = 100, tolerance = "1e-40") {
     );
   }
 
+  // PARAMETER VALIDATION: Ensure samples is a positive integer
+  // WHY: Non-positive or non-integer samples would cause loop errors or division by zero
+  if (typeof samples !== "number" || samples < 1 || !Number.isInteger(samples)) {
+    throw new Error(
+      `verifyBoundingBox: samples must be a positive integer, got ${samples}`,
+    );
+  }
+
   const tol = D(tolerance);
   const errors = [];
 
@@ -1564,6 +1752,14 @@ export function verifyDerivative(points, t, order = 1, tolerance = "1e-8") {
     );
   }
 
+  // PARAMETER VALIDATION: Ensure order is a positive integer
+  // WHY: Negative or non-integer orders are not meaningful for derivatives
+  if (typeof order !== "number" || order < 0 || !Number.isInteger(order)) {
+    throw new Error(
+      `verifyDerivative: order must be a non-negative integer, got ${order}`,
+    );
+  }
+
   const tol = D(tolerance);
   const tD = D(t);