@emasoft/svg-matrix 1.0.30 → 1.0.31

package/src/index.js

@@ -5,7 +5,7 @@
  * SVG path conversion, and 2D/3D affine transformations using Decimal.js.
  *
  * @module @emasoft/svg-matrix
- * @version 1.0.30
+ * @version 1.0.31
  * @license MIT
  *
  * @example
@@ -93,7 +93,6 @@ import {
   Logger,
   LogLevel,
   setLogLevel,
-  getLogLevel as _getLoggerLevel,
   enableFileLogging,
   disableFileLogging,
 } from "./logger.js";
@@ -135,7 +134,7 @@ Decimal.set({ precision: 80 });
  * Library version
  * @constant {string}
  */
-export const VERSION = '1.0.30';
+export const VERSION = '1.0.31';
 
 /**
  * Default precision for path output (decimal places)
@@ -352,8 +351,15 @@ export { Logger, LogLevel, setLogLevel, enableFileLogging, disableFileLogging };
  * @param {number|string|Decimal} tx - X translation
  * @param {number|string|Decimal} ty - Y translation
  * @returns {Matrix} 3x3 translation matrix
+ * @throws {TypeError} If tx or ty is null or undefined
  */
 export function translate2D(tx, ty) {
+  if (tx == null) {
+    throw new TypeError("translate2D: tx cannot be null or undefined");
+  }
+  if (ty == null) {
+    throw new TypeError("translate2D: ty cannot be null or undefined");
+  }
   return Transforms2D.translation(tx, ty);
 }
 
