Remove internal caching and expose parsePath utility for performance optimization

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

@@ -9,11 +9,16 @@
  * on each path (segment1, segment2) and the relative location of the
  * intersection on these segments (t1, t2).
  *
- * The path may be an SVG path string or a list of path components
+ * The path may be an SVG path string or an array of path components
  * such as `[ [ 'M', 0, 10 ], [ 'L', 20, 0 ] ]`.
  *
+ * For performance optimization, pre-parsed paths can be passed directly,
+ * {@link parsePath | the parsePath utility} 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 ] ]
@@ -23,11 +28,11 @@
  * //   { x: 50, y: 50, segment1: 1, segment2: 1, t1: 0.5, t2: 0.5 }
  * // ];
  *
- * @param {String|Array<PathComponent>} path1
- * @param {String|Array<PathComponent>} path2
- * @param {Boolean} [justCount=false]
+ * @param {Path} path1
+ * @param {Path} path2
+ * @param {boolean} [justCount=false]
  *
- * @return {Array<Intersection>|Number}
+ * @return {Intersection[]|number}
  */
 declare function findPathIntersections(path1: Path, path2: Path, justCount: true): number;
 declare function findPathIntersections(path1: Path, path2: Path, justCount: false): Intersection[];
@@ -37,18 +42,57 @@ declare function findPathIntersections(path1: Path, path2: Path, justCount?: boo
 export default findPathIntersections;
 
 /**
- * A string in the form of 'M150,150m0,-18a18,18,0,1,1,0,36a18,18,0,1,1,0,-36z'
- * or something like:
+ * Parses a path to an optimized format. The result can be cached
+ * and reused to maximize performance in subsequent 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
+ * {@link findPathIntersections | the intersect function}.
+ *
+ * @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 SVG path string, or it's array encoded version.
+ *
+ * @example
+ *
+ * "M150,150m0,-18a18,18,0,1,1,0,36a18,18,0,1,1,0,-36z"
+ *
+ * @example
+ *
  * [
- *  ['M', 1, 2],
- *  ['m', 0, -2],
- *  ['a', 1, 1, 0, 1, 1, 0, 2 * 1],
- *  ['a', 1, 1, 0, 1, 1, 0, -2 * 1],
- *  ['z']
+ *   ['M', 1, 2],
+ *   ['m', 0, -2],
+ *   ['a', 1, 1, 0, 1, 1, 0, 2 * 1],
+ *   ['a', 1, 1, 0, 1, 1, 0, -2 * 1],
+ *   ['z']
  * ]
  */
 declare type Path = string | PathComponent[];
-declare type PathComponent = any[];
+/**
+ * A SVG path component, stored as an array with the operation, and parameters.
+ * 
+ * @example
+ *
+ * ['M', 1, 2]
+ */
+declare type PathComponent = [ string, ...number[] ];
 
 declare interface Intersection {
   /**