svg-path-commander 1.0.5 → 2.0.0-alpha2

package/src/process/{arcToCubic.js → arcToCubic.ts}

@@ -6,27 +6,42 @@ import rotateVector from '../math/rotateVector';
  * For more information of where this math came from visit:
  * http://www.w3.org/TR/SVG11/implnote.html#ArcImplementationNotes
  *
- * @param {number} X1 the starting x position
- * @param {number} Y1 the starting y position
- * @param {number} RX x-radius of the arc
- * @param {number} RY y-radius of the arc
- * @param {number} angle x-axis-rotation of the arc
- * @param {number} LAF large-arc-flag of the arc
- * @param {number} SF sweep-flag of the arc
- * @param {number} X2 the ending x position
- * @param {number} Y2 the ending y position
- * @param {number[]=} recursive the parameters needed to split arc into 2 segments
- * @return {number[]} the resulting cubic-bezier segment(s)
+ * @param X1 the starting x position
+ * @param Y1 the starting y position
+ * @param RX x-radius of the arc
+ * @param RY y-radius of the arc
+ * @param angle x-axis-rotation of the arc
+ * @param LAF large-arc-flag of the arc
+ * @param SF sweep-flag of the arc
+ * @param X2 the ending x position
+ * @param Y2 the ending y position
+ * @param recursive the parameters needed to split arc into 2 segments
+ * @return the resulting cubic-bezier segment(s)
  */