@@ -362,8 +368,12 @@ export function translate2D(tx, ty) {
  * Convenience wrapper for Transforms2D.rotate().
  * @param {number|string|Decimal} angle - Rotation angle in radians
  * @returns {Matrix} 3x3 rotation matrix
+ * @throws {TypeError} If angle is null or undefined
  */
 export function rotate2D(angle) {
+  if (angle == null) {
+    throw new TypeError("rotate2D: angle cannot be null or undefined");
+  }
   return Transforms2D.rotate(angle);
 }
 
@@ -373,8 +383,12 @@ export function rotate2D(angle) {
  * @param {number|string|Decimal} sx - X scale factor
  * @param {number|string|Decimal} [sy=sx] - Y scale factor (defaults to sx for uniform scaling)
  * @returns {Matrix} 3x3 scale matrix
+ * @throws {TypeError} If sx is null or undefined
  */
 export function scale2D(sx, sy = null) {
+  if (sx == null) {
+    throw new TypeError("scale2D: sx cannot be null or undefined");
+  }
   return Transforms2D.scale(sx, sy);
 }
 
@@ -385,8 +399,18 @@ export function scale2D(sx, sy = null) {
  * @param {number|string|Decimal} x - X coordinate
  * @param {number|string|Decimal} y - Y coordinate
  * @returns {[Decimal, Decimal]} Transformed [x, y] coordinates
+ * @throws {TypeError} If matrix, x, or y is null or undefined
  */
 export function transform2D(matrix, x, y) {
+  if (matrix == null) {
+    throw new TypeError("transform2D: matrix cannot be null or undefined");
+  }
+  if (x == null) {
+    throw new TypeError("transform2D: x cannot be null or undefined");
+  }
+  if (y == null) {
+    throw new TypeError("transform2D: y cannot be null or undefined");
+  }
   return Transforms2D.applyTransform(matrix, x, y);
 }
 
@@ -397,8 +421,18 @@ export function transform2D(matrix, x, y) {
  * @param {number|string|Decimal} ty - Y translation
  * @param {number|string|Decimal} tz - Z translation
  * @returns {Matrix} 4x4 translation matrix
+ * @throws {TypeError} If tx, ty, or tz is null or undefined
  */
 export function translate3D(tx, ty, tz) {
+  if (tx == null) {
+    throw new TypeError("translate3D: tx cannot be null or undefined");
+  }
+  if (ty == null) {
+    throw new TypeError("translate3D: ty cannot be null or undefined");
+  }
+  if (tz == null) {
+    throw new TypeError("translate3D: tz cannot be null or undefined");
+  }
   return Transforms3D.translation(tx, ty, tz);
 }
 
@@ -409,8 +443,12 @@ export function translate3D(tx, ty, tz) {
  * @param {number|string|Decimal} [sy=sx] - Y scale factor
  * @param {number|string|Decimal} [sz=sx] - Z scale factor
  * @returns {Matrix} 4x4 scale matrix
+ * @throws {TypeError} If sx is null or undefined
  */
 export function scale3D(sx, sy = null, sz = null) {
+  if (sx == null) {
+    throw new TypeError("scale3D: sx cannot be null or undefined");
+  }
   return Transforms3D.scale(sx, sy, sz);
 }
 
@@ -422,8 +460,21 @@ export function scale3D(sx, sy = null, sz = null) {
  * @param {number|string|Decimal} y - Y coordinate
  * @param {number|string|Decimal} z - Z coordinate
  * @returns {[Decimal, Decimal, Decimal]} Transformed [x, y, z] coordinates
+ * @throws {TypeError} If matrix, x, y, or z is null or undefined
  */
 export function transform3D(matrix, x, y, z) {
+  if (matrix == null) {
+    throw new TypeError("transform3D: matrix cannot be null or undefined");
+  }
+  if (x == null) {
+    throw new TypeError("transform3D: x cannot be null or undefined");
+  }
+  if (y == null) {
+    throw new TypeError("transform3D: y cannot be null or undefined");
+  }
+  if (z == null) {
+    throw new TypeError("transform3D: z cannot be null or undefined");
+  }
   return Transforms3D.applyTransform(matrix, x, y, z);
 }
 
@@ -435,8 +486,25 @@ export function transform3D(matrix, x, y, z) {
  * @param {number|string|Decimal} r - Radius
  * @param {number} [precision=6] - Number of decimal places in output
  * @returns {string} SVG path data string
+ * @throws {TypeError} If cx, cy, or r is null/undefined, or precision is not a number
+ * @throws {RangeError} If precision is negative
  */
 export function circleToPath(cx, cy, r, precision = DEFAULT_PRECISION) {
+  if (cx == null) {
+    throw new TypeError("circleToPath: cx cannot be null or undefined");
+  }
+  if (cy == null) {
+    throw new TypeError("circleToPath: cy cannot be null or undefined");
+  }
+  if (r == null) {
+    throw new TypeError("circleToPath: r cannot be null or undefined");
+  }
+  if (typeof precision !== "number" || !Number.isFinite(precision)) {
+    throw new TypeError(`circleToPath: precision must be a finite number, got ${typeof precision}`);
+  }
+  if (precision < 0) {
+    throw new RangeError(`circleToPath: precision must be non-negative, got ${precision}`);
+  }
   return GeometryToPath.circleToPathData(cx, cy, r, precision);
 }
 
@@ -448,8 +516,28 @@ export function circleToPath(cx, cy, r, precision = DEFAULT_PRECISION) {
  * @param {number|string|Decimal} ry - Y-axis radius
  * @param {number} [precision=6] - Number of decimal places in output
  * @returns {string} SVG path data string
+ * @throws {TypeError} If cx, cy, rx, or ry is null/undefined, or precision is not a number
+ * @throws {RangeError} If precision is negative
  */
 export function ellipseToPath(cx, cy, rx, ry, precision = DEFAULT_PRECISION) {
+  if (cx == null) {
+    throw new TypeError("ellipseToPath: cx cannot be null or undefined");
+  }
+  if (cy == null) {
+    throw new TypeError("ellipseToPath: cy cannot be null or undefined");
+  }
+  if (rx == null) {
+    throw new TypeError("ellipseToPath: rx cannot be null or undefined");
+  }
+  if (ry == null) {
+    throw new TypeError("ellipseToPath: ry cannot be null or undefined");
+  }
+  if (typeof precision !== "number" || !Number.isFinite(precision)) {
+    throw new TypeError(`ellipseToPath: precision must be a finite number, got ${typeof precision}`);
+  }
+  if (precision < 0) {
+    throw new RangeError(`ellipseToPath: precision must be non-negative, got ${precision}`);
+  }
   return GeometryToPath.ellipseToPathData(cx, cy, rx, ry, precision);
 }
 
@@ -463,6 +551,8 @@ export function ellipseToPath(cx, cy, rx, ry, precision = DEFAULT_PRECISION) {
  * @param {number|string|Decimal} [ry=rx] - Corner Y radius
  * @param {number} [precision=6] - Number of decimal places in output
  * @returns {string} SVG path data string
+ * @throws {TypeError} If x, y, width, or height is null/undefined, or precision is not a number
+ * @throws {RangeError} If precision is negative
  */
 export function rectToPath(
   x,
@@ -473,6 +563,24 @@ export function rectToPath(
   ry = null,
   precision = DEFAULT_PRECISION,
 ) {
+  if (x == null) {
+    throw new TypeError("rectToPath: x cannot be null or undefined");
+  }
+  if (y == null) {
+    throw new TypeError("rectToPath: y cannot be null or undefined");
+  }
+  if (width == null) {
+    throw new TypeError("rectToPath: width cannot be null or undefined");
+  }
+  if (height == null) {
+    throw new TypeError("rectToPath: height cannot be null or undefined");
+  }
+  if (typeof precision !== "number" || !Number.isFinite(precision)) {
+    throw new TypeError(`rectToPath: precision must be a finite number, got ${typeof precision}`);
+  }
+  if (precision < 0) {
+    throw new RangeError(`rectToPath: precision must be non-negative, got ${precision}`);
+  }
   return GeometryToPath.rectToPathData(
     x,
     y,
@@ -493,8 +601,28 @@ export function rectToPath(
  * @param {number|string|Decimal} y2 - End Y coordinate
  * @param {number} [precision=6] - Number of decimal places in output
  * @returns {string} SVG path data string
+ * @throws {TypeError} If x1, y1, x2, or y2 is null/undefined, or precision is not a number
+ * @throws {RangeError} If precision is negative
  */
 export function lineToPath(x1, y1, x2, y2, precision = DEFAULT_PRECISION) {
+  if (x1 == null) {
+    throw new TypeError("lineToPath: x1 cannot be null or undefined");
+  }
+  if (y1 == null) {
+    throw new TypeError("lineToPath: y1 cannot be null or undefined");
+  }
+  if (x2 == null) {
+    throw new TypeError("lineToPath: x2 cannot be null or undefined");
+  }
+  if (y2 == null) {
+    throw new TypeError("lineToPath: y2 cannot be null or undefined");
+  }
+  if (typeof precision !== "number" || !Number.isFinite(precision)) {
+    throw new TypeError(`lineToPath: precision must be a finite number, got ${typeof precision}`);
+  }
+  if (precision < 0) {
+    throw new RangeError(`lineToPath: precision must be non-negative, got ${precision}`);
+  }
   return GeometryToPath.lineToPathData(x1, y1, x2, y2, precision);
 }
 
@@ -503,8 +631,19 @@ export function lineToPath(x1, y1, x2, y2, precision = DEFAULT_PRECISION) {
  * @param {string|Array<[number, number]>} points - SVG points attribute or array of [x, y] pairs
  * @param {number} [precision=6] - Number of decimal places in output
  * @returns {string} SVG path data string (closed)
+ * @throws {TypeError} If points is null/undefined, or precision is not a number
+ * @throws {RangeError} If precision is negative
  */
 export function polygonToPath(points, precision = DEFAULT_PRECISION) {
+  if (points == null) {
+    throw new TypeError("polygonToPath: points cannot be null or undefined");
+  }
+  if (typeof precision !== "number" || !Number.isFinite(precision)) {
+    throw new TypeError(`polygonToPath: precision must be a finite number, got ${typeof precision}`);
+  }
+  if (precision < 0) {
+    throw new RangeError(`polygonToPath: precision must be non-negative, got ${precision}`);
+  }
   return GeometryToPath.polygonToPathData(points, precision);
 }
 
@@ -513,8 +652,19 @@ export function polygonToPath(points, precision = DEFAULT_PRECISION) {
  * @param {string|Array<[number, number]>} points - SVG points attribute or array of [x, y] pairs
  * @param {number} [precision=6] - Number of decimal places in output
  * @returns {string} SVG path data string (open)
+ * @throws {TypeError} If points is null/undefined, or precision is not a number
+ * @throws {RangeError} If precision is negative
  */
 export function polylineToPath(points, precision = DEFAULT_PRECISION) {
+  if (points == null) {
+    throw new TypeError("polylineToPath: points cannot be null or undefined");
+  }
+  if (typeof precision !== "number" || !Number.isFinite(precision)) {
+    throw new TypeError(`polylineToPath: precision must be a finite number, got ${typeof precision}`);
+  }
+  if (precision < 0) {
+    throw new RangeError(`polylineToPath: precision must be non-negative, got ${precision}`);
+  }
   return GeometryToPath.polylineToPathData(points, precision);
 }
 
@@ -531,8 +681,12 @@ export function getKappa() {
  * Parse SVG path data into an array of commands with Decimal arguments.
  * @param {string} pathData - SVG path data string
  * @returns {Array<{command: string, args: Decimal[]}>} Parsed commands
+ * @throws {TypeError} If pathData is null or undefined
  */
 export function parsePath(pathData) {
+  if (pathData == null) {
+    throw new TypeError("parsePath: pathData cannot be null or undefined");
+  }
   return GeometryToPath.parsePathData(pathData);
 }
 
@@ -541,8 +695,19 @@ export function parsePath(pathData) {
  * @param {Array<{command: string, args: Decimal[]}>} commands - Path commands
  * @param {number} [precision=6] - Number of decimal places in output
  * @returns {string} SVG path data string
+ * @throws {TypeError} If commands is null/undefined, or precision is not a number
+ * @throws {RangeError} If precision is negative
  */
 export function pathToString(commands, precision = DEFAULT_PRECISION) {
+  if (commands == null) {
+    throw new TypeError("pathToString: commands cannot be null or undefined");
+  }
+  if (typeof precision !== "number" || !Number.isFinite(precision)) {
+    throw new TypeError(`pathToString: precision must be a finite number, got ${typeof precision}`);
+  }
+  if (precision < 0) {
+    throw new RangeError(`pathToString: precision must be non-negative, got ${precision}`);
+  }
   return GeometryToPath.pathArrayToString(commands, precision);
 }
 
@@ -550,8 +715,12 @@ export function pathToString(commands, precision = DEFAULT_PRECISION) {
  * Convert relative path commands to absolute.
  * @param {string} pathData - SVG path data (may contain relative commands)
  * @returns {string} SVG path data with only absolute commands
+ * @throws {TypeError} If pathData is null or undefined
  */
 export function pathToAbsolute(pathData) {
+  if (pathData == null) {
+    throw new TypeError("pathToAbsolute: pathData cannot be null or undefined");
+  }
   return GeometryToPath.pathToAbsolute(pathData);
 }
 
@@ -560,8 +729,12 @@ export function pathToAbsolute(pathData) {
  * Lines become degenerate cubics, quadratics are elevated to cubics.
  * @param {string} pathData - SVG path data
  * @returns {string} SVG path data with only M, C, and Z commands
+ * @throws {TypeError} If pathData is null or undefined
  */
 export function pathToCubics(pathData) {
+  if (pathData == null) {
+    throw new TypeError("pathToCubics: pathData cannot be null or undefined");
+  }
   return GeometryToPath.pathToCubics(pathData);
 }
 
@@ -571,8 +744,22 @@ export function pathToCubics(pathData) {
  * @param {Matrix} matrix - 3x3 transformation matrix
  * @param {number} [precision=6] - Number of decimal places in output
  * @returns {string} Transformed SVG path data
+ * @throws {TypeError} If pathData or matrix is null/undefined, or precision is not a number
+ * @throws {RangeError} If precision is negative
  */
 export function transformPath(pathData, matrix, precision = DEFAULT_PRECISION) {
+  if (pathData == null) {
+    throw new TypeError("transformPath: pathData cannot be null or undefined");
+  }
+  if (matrix == null) {
+    throw new TypeError("transformPath: matrix cannot be null or undefined");
+  }
+  if (typeof precision !== "number" || !Number.isFinite(precision)) {
+    throw new TypeError(`transformPath: precision must be a finite number, got ${typeof precision}`);
+  }
+  if (precision < 0) {
+    throw new RangeError(`transformPath: precision must be non-negative, got ${precision}`);
+  }
   return GeometryToPath.transformPathData(pathData, matrix, precision);
 }
 
@@ -582,8 +769,19 @@ export function transformPath(pathData, matrix, precision = DEFAULT_PRECISION) {
  * @param {Object|Element} element - SVG element or object with tagName and attributes
  * @param {number} [precision=6] - Number of decimal places in output
  * @returns {string|null} SVG path data string, or null if element type not supported
+ * @throws {TypeError} If element is null/undefined, or precision is not a number
+ * @throws {RangeError} If precision is negative
  */
 export function elementToPath(element, precision = DEFAULT_PRECISION) {
+  if (element == null) {
+    throw new TypeError("elementToPath: element cannot be null or undefined");
+  }
+  if (typeof precision !== "number" || !Number.isFinite(precision)) {
+    throw new TypeError(`elementToPath: precision must be a finite number, got ${typeof precision}`);
+  }
+  if (precision < 0) {
+    throw new RangeError(`elementToPath: precision must be non-negative, got ${precision}`);
+  }
   return GeometryToPath.convertElementToPath(element, precision);
 }
 
@@ -591,8 +789,18 @@ export function elementToPath(element, precision = DEFAULT_PRECISION) {
  * Create an identity matrix of the given size.
  * @param {number} n - Matrix dimension (creates n x n identity matrix)
  * @returns {Matrix} Identity matrix
+ * @throws {TypeError} If n is not a number
+ * @throws {RangeError} If n is not a positive integer
  */
 export function identity(n) {
+  // Validate n is a number
+  if (typeof n !== "number" || !Number.isFinite(n)) {
+    throw new TypeError(`identity: n must be a finite number, got ${typeof n}`);
+  }
+  // Validate n is a positive integer
+  if (!Number.isInteger(n) || n < 1) {
+    throw new RangeError(`identity: n must be a positive integer, got ${n}`);
+  }
   return Matrix.identity(n);
 }
 
@@ -601,8 +809,30 @@ export function identity(n) {
  * @param {number} rows - Number of rows
  * @param {number} cols - Number of columns
  * @returns {Matrix} Zero matrix
+ * @throws {TypeError} If rows or cols is not a number
+ * @throws {RangeError} If rows or cols is not a positive integer
  */
 export function zeros(rows, cols) {
+  // Validate rows is a number
+  if (typeof rows !== "number" || !Number.isFinite(rows)) {
+    throw new TypeError(
+      `zeros: rows must be a finite number, got ${typeof rows}`,
+    );
+  }
+  // Validate cols is a number
+  if (typeof cols !== "number" || !Number.isFinite(cols)) {
+    throw new TypeError(
+      `zeros: cols must be a finite number, got ${typeof cols}`,
+    );
+  }
+  // Validate rows is a positive integer
+  if (!Number.isInteger(rows) || rows < 1) {
+    throw new RangeError(`zeros: rows must be a positive integer, got ${rows}`);
+  }
+  // Validate cols is a positive integer
+  if (!Number.isInteger(cols) || cols < 1) {
+    throw new RangeError(`zeros: cols must be a positive integer, got ${cols}`);
+  }
   return Matrix.zeros(rows, cols);
 }
 
@@ -610,8 +840,12 @@ export function zeros(rows, cols) {
  * Create a vector from an array of components.
  * @param {Array<number|string|Decimal>} components - Vector components
  * @returns {Vector} New vector instance
+ * @throws {TypeError} If components is null or undefined
  */
 export function vec(components) {
+  if (components == null) {
+    throw new TypeError("vec: components cannot be null or undefined");
+  }
   return Vector.from(components);
 }
 
@@ -619,16 +853,40 @@ export function vec(components) {
  * Create a matrix from a 2D array.
  * @param {Array<Array<number|string|Decimal>>} data - 2D array of matrix elements
  * @returns {Matrix} New matrix instance
+ * @throws {TypeError} If data is null or undefined
  */
 export function mat(data) {
+  if (data == null) {
+    throw new TypeError("mat: data cannot be null or undefined");
+  }
   return Matrix.from(data);
 }
 
 /**
  * Set the global precision for all Decimal operations.
  * @param {number} precision - Number of significant digits (1 to 1e9)
+ * @throws {TypeError} If precision is not a finite number or not an integer
+ * @throws {RangeError} If precision is not between 1 and 1e9
  */
 export function setPrecision(precision) {
+  // Validate precision is a number
+  if (typeof precision !== "number" || !Number.isFinite(precision)) {
+    throw new TypeError(
+      `setPrecision: precision must be a finite number, got ${typeof precision}`,
+    );
+  }
+  // Validate precision is an integer
+  if (!Number.isInteger(precision)) {
+    throw new TypeError(
+      `setPrecision: precision must be an integer, got ${precision}`,
+    );
+  }
+  // Validate precision range (Decimal.js requirement: 1 to 1e9)
+  if (precision < 1 || precision > 1e9) {
+    throw new RangeError(
+      `setPrecision: precision must be between 1 and 1e9, got ${precision}`,
+    );
+  }
   Decimal.set({ precision });
 }