feat: rework path parsing + allow external caching

Closes #25

Author: nikku

README.md

@@ -27,6 +27,25 @@ const intersection = intersect(path0, path1);
 Results are approximate, as we use [bezier clipping](https://math.stackexchange.com/questions/118937) to find intersections.
 
 
+## Path Caching
+
+Where performance matters, you can pre-parse paths and cache them:
+
+```javascript
+import intersect, { parsePath } from 'path-intersection';
+
+// parse paths once
+const path1 = parsePath('M0,0L100,100');
+const path2 = parsePath('M0,100L100,0');
+
+// they won't be re-parsed during intersection checking
+const result1 = intersect(path1, path2);
+const result2 = intersect(path2, path2);
+```
+
+For repeated calculations, this optimization can result in substantial performance improvements.
+
+
 ## Building the Project
 
 ```

intersect.d.ts

@@ -12,8 +12,13 @@
  * The path may be an SVG path string or a list of path components
  * such as `[ [ 'M', 0, 10 ], [ 'L', 20, 0 ] ]`.
  *
+ * For performance optimization, pre-parsed paths can be passed directly,
+ * the utility `parsePath` can be used to pre-parse any path.
+ *
  * @example
  *
+ * import findPathIntersections from 'path-intersection';
+ *
  * var intersections = findPathIntersections(
  *   'M0,0L100,100',
  *   [ [ 'M', 0, 100 ], [ 'L', 100, 0 ] ]
@@ -36,6 +41,34 @@ declare function findPathIntersections(path1: Path, path2: Path, justCount?: boo
 
 export default findPathIntersections;
 
+/**
+ * Parses and optimizes a path for use with intersection calculations.
+ *
+ * Takes an SVG path string or component array and converts it to an optimized
+ * internal format. The result can be cached and reused for maximum
+ * performance in intersection calculations.
+ *
+ * This is the recommended way to pre-parse paths for repeated use.
+ * Paths parsed this way will not be re-parsed when passed to `intersect()`.
+ *
+ * @example
+ *
+ * import intersect, { parsePath } from 'path-intersection';
+ *
+ * // parse once
+ * const path1 = parsePath('M0,0L100,100');
+ * const path2 = parsePath('M0,100L100,0');
+ *
+ * // cache and reuse
+ * const result1 = intersect(path1, parsedPath2);
+ * const result2 = intersect(path2, parsedPath2);
+ *
+ * @param {Path} path - the path to parse
+ *
+ * @return {PathComponent[]} pre-parsed and optimized path
+ */
+export function parsePath(path: Path): PathComponent[];
+
 /**
  * A string in the form of 'M150,150m0,-18a18,18,0,1,1,0,36a18,18,0,1,1,0,-36z'
  * or something like:

intersect.js

@@ -75,71 +75,61 @@ function parsePathString(pathString) {
     return null;
   }
 
-  var pth = paths(pathString);
+  var paramCounts = { a: 7, c: 6, h: 1, l: 2, m: 2, q: 4, s: 4, t: 2, v: 1, z: 0 },
+      pathComponents = [];
 
-  if (pth.arr) {
-    return clone(pth.arr);
-  }
+  String(pathString).replace(pathCommand, function(a, b, c) {
+    var params = [],
+        name = b.toLowerCase();
 
-  var paramCounts = { a: 7, c: 6, h: 1, l: 2, m: 2, q: 4, s: 4, t: 2, v: 1, z: 0 },
-      data = [];
+    c.replace(pathValues, function(a, b) {
+      b && params.push(+b);
+    });
 
-  if (isArray(pathString) && isArray(pathString[0])) { // rough assumption
-    data = clone(pathString);
-  }
+    if (name == 'm' && params.length > 2) {
+      pathComponents.push([ b, ...params.splice(0, 2) ]);
+      name = 'l';
+      b = b == 'm' ? 'l' : 'L';
+    }
 
-  if (!data.length) {
+    while (params.length >= paramCounts[name]) {
+      pathComponents.push([ b, ...params.splice(0, paramCounts[name]) ]);
+      if (!paramCounts[name]) {
+        break;
+      }
+    }
+  });
 
-    String(pathString).replace(pathCommand, function(a, b, c) {
-      var params = [],
-          name = b.toLowerCase();
+  pathComponents.toString = pathToString;
 
-      c.replace(pathValues, function(a, b) {
-        b && params.push(+b);
-      });
+  return pathComponents;
+}
 
-      if (name == 'm' && params.length > 2) {
-        data.push([ b, ...params.splice(0, 2) ]);
-        name = 'l';
-        b = b == 'm' ? 'l' : 'L';
-      }
+function isPathAbsolute(pathComponents) {
 
-      while (params.length >= paramCounts[name]) {
-        data.push([ b, ...params.splice(0, paramCounts[name]) ]);
-        if (!paramCounts[name]) {
-          break;
-        }
-      }
-    });
+  for (var i = 0; i < pathComponents.length; i++) {
+    var command = pathComponents[i][0];
+    if (typeof command === 'string' && command !== command.toUpperCase()) {
+      return false;
+    }
   }
 
-  data.toString = paths.toString;
-  pth.arr = clone(data);
-
-  return data;
+  return true;
 }
 
-function paths(ps) {
-  var p = paths.ps = paths.ps || {};
-
-  if (p[ps]) {
-    p[ps].sleep = 100;
-  } else {
-    p[ps] = {
-      sleep: 100
-    };
+function isPathCurve(pathArray) {
+  if (!isArray(pathArray) || !pathArray.length) {
+    return false;
   }
 
-  setTimeout(function() {
-    for (var key in p) {
-      if (hasProperty(p, key) && key != ps) {
-        p[key].sleep--;
-        !p[key].sleep && delete p[key];
-      }
+  for (var i = 0; i < pathArray.length; i++) {
+    var command = pathArray[i][0];
+    if (command !== 'M' && command !== 'C') {
+      return false;
     }
-  });
+  }
 
-  return p[ps];
+  return true;
 }
 
 function rectBBox(x, y, width, height) {
@@ -471,20 +461,14 @@ export default function findPathIntersections(path1, path2, justCount) {
   return res;
 }
 
+function isPathComponents(path) {
+  return isArray(path) && isArray(path[0]);
+}
 
 function pathToAbsolute(pathArray) {
-  var pth = paths(pathArray);
 
-  if (pth.abs) {
-    return pathClone(pth.abs);
-  }
-
-  if (!isArray(pathArray) || !isArray(pathArray && pathArray[0])) { // rough assumption
-    pathArray = parsePathString(pathArray);
-  }
-
-  if (!pathArray || !pathArray.length) {
-    return [ [ 'M', 0, 0 ] ];
+  if (isPathAbsolute(pathArray)) {
+    return pathArray;
   }
 
   var res = [],
@@ -564,7 +548,6 @@ function pathToAbsolute(pathArray) {
   }
 
   res.toString = pathToString;
-  pth.abs = pathClone(res);
 
   return res;
 }
@@ -787,14 +770,15 @@ function curveBBox(x0, y0, x1, y1, x2, y2, x3, y3) {
 
 function pathToCurve(path) {
 
-  var pth = paths(path);
+  if (!isPathComponents(path)) {
+    path = parsePathString(path);
+  }
 
-  // return cached curve, if existing
-  if (pth.curve) {
-    return pathClone(pth.curve);
+  if (isPathCurve(path)) {
+    return path;
   }
 
-  var curvedPath = pathToAbsolute(path),
+  var curvedPath = pathClone(pathToAbsolute(path)),
       attrs = { x: 0, y: 0, bx: 0, by: 0, X: 0, Y: 0, qx: null, qy: null },
       processPath = function(path, d, pathCommand) {
         var nx, ny;
@@ -918,8 +902,35 @@ function pathToCurve(path) {
     attrs.by = toFloat(seg[seglen - 3]) || attrs.y;
   }
 
-  // cache curve
-  pth.curve = pathClone(curvedPath);
-
   return curvedPath;
+}
+
+/**
+ * Parses and optimizes a path for use with intersection calculations.
+ *
+ * Takes an SVG path string or component array and converts it to an optimized
+ * internal format. The result can be cached and reused for maximum
+ * performance in intersection calculations.
+ *
+ * This is the recommended way to pre-parse paths for repeated use.
+ * Paths parsed this way will not be re-parsed when passed to `intersect()`.
+ *
+ * @example
+ *
+ * import intersect, { parsePath } from 'path-intersection';
+ *
+ * // parse once
+ * const path1 = parsePath('M0,0L100,100');
+ * const path2 = parsePath('M0,100L100,0');
+ *
+ * // cache and reuse
+ * const result1 = intersect(path1, parsedPath2);
+ * const result2 = intersect(path2, parsedPath2);
+ *
+ * @param {Path} path - the path to parse
+ *
+ * @return {PathComponent[]} pre-parsed and optimized path
+ */
+export function parsePath(path) {
+  return pathToCurve(path);
 }