-export default function arcToCubic(X1, Y1, RX, RY, angle, LAF, SF, X2, Y2, recursive) {
-  let x1 = X1; let y1 = Y1; let rx = RX; let ry = RY; let x2 = X2; let y2 = Y2;
+const arcToCubic = (
+  X1: number,
+  Y1: number,
+  RX: number,
+  RY: number,
+  angle: number,
+  LAF: number,
+  SF: number,
+  X2: number,
+  Y2: number,
+  recursive?: [number, number, number, number],
+): number[] => {
+  let x1 = X1;
+  let y1 = Y1;
+  let rx = RX;
+  let ry = RY;
+  let x2 = X2;
+  let y2 = Y2;
   // for more information of where this Math came from visit:
   // http://www.w3.org/TR/SVG11/implnote.html#ArcImplementationNotes
   const d120 = (Math.PI * 120) / 180;
 
   const rad = (Math.PI / 180) * (+angle || 0);
-  /** @type {number[]} */
-  let res = [];
+  let res = [] as number[];
   let xy;
   let f1;
   let f2;
@@ -52,21 +67,21 @@ export default function arcToCubic(X1, Y1, RX, RY, angle, LAF, SF, X2, Y2, recur
     const rx2 = rx * rx;
     const ry2 = ry * ry;
 
-    const k = (LAF === SF ? -1 : 1)
-            * Math.sqrt(Math.abs((rx2 * ry2 - rx2 * y * y - ry2 * x * x)
-                / (rx2 * y * y + ry2 * x * x)));
+    const k =
+      (LAF === SF ? -1 : 1) *
+      Math.sqrt(Math.abs((rx2 * ry2 - rx2 * y * y - ry2 * x * x) / (rx2 * y * y + ry2 * x * x)));
 
-    cx = ((k * rx * y) / ry) + ((x1 + x2) / 2);
-    cy = ((k * -ry * x) / rx) + ((y1 + y2) / 2);
+    cx = (k * rx * y) / ry + (x1 + x2) / 2;
+    cy = (k * -ry * x) / rx + (y1 + y2) / 2;
     // eslint-disable-next-line no-bitwise -- Impossible to satisfy no-bitwise
-    f1 = Math.asin((((y1 - cy) / ry) * (10 ** 9) >> 0) / (10 ** 9));
+    f1 = Math.asin(((((y1 - cy) / ry) * 10 ** 9) >> 0) / 10 ** 9);
     // eslint-disable-next-line no-bitwise -- Impossible to satisfy no-bitwise
-    f2 = Math.asin((((y2 - cy) / ry) * (10 ** 9) >> 0) / (10 ** 9));
+    f2 = Math.asin(((((y2 - cy) / ry) * 10 ** 9) >> 0) / 10 ** 9);
 
     f1 = x1 < cx ? Math.PI - f1 : f1;
     f2 = x2 < cx ? Math.PI - f2 : f2;
-    if (f1 < 0) (f1 = Math.PI * 2 + f1);
-    if (f2 < 0) (f2 = Math.PI * 2 + f2);
+    if (f1 < 0) f1 = Math.PI * 2 + f1;
+    if (f2 < 0) f2 = Math.PI * 2 + f2;
     if (SF && f1 > f2) {
       f1 -= Math.PI * 2;
     }
@@ -106,9 +121,8 @@ export default function arcToCubic(X1, Y1, RX, RY, angle, LAF, SF, X2, Y2, recur
   res = [...m2, ...m3, ...m4, ...res];
   const newres = [];
   for (let i = 0, ii = res.length; i < ii; i += 1) {
-    newres[i] = i % 2
-      ? rotateVector(res[i - 1], res[i], rad).y
-      : rotateVector(res[i], res[i + 1], rad).x;
+    newres[i] = i % 2 ? rotateVector(res[i - 1], res[i], rad).y : rotateVector(res[i], res[i + 1], rad).x;
   }
   return newres;
-}
+};
+export default arcToCubic;

package/src/process/fixArc.ts

@@ -0,0 +1,23 @@
+import { CSegment, PathArray, PathCommand } from '../types';
+
+/**
+ * Splits an extended A (arc-to) segment into two cubic-bezier segments.
+ *
+ * @param path the `pathArray` this segment belongs to
+ * @param allPathCommands all previous path commands
+ * @param i the segment index
+ */
+const fixArc = (path: PathArray, allPathCommands: PathCommand[], i: number) => {
+  if (path[i].length > 7) {
+    path[i].shift();
+    const segment = path[i];
+    let ni = i; // ESLint
+    while (segment.length) {
+      // if created multiple C:s, their original seg is saved
+      allPathCommands[i] = 'A';
+      path.splice((ni += 1), 0, ['C', ...segment.splice(0, 6)] as CSegment);
+    }
+    path.splice(i, 1);
+  }
+};
+export default fixArc;

package/src/process/getSVGMatrix.ts

@@ -0,0 +1,70 @@
+import CSSMatrix from '@thednp/dommatrix';
+// import type { TransformObject } from '../interface';
+import type { TransformObjectValues } from '../types';
+
+/**
+ * Returns a transformation matrix to apply to `<path>` elements.
+ *
+ * @see TransformObjectValues
+ *
+ * @param transform the `transformObject`
+ * @returns a new transformation matrix
+ */
+const getSVGMatrix = (transform: TransformObjectValues): CSSMatrix => {
+  let matrix = new CSSMatrix();
+  const { origin } = transform;
+  const [originX, originY] = origin as [number, number, number];
+  const { translate } = transform;
+  const { rotate } = transform;
+  const { skew } = transform;
+  const { scale } = transform;
+
+  // set translate
+  if (
+    Array.isArray(translate) &&
+    translate.length >= 2 &&
+    translate.every(x => !Number.isNaN(+x)) &&
+    translate.some(x => x !== 0)
+  ) {
+    matrix = matrix.translate(...(translate as [number, number, number?]));
+  } else if (typeof translate === 'number' && !Number.isNaN(translate)) {
+    matrix = matrix.translate(translate);
+  }
+
+  if (rotate || skew || scale) {
+    // set SVG transform-origin, always defined
+    matrix = matrix.translate(originX, originY);
+
+    // set rotation
+    if (
+      Array.isArray(rotate) &&
+      rotate.length >= 2 &&
+      rotate.every(x => !Number.isNaN(+x)) &&
+      rotate.some(x => x !== 0)
+    ) {
+      matrix = matrix.rotate(...(rotate as [number, number, number?]));
+    } else if (typeof rotate === 'number' && !Number.isNaN(rotate)) {
+      matrix = matrix.rotate(rotate);
+    }
+
+    // set skew(s)
+    if (Array.isArray(skew) && skew.length === 2 && skew.every(x => !Number.isNaN(+x)) && skew.some(x => x !== 0)) {
+      matrix = skew[0] ? matrix.skewX(skew[0]) : matrix;
+      matrix = skew[1] ? matrix.skewY(skew[1]) : matrix;
+    } else if (typeof skew === 'number' && !Number.isNaN(skew)) {
+      matrix = matrix.skewX(skew);
+    }
+
+    // set scale
+    if (Array.isArray(scale) && scale.length >= 2 && scale.every(x => !Number.isNaN(+x)) && scale.some(x => x !== 1)) {
+      matrix = matrix.scale(...(scale as [number, number, number?]));
+    } else if (typeof scale === 'number' && !Number.isNaN(scale)) {
+      matrix = matrix.scale(scale);
+    }
+    // set SVG transform-origin
+    matrix = matrix.translate(-originX, -originY);
+  }
+
+  return matrix;
+};
+export default getSVGMatrix;

package/src/process/lineToCubic.ts

@@ -0,0 +1,17 @@
+import midPoint from '../math/midPoint';
+
+/**
+ * Converts an L (line-to) segment to C (cubic-bezier).
+ *
+ * @param x1 line start x
+ * @param y1 line start y
+ * @param x2 line end x
+ * @param y2 line end y
+ * @returns the cubic-bezier segment
+ */
+const lineToCubic = (x1: number, y1: number, x2: number, y2: number) => {
+  const t = 0.5;
+  const mid = midPoint([x1, y1], [x2, y2], t);
+  return [...mid, x2, y2, x2, y2];
+};
+export default lineToCubic;

package/src/process/{normalizePath.js → normalizePath.ts}

@@ -1,23 +1,22 @@
 import pathToAbsolute from '../convert/pathToAbsolute';
 import normalizeSegment from './normalizeSegment';
-import clonePath from './clonePath';
 import isNormalizedArray from '../util/isNormalizedArray';
 import paramsParser from '../parser/paramsParser';
+import type { NormalArray, PathArray } from '../types';
 
 /**
  * Normalizes a `path` object for further processing:
  * * convert segments to absolute values
  * * convert shorthand path commands to their non-shorthand notation
  *
- * @param {string | SVGPath.pathArray} pathInput the string to be parsed or 'pathArray'
- * @returns {SVGPath.normalArray} the normalized `pathArray`
+ * @param pathInput the string to be parsed or 'pathArray'
+ * @returns the normalized `pathArray`
  */
-export default function normalizePath(pathInput) {
+const normalizePath = (pathInput: string | PathArray): NormalArray => {
   if (isNormalizedArray(pathInput)) {
-    return clonePath(pathInput);
+    return [...pathInput];
   }
 
-  /** @type {SVGPath.normalArray} */
   const path = pathToAbsolute(pathInput);
   const params = { ...paramsParser };
   const allPathCommands = [];
@@ -36,9 +35,10 @@ export default function normalizePath(pathInput) {
 
     params.x1 = +segment[seglen - 2];
     params.y1 = +segment[seglen - 1];
-    params.x2 = +(segment[seglen - 4]) || params.x1;
-    params.y2 = +(segment[seglen - 3]) || params.y1;
+    params.x2 = +segment[seglen - 4] || params.x1;
+    params.y2 = +segment[seglen - 3] || params.y1;
   }
 
-  return path;
-}
+  return path as NormalArray;
+};
+export default normalizePath;

package/src/process/normalizeSegment.ts

@@ -0,0 +1,47 @@
+import type { ParserParams } from '../interface';
+import type { NormalSegment, PathSegment } from '../types';
+
+/**
+ * Normalizes a single segment of a `pathArray` object.
+ *
+ * @param segment the segment object
+ * @param params the coordinates of the previous segment
+ * @returns the normalized segment
+ */
+const normalizeSegment = (segment: PathSegment, params: ParserParams): NormalSegment => {
+  const [pathCommand] = segment;
+  const { x1: px1, y1: py1, x2: px2, y2: py2 } = params;
+  const values = segment.slice(1).map(Number);
+  let result = segment;
+
+  if (!'TQ'.includes(pathCommand)) {
+    // optional but good to be cautious
+    params.qx = null;
+    params.qy = null;
+  }
+
+  if (pathCommand === 'H') {
+    result = ['L', segment[1], py1];
+  } else if (pathCommand === 'V') {
+    result = ['L', px1, segment[1]];
+  } else if (pathCommand === 'S') {
+    const x1 = px1 * 2 - px2;
+    const y1 = py1 * 2 - py2;
+    params.x1 = x1;
+    params.y1 = y1;
+    result = ['C', x1, y1, ...(values as [number, number, number, number])];
+  } else if (pathCommand === 'T') {
+    const qx = px1 * 2 - (params.qx ? params.qx : /* istanbul ignore next */ 0);
+    const qy = py1 * 2 - (params.qy ? params.qy : /* istanbul ignore next */ 0);
+    params.qx = qx;
+    params.qy = qy;
+    result = ['Q', qx, qy, ...(values as [number, number])];
+  } else if (pathCommand === 'Q') {
+    const [nqx, nqy] = values as [number, number];
+    params.qx = nqx;
+    params.qy = nqy;
+  }
+
+  return result as NormalSegment;
+};
+export default normalizeSegment;

package/src/process/{optimizePath.js → optimizePath.ts}

@@ -4,28 +4,25 @@ import pathToRelative from '../convert/pathToRelative';
 import shortenSegment from './shortenSegment';
 import paramsParser from '../parser/paramsParser';
 import normalizePath from './normalizePath';
+import type { PathSegment, HSegment, PathArray, VSegment, PathCommand, AbsoluteSegment } from '../types';
 
 /**
  * Optimizes a `pathArray` object:
  * * convert segments to shorthand if possible
  * * select shortest segments from absolute and relative `pathArray`s
  *
- * TO DO
- * * implement `auto` for rounding values based on pathBBox
- * * also revers path check if it's smaller string, maybe?
- *
- * @param {SVGPath.pathArray} pathInput a string or `pathArray`
- * @param {number | 'off'} round the amount of decimals to round values to
- * @returns {SVGPath.pathArray} the optimized `pathArray`
+ * @param pathInput a string or `pathArray`
+ * @param round the amount of decimals to round values to
+ * @returns the optimized `pathArray`
  */
-export default function optimizePath(pathInput, round) {
+const optimizePath = (pathInput: PathArray, round: 'off' | number): PathArray => {
   const path = pathToAbsolute(pathInput);
   const normalPath = normalizePath(path);
   const params = { ...paramsParser };
-  const allPathCommands = [];
+  const allPathCommands = [] as PathCommand[];
   const ii = path.length;
-  let pathCommand = '';
-  let prevCommand = '';
+  let pathCommand = '' as PathCommand;
+  let prevCommand = '' as PathCommand;
   let x = 0;
   let y = 0;
   let mx = 0;
@@ -38,7 +35,7 @@ export default function optimizePath(pathInput, round) {
     allPathCommands[i] = pathCommand;
     // Get previous path command for `shortenSegment`
     if (i) prevCommand = allPathCommands[i - 1];
-    path[i] = shortenSegment(path[i], normalPath[i], params, prevCommand);
+    path[i] = shortenSegment(path[i], normalPath[i], params, prevCommand) as AbsoluteSegment;
 
     const segment = path[i];
     const seglen = segment.length;
@@ -46,8 +43,8 @@ export default function optimizePath(pathInput, round) {
     // update C, S, Q, T specific params
     params.x1 = +segment[seglen - 2];
     params.y1 = +segment[seglen - 1];
-    params.x2 = +(segment[seglen - 4]) || params.x1;
-    params.y2 = +(segment[seglen - 3]) || params.y1;
+    params.x2 = +segment[seglen - 4] || params.x1;
+    params.y2 = +segment[seglen - 3] || params.y1;
 
     // update x, y params
     switch (pathCommand) {
@@ -56,10 +53,10 @@ export default function optimizePath(pathInput, round) {
         y = my;
         break;
       case 'H':
-        [, x] = segment;
+        [, x] = segment as HSegment;
         break;
       case 'V':
-        [, y] = segment;
+        [, y] = segment as VSegment;
         break;
       default:
         [x, y] = segment.slice(-2).map(Number);
@@ -76,11 +73,11 @@ export default function optimizePath(pathInput, round) {
   const absolutePath = roundPath(path, round);
   const relativePath = roundPath(pathToRelative(path), round);
 
-  return absolutePath.map((a, i) => {
+  return absolutePath.map((a: PathSegment, i: number) => {
     if (i) {
-      return a.join('').length < relativePath[i].join('').length
-        ? a : relativePath[i];
+      return a.join('').length < relativePath[i].join('').length ? a : relativePath[i];
     }
     return a;
-  });
-}
+  }) as PathArray;
+};
+export default optimizePath;

package/src/process/{projection2d.js → projection2d.ts}

@@ -1,4 +1,4 @@
-import { Translate } from 'dommatrix/src/dommatrix';
+import CSSMatrix from '@thednp/dommatrix';
 
 /**
  * Transforms a specified point using a matrix, returning a new
@@ -7,18 +7,18 @@ import { Translate } from 'dommatrix/src/dommatrix';
  *
  * @copyright thednp © 2021
  *
- * @param {SVGPath.CSSMatrix} M CSSMatrix instance
- * @param {[number, number, number, number]} v Tuple
- * @return {[number, number, number, number]} the resulting Tuple
+ * @param cssm CSSMatrix instance
+ * @param v Tuple
+ * @return the resulting Tuple
  */
-function translatePoint(M, v) {
-  let m = Translate(...v);
+const translatePoint = (cssm: CSSMatrix, v: [number, number, number, number]): [number, number, number, number] => {
+  let m = CSSMatrix.Translate(...(v.slice(0, -1) as [number, number, number]));
 
-  [,,, m.m44] = v;
-  m = M.multiply(m);
+  [, , , m.m44] = v;
+  m = cssm.multiply(m);
 
   return [m.m41, m.m42, m.m43, m.m44];
-}
+};
 
 /**
  * Returns the [x,y] projected coordinates for a given an [x,y] point
@@ -29,12 +29,12 @@ function translatePoint(M, v) {
  * Details =>
  * https://stackoverflow.com/questions/23792505/predicted-rendering-of-css-3d-transformed-pixel
  *
- * @param {SVGPath.CSSMatrix} m the transformation matrix
- * @param {[number, number]} point2D the initial [x,y] coordinates
- * @param {number[]} origin the [x,y,z] transform origin
- * @returns {[number, number]} the projected [x,y] coordinates
+ * @param m the transformation matrix
+ * @param point2D the initial [x,y] coordinates
+ * @param origin the [x,y,z] transform origin
+ * @returns the projected [x,y] coordinates
  */
-export default function projection2d(m, point2D, origin) {
+const projection2d = (m: CSSMatrix, point2D: [number, number], origin: [number, number, number]): [number, number] => {
   const [originX, originY, originZ] = origin;
   const [x, y, z] = translatePoint(m, [...point2D, 0, 1]);
 
@@ -47,4 +47,5 @@ export default function projection2d(m, point2D, origin) {
     relativePositionX * (Math.abs(originZ) / Math.abs(relativePositionZ) || 1) + originX,
     relativePositionY * (Math.abs(originZ) / Math.abs(relativePositionZ) || 1) + originY,
   ];
-}
+};
+export default projection2d;

package/src/process/quadToCubic.ts

@@ -0,0 +1,31 @@
+/**
+ * Converts a Q (quadratic-bezier) segment to C (cubic-bezier).
+ *
+ * @param x1 curve start x
+ * @param y1 curve start y
+ * @param qx control point x
+ * @param qy control point y
+ * @param x2 curve end x
+ * @param y2 curve end y
+ * @returns the cubic-bezier segment
+ */
+const quadToCubic = (
+  x1: number,
+  y1: number,
+  qx: number,
+  qy: number,
+  x2: number,
+  y2: number,
+): [number, number, number, number, number, number] => {
+  const r13 = 1 / 3;
+  const r23 = 2 / 3;
+  return [
+    r13 * x1 + r23 * qx, // cpx1
+    r13 * y1 + r23 * qy, // cpy1
+    r13 * x2 + r23 * qx, // cpx2
+    r13 * y2 + r23 * qy, // cpy2
+    x2,
+    y2, // x,y
+  ];
+};
+export default quadToCubic;

package/src/process/reverseCurve.ts

@@ -0,0 +1,21 @@
+import type { CurveArray } from '../types';
+
+/**
+ * Reverses all segments of a `pathArray`
+ * which consists of only C (cubic-bezier) path commands.
+ *
+ * @param path the source `pathArray`
+ * @returns the reversed `pathArray`
+ */
+const reverseCurve = (path: CurveArray): CurveArray => {
+  const rotatedCurve = path
+    .slice(1)
+    .map((x, i, curveOnly) =>
+      !i ? [...path[0].slice(1), ...x.slice(1)] : [...curveOnly[i - 1].slice(-2), ...x.slice(1)],
+    )
+    .map(x => x.map((_, i) => x[x.length - i - 2 * (1 - (i % 2))]))
+    .reverse();
+
+  return [['M', ...rotatedCurve[0].slice(0, 2)], ...rotatedCurve.map(x => ['C', ...x.slice(2)])] as CurveArray;
+};
+export default reverseCurve;

package/src/process/reversePath.ts

@@ -0,0 +1,101 @@
+import type {
+  ASegment,
+  CSegment,
+  HSegment,
+  MSegment,
+  PathArray,
+  PathSegment,
+  QSegment,
+  SSegment,
+  TSegment,
+  VSegment,
+} from 'src/types';
+import pathToAbsolute from '../convert/pathToAbsolute';
+import normalizePath from './normalizePath';
+
+/**
+ * Reverses all segments of a `pathArray` and returns a new `pathArray` instance.
+ *
+ * @param pathInput the source `pathArray`
+ * @returns the reversed `pathArray`
+ */
+const reversePath = (pathInput: PathArray): PathArray => {
+  const absolutePath = pathToAbsolute(pathInput);
+  const isClosed = absolutePath.slice(-1)[0][0] === 'Z';
+
+  const reversedPath = normalizePath(absolutePath)
+    .map((segment, i) => {
+      const [x, y] = segment.slice(-2).map(Number);
+      return {
+        seg: absolutePath[i], // absolute
+        n: segment, // normalized
+        c: absolutePath[i][0], // pathCommand
+        x, // x
+        y, // y
+      };
+    })
+    .map((seg, i, path) => {
+      const segment = seg.seg;
+      const data = seg.n;
+      const prevSeg = i && path[i - 1];
+      const nextSeg = path[i + 1];
+      const pathCommand = seg.c;
+      const pLen = path.length;
+      const x = i ? path[i - 1].x : path[pLen - 1].x;
+      const y = i ? path[i - 1].y : path[pLen - 1].y;
+      let result = [];
+
+      switch (pathCommand) {
+        case 'M':
+          result = (isClosed ? ['Z'] : [pathCommand, x, y]) as PathSegment;
+          break;
+        case 'A':
+          result = [pathCommand, ...segment.slice(1, -3), segment[5] === 1 ? 0 : 1, x, y] as ASegment;
+          break;
+        case 'C':
+          if (nextSeg && nextSeg.c === 'S') {
+            result = ['S', segment[1], segment[2], x, y] as SSegment;
+          } else {
+            result = [pathCommand, segment[3], segment[4], segment[1], segment[2], x, y] as CSegment;
+          }
+          break;
+        case 'S':
+          if (prevSeg && 'CS'.includes(prevSeg.c) && (!nextSeg || nextSeg.c !== 'S')) {
+            result = ['C', data[3], data[4], data[1], data[2], x, y] as CSegment;
+          } else {
+            result = [pathCommand, data[1], data[2], x, y] as SSegment;
+          }
+          break;
+        case 'Q':
+          if (nextSeg && nextSeg.c === 'T') {
+            result = ['T', x, y] as TSegment;
+          } else {
+            result = [pathCommand, ...segment.slice(1, -2), x, y] as QSegment;
+          }
+          break;
+        case 'T':
+          if (prevSeg && 'QT'.includes(prevSeg.c) && (!nextSeg || nextSeg.c !== 'T')) {
+            result = ['Q', data[1], data[2], x, y] as QSegment;
+          } else {
+            result = [pathCommand, x, y] as TSegment;
+          }
+          break;
+        case 'Z':
+          result = ['M', x, y] as MSegment;
+          break;
+        case 'H':
+          result = [pathCommand, x] as HSegment;
+          break;
+        case 'V':
+          result = [pathCommand, y] as VSegment;
+          break;
+        default:
+          result = [pathCommand, ...segment.slice(1, -2), x, y] as PathSegment;
+      }
+
+      return result;
+    });
+
+  return (isClosed ? reversedPath.reverse() : [reversedPath[0], ...reversedPath.slice(1).reverse()]) as PathArray;
+};
+export default reversePath;

package/src/process/roundPath.ts

@@ -0,0 +1,29 @@
+import type { PathArray } from 'src/types';
+import defaultOptions from '../options/options';
+
+/**
+ * Rounds the values of a `pathArray` instance to
+ * a specified amount of decimals and returns it.
+ *
+ * @param path the source `pathArray`
+ * @param roundOption the amount of decimals to round numbers to
+ * @returns the resulted `pathArray` with rounded values
+ */
+const roundPath = (path: PathArray, roundOption?: number | 'off'): PathArray => {
+  let { round } = defaultOptions;
+  if (roundOption === 'off' || round === 'off') return [...path];
+  // allow for ZERO decimals
+  round = typeof roundOption === 'number' && roundOption >= 0 ? roundOption : round;
+  // to round values to the power
+  // the `round` value must be integer
+  const pow = typeof round === 'number' && round >= 1 ? 10 ** round : 1;
+
+  return path.map(pi => {
+    const values = pi
+      .slice(1)
+      .map(Number)
+      .map(n => (round ? Math.round(n * pow) / pow : Math.round(n)));
+    return [pi[0], ...values];
+  }) as PathArray;
+};
+export default roundPath;