@khanacademy/kmath 1.0.0 → 2.0.0

package/dist/index.js

@@ -1,21 +1,44 @@
-import { addLibraryVersionToPerseusDebug } from '@khanacademy/perseus-utils';
-import _ from 'underscore';
-import { approximateEqual, approximateDeepEqual } from '@khanacademy/perseus-core';
-import $ from 'jquery';
+'use strict';
+
+Object.defineProperty(exports, '__esModule', { value: true });
+
+var perseusUtils = require('@khanacademy/perseus-utils');
+var _ = require('underscore');
+var perseusCore = require('@khanacademy/perseus-core');
+var $ = require('jquery');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e : { default: e }; }
+
+var ___default = /*#__PURE__*/_interopDefaultCompat(_);
+var $__default = /*#__PURE__*/_interopDefaultCompat($);
+
+// This file is processed by a Rollup plugin (replace) to inject the production
+// version number during the release build.
+// In dev, you'll never see the version number.
 
 const libName = "@khanacademy/kmath";
-const libVersion = "1.0.0";
-addLibraryVersionToPerseusDebug(libName, libVersion);
+const libVersion = "2.0.0";
+perseusUtils.addLibraryVersionToPerseusDebug(libName, libVersion);
+
+/**
+ * Number Utils
+ * A number is a js-number, e.g. 5.12
+ */
 
 const DEFAULT_TOLERANCE = 1e-9;
+
+// TODO: Should this just be Number.Epsilon
 const EPSILON = Math.pow(2, -42);
 function is$2(x) {
-  return _.isNumber(x) && !_.isNaN(x);
+  return ___default.default.isNumber(x) && !___default.default.isNaN(x);
 }
 function equal$4(x, y, tolerance) {
+  // Checking for undefined makes this function behave nicely
+  // with vectors of different lengths that are _.zip'd together
   if (x == null || y == null) {
     return x === y;
   }
+  // We check === here so that +/-Infinity comparisons work correctly
   if (x === y) {
     return true;
   }
@@ -24,16 +47,21 @@ function equal$4(x, y, tolerance) {
   }
   return Math.abs(x - y) < tolerance;
 }
-function sign$1(x, tolerance) {
+function sign$1(x, tolerance) /* Should be: 0 | 1 | -1 */{
   return equal$4(x, 0, tolerance) ? 0 : Math.abs(x) / x;
 }
 function isInteger(num, tolerance) {
   return equal$4(Math.round(num), num, tolerance);
 }
+
+// Round a number to a certain number of decimal places
 function round$2(num, precision) {
   const factor = Math.pow(10, precision);
   return Math.round(num * factor) / factor;
 }
+
+// Round num to the nearest multiple of increment
+// i.e. roundTo(83, 5) -> 85
 function roundTo$2(num, increment) {
   return Math.round(num / increment) * increment;
 }
@@ -43,7 +71,26 @@ function floorTo$2(num, increment) {
 function ceilTo$2(num, increment) {
   return Math.ceil(num / increment) * increment;
 }
-function toFraction(decimal, tolerance = EPSILON, maxDenominator = 1000) {
+
+/**
+ * toFraction
+ *
+ * Returns a [numerator, denominator] array rational representation
+ * of `decimal`
+ *
+ * See http://en.wikipedia.org/wiki/Continued_fraction for implementation
+ * details
+ *
+ * toFraction(4/8) => [1, 2]
+ * toFraction(0.66) => [33, 50]
+ * toFraction(0.66, 0.01) => [2/3]
+ * toFraction(283 + 1/3) => [850, 3]
+ */
+function toFraction(decimal) {
+  let tolerance = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : EPSILON;
+  let maxDenominator = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : 1000;
+  // Initialize everything to compute successive terms of
+  // continued-fraction approximations via recurrence relation
   let n = [1, 0];
   let d = [0, 1];
   let a = Math.floor(decimal);
@@ -57,6 +104,9 @@ function toFraction(decimal, tolerance = EPSILON, maxDenominator = 1000) {
     a = Math.floor(1 / rem);
     rem = 1 / rem - a;
   }
+
+  // We failed to find a nice rational representation,
+  // so return an irrational "fraction"
   return [decimal, 1];
 }
 
@@ -75,13 +125,21 @@ var number = /*#__PURE__*/Object.freeze({
     toFraction: toFraction
 });
 
+/**
+ * Vector Utils
+ * A vector is an array of numbers e.g. [0, 3, 4].
+ */
+
 function arraySum(array) {
   return array.reduce((memo, arg) => memo + arg, 0);
 }
 function arrayProduct(array) {
   return array.reduce((memo, arg) => memo * arg, 1);
 }
-function zip(...arrays) {
+function zip() {
+  for (var _len = arguments.length, arrays = new Array(_len), _key = 0; _key < _len; _key++) {
+    arrays[_key] = arguments[_key];
+  }
   const n = Math.min(...arrays.map(a => a.length));
   const results = [];
   for (let i = 0; i < n; i++) {
@@ -92,6 +150,16 @@ function zip(...arrays) {
 function map(pair, f) {
   return [f(pair[0], 0), f(pair[1], 1)];
 }
+
+/**
+ * Checks if the given vector contains only numbers and, optionally, is of the
+ * right dimension (length).
+ *
+ * is([1, 2, 3]) -> true
+ * is([1, "Hello", 3]) -> false
+ * is([1, 2, 3], 1) -> false
+ */
+
 function is$1(vec, dimension) {
   if (!Array.isArray(vec)) {
     return false;
@@ -101,30 +169,46 @@ function is$1(vec, dimension) {
   }
   return vec.every(is$2);
 }
+
+// Normalize to a unit vector
 function normalize(v) {
   return scale(v, 1 / length(v));
 }
+
+// Length/magnitude of a vector
 function length(v) {
   return Math.sqrt(dot(v, v));
 }
+// Dot product of two vectors
 function dot(a, b) {
   const zipped = zip(a, b);
   const multiplied = zipped.map(arrayProduct);
   return arraySum(multiplied);
 }
-function add$1(...vecs) {
-  const zipped = zip(...vecs);
+
+/* vector-add multiple [x, y] coords/vectors
+ *
+ * add([1, 2], [3, 4]) -> [4, 6]
+ */
+function add$1() {
+  const zipped = zip(...arguments);
+  // @ts-expect-error - TS2322 - Type 'number[]' is not assignable to type 'V'.
   return zipped.map(arraySum);
 }
 function subtract(v1, v2) {
+  // @ts-expect-error - TS2322 - Type 'number[]' is not assignable to type 'V'.
   return zip(v1, v2).map(dim => dim[0] - dim[1]);
 }
 function negate(v) {
+  // @ts-expect-error - TS2322 - Type 'number[]' is not assignable to type 'V'.
   return v.map(x => {
     return -x;
   });
 }
+
+// Scale a vector
 function scale(v1, scalar) {
+  // @ts-expect-error - TS2322 - Type 'number[]' is not assignable to type 'V'.
   return v1.map(x => {
     return x * scalar;
   });
@@ -133,6 +217,9 @@ function equal$3(v1, v2, tolerance) {
   return v1.length === v2.length && zip(v1, v2).every(pair => equal$4(pair[0], pair[1], tolerance));
 }
 function codirectional(v1, v2, tolerance) {
+  // The origin is trivially codirectional with all other vectors.
+  // This gives nice semantics for codirectionality between points when
+  // comparing their difference vectors.
   if (equal$4(length(v1), 0, tolerance) || equal$4(length(v2), 0, tolerance)) {
     return true;
   }
@@ -143,24 +230,48 @@ function codirectional(v1, v2, tolerance) {
 function collinear$1(v1, v2, tolerance) {
   return codirectional(v1, v2, tolerance) || codirectional(v1, negate(v2), tolerance);
 }
+
+// TODO(jeremy) These coordinate conversion functions really only handle 2D points (ie. [number, number])
+
+// Convert a cartesian coordinate into a radian polar coordinate
 function polarRadFromCart$1(v) {
   const radius = length(v);
   let theta = Math.atan2(v[1], v[0]);
+
+  // Convert angle range from [-pi, pi] to [0, 2pi]
   if (theta < 0) {
     theta += 2 * Math.PI;
   }
   return [radius, theta];
 }
-function polarDegFromCart$1(v) {
+
+// Converts a cartesian coordinate into a degree polar coordinate
+function polarDegFromCart$1(v) /* TODO: convert to tuple/Point */{
   const polar = polarRadFromCart$1(v);
   return [polar[0], polar[1] * 180 / Math.PI];
 }
-function cartFromPolarRad$1(radius, theta = 0) {
+
+/* Convert a polar coordinate into a cartesian coordinate
+ *
+ * Examples:
+ * cartFromPolarRad(5, Math.PI)
+ */
+function cartFromPolarRad$1(radius) /* TODO: convert to tuple/Point */{
+  let theta = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
   return [radius * Math.cos(theta), radius * Math.sin(theta)];
 }
-function cartFromPolarDeg$1(radius, theta = 0) {
+
+/* Convert a polar coordinate into a cartesian coordinate
+ *
+ * Examples:
+ * cartFromPolarDeg(5, 30)
+ */
+function cartFromPolarDeg$1(radius) {
+  let theta = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : 0;
   return cartFromPolarRad$1(radius, theta * Math.PI / 180);
 }
+
+// Rotate vector
 function rotateRad$1(v, theta) {
   const polar = polarRadFromCart$1(v);
   const angle = polar[1] + theta;
@@ -171,26 +282,39 @@ function rotateDeg$1(v, theta) {
   const angle = polar[1] + theta;
   return cartFromPolarDeg$1(polar[0], angle);
 }
+
+// Angle between two vectors
 function angleRad(v1, v2) {
   return Math.acos(dot(v1, v2) / (length(v1) * length(v2)));
 }
 function angleDeg(v1, v2) {
   return angleRad(v1, v2) * 180 / Math.PI;
 }
+
+// Vector projection of v1 onto v2
 function projection(v1, v2) {
   const scalar = dot(v1, v2) / dot(v2, v2);
   return scale(v2, scalar);
 }
+
+// Round each number to a certain number of decimal places
 function round$1(vec, precision) {
+  // @ts-expect-error - TS2322 - Type 'number[]' is not assignable to type 'V'.
   return vec.map((elem, i) => round$2(elem, precision[i] || precision));
 }
+
+// Round each number to the nearest increment
+
 function roundTo$1(vec, increment) {
+  // @ts-expect-error - TS2322 - Type 'number[]' is not assignable to type 'V'.
   return vec.map((elem, i) => roundTo$2(elem, increment[i] || increment));
 }
 function floorTo$1(vec, increment) {
+  // @ts-expect-error - TS2322 - Type 'number[]' is not assignable to type 'V'.
   return vec.map((elem, i) => floorTo$2(elem, increment[i] || increment));
 }
 function ceilTo$1(vec, increment) {
+  // @ts-expect-error - TS2322 - Type 'number[]' is not assignable to type 'V'.
   return vec.map((elem, i) => ceilTo$2(elem, increment[i] || increment));
 }
 
@@ -224,6 +348,15 @@ var vector$1 = /*#__PURE__*/Object.freeze({
     zip: zip
 });
 
+/**
+ * Point Utils
+ * A point is an array of two numbers e.g. [0, 0].
+ */
+
+
+// A point, in 2D, 3D, or nD space.
+
+// Rotate point (around origin unless a center is specified)
 function rotateRad(point, theta, center) {
   if (center === undefined) {
     return rotateRad$1(point, theta);
@@ -238,9 +371,13 @@ function rotateDeg(point, theta, center) {
     return add$1(center, rotateDeg$1(subtract(point, center), theta));
   }
 }
+
+// Distance between two points
 function distanceToPoint$1(point1, point2) {
   return length(subtract(point1, point2));
 }
+
+// Distance between point and line
 function distanceToLine(point, line) {
   const lv = subtract(line[1], line[0]);
   const pv = subtract(point, line[0]);
@@ -248,6 +385,8 @@ function distanceToLine(point, line) {
   const distancePv = subtract(projectedPv, pv);
   return length(distancePv);
 }
+
+// Reflect point over line
 function reflectOverLine(point, line) {
   const lv = subtract(line[1], line[0]);
   const pv = subtract(point, line[0]);
@@ -255,7 +394,17 @@ function reflectOverLine(point, line) {
   const reflectedPv = subtract(scale(projectedPv, 2), pv);
   return add$1(line[0], reflectedPv);
 }
-function compare(point1, point2, equalityTolerance) {
+
+/**
+ * Compares two points, returning -1, 0, or 1, for use with
+ * Array.prototype.sort
+ *
+ * Note: This technically doesn't satisfy the total-ordering
+ * requirements of Array.prototype.sort unless equalityTolerance
+ * is 0. In some cases very close points that compare within a
+ * few equalityTolerances could appear in the wrong order.
+ */
+function compare(point1, point2, equalityTolerance) /* TODO: convert to -1 | 0 | 1 type */{
   if (point1.length !== point2.length) {
     return point1.length - point2.length;
   }
@@ -266,15 +415,23 @@ function compare(point1, point2, equalityTolerance) {
   }
   return 0;
 }
+
+// Check if a value is a point
 const is = is$1;
+
+// Add and subtract vector(s)
 const addVector = add$1;
 const addVectors = add$1;
 const subtractVector = subtract;
 const equal$2 = equal$3;
+
+// Convert from cartesian to polar and back
 const polarRadFromCart = polarRadFromCart$1;
 const polarDegFromCart = polarDegFromCart$1;
 const cartFromPolarRad = cartFromPolarRad$1;
 const cartFromPolarDeg = cartFromPolarDeg$1;
+
+// Rounding
 const round = round$1;
 const roundTo = roundTo$1;
 const floorTo = floorTo$1;
@@ -303,6 +460,11 @@ var point = /*#__PURE__*/Object.freeze({
     subtractVector: subtractVector
 });
 
+/**
+ * Line Utils
+ * A line is an array of two points e.g. [[-5, 0], [5, 0]].
+ */
+
 function distanceToPoint(line, point$1) {
   return distanceToLine(point$1, line);
 }
@@ -313,14 +475,20 @@ function midpoint(line) {
   return [(line[0][0] + line[1][0]) / 2, (line[0][1] + line[1][1]) / 2];
 }
 function equal$1(line1, line2, tolerance) {
+  // TODO: A nicer implementation might just check collinearity of
+  // vectors using underscore magick
+  // Compare the directions of the lines
   const v1 = subtract(line1[1], line1[0]);
   const v2 = subtract(line2[1], line2[0]);
   if (!collinear$1(v1, v2, tolerance)) {
     return false;
   }
+  // If the start point is the same for the two lines, then they are the same
   if (equal$2(line1[0], line2[0])) {
     return true;
   }
+  // Make sure that the direction to get from line1 to
+  // line2 is the same as the direction of the lines
   const line1ToLine2Vector = subtract(line2[0], line1[0]);
   return collinear$1(v1, line1ToLine2Vector, tolerance);
 }
@@ -333,7 +501,15 @@ var line = /*#__PURE__*/Object.freeze({
     reflectPoint: reflectPoint
 });
 
+/**
+ * Ray Utils
+ * A ray (→) is an array of an endpoint and another point along the ray.
+ * For example, [[0, 0], [1, 0]] is the ray starting at the origin and
+ * traveling along the positive x-axis.
+ */
+
 function equal(ray1, ray2, tolerance) {
+  // Compare the directions of the rays
   const v1 = subtract(ray1[1], ray1[0]);
   const v2 = subtract(ray2[1], ray2[0]);
   const sameOrigin = equal$2(ray1[0], ray2[0]);
@@ -347,9 +523,11 @@ var ray = /*#__PURE__*/Object.freeze({
 });
 
 const KhanMath = {
+  // Simplify formulas before display
   cleanMath: function (expr) {
     return typeof expr === "string" ? expr.replace(/\+\s*-/g, "- ").replace(/-\s*-/g, "+ ").replace(/\^1/g, "") : expr;
   },
+  // Bound a number by 1e-6 and 1e20 to avoid exponents after toString
   bound: function (num) {
     if (num === 0) {
       return num;
@@ -367,12 +545,17 @@ const KhanMath = {
   },
   getGCD: function (a, b) {
     if (arguments.length > 2) {
+      // TODO(kevinb): rewrite using rest args instead of arguments
+      // eslint-disable-next-line prefer-rest-params
       const rest = [].slice.call(arguments, 1);
+      // @ts-expect-error - TS2556 - A spread argument must either have a tuple type or be passed to a rest parameter.
       return KhanMath.getGCD(a, KhanMath.getGCD(...rest));
     }
     let mod;
     a = Math.abs(a);
     b = Math.abs(b);
+
+    // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
     while (b) {
       mod = a % b;
       a = b;
@@ -382,7 +565,10 @@ const KhanMath = {
   },
   getLCM: function (a, b) {
     if (arguments.length > 2) {
+      // TODO(kevinb): rewrite using rest args instead of arguments
+      // eslint-disable-next-line prefer-rest-params
       const rest = [].slice.call(arguments, 1);
+      // @ts-expect-error - TS2556 - A spread argument must either have a tuple type or be passed to a rest parameter.
       return KhanMath.getLCM(a, KhanMath.getLCM(...rest));
     }
     return Math.abs(a * b) / KhanMath.getGCD(a, b);
@@ -393,7 +579,8 @@ const KhanMath = {
       return false;
     }
     if (n < 101) {
-      return !!$.grep(KhanMath.primes, function (p, i) {
+      // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+      return !!$__default.default.grep(KhanMath.primes, function (p, i) {
         return Math.abs(p - n) <= 0.5;
       }).length;
     }
@@ -407,6 +594,7 @@ const KhanMath = {
     }
     return true;
   },
+  // @ts-expect-error - TS2366 - Function lacks ending return statement and return type does not include 'undefined'.
   getPrimeFactorization: function (number) {
     if (number === 1) {
       return [];
@@ -417,24 +605,39 @@ const KhanMath = {
     const maxf = Math.sqrt(number);
     for (let f = 2; f <= maxf; f++) {
       if (number % f === 0) {
-        return $.merge(KhanMath.getPrimeFactorization(f), KhanMath.getPrimeFactorization(number / f));
+        return $__default.default.merge(KhanMath.getPrimeFactorization(f), KhanMath.getPrimeFactorization(number / f));
       }
     }
   },
+  // Round a number to the nearest increment
+  // E.g., if increment = 30 and num = 40, return 30. if increment = 30 and
+  //     num = 45, return 60.
   roundToNearest: function (increment, num) {
     return Math.round(num / increment) * increment;
   },
+  // Round a number to a certain number of decimal places
   roundTo: function (precision, num) {
     const factor = Math.pow(10, precision).toFixed(5);
+    // @ts-expect-error - TS2345 - Argument of type 'string' is not assignable to parameter of type 'number'. | TS2363 - The right-hand side of an arithmetic operation must be of type 'any', 'number', 'bigint' or an enum type. | TS2363 - The right-hand side of an arithmetic operation must be of type 'any', 'number', 'bigint' or an enum type.
     return Math.round((num * factor).toFixed(5)) / factor;
   },
+  /**
+   * Return a string of num rounded to a fixed precision decimal places,
+   * with an approx symbol if num had to be rounded, and trailing 0s
+   */
   toFixedApprox: function (num, precision) {
+    // TODO(aria): Make this locale-dependent
     const fixedStr = num.toFixed(precision);
     if (equal$4(+fixedStr, num)) {
       return fixedStr;
     }
     return "\\approx " + fixedStr;
   },
+  /**
+   * Return a string of num rounded to precision decimal places, with an
+   * approx symbol if num had to be rounded, but no trailing 0s if it was
+   * not rounded.
+   */
   roundToApprox: function (num, precision) {
     const fixed = KhanMath.roundTo(precision, num);
     if (equal$4(fixed, num)) {
@@ -442,6 +645,11 @@ const KhanMath = {
     }
     return KhanMath.toFixedApprox(num, precision);
   },
+  // toFraction(4/8) => [1, 2]
+  // toFraction(0.666) => [333, 500]
+  // toFraction(0.666, 0.001) => [2, 3]
+  //
+  // tolerance can't be bigger than 1, sorry
   toFraction: function (decimal, tolerance) {
     if (tolerance == null) {
       tolerance = Math.pow(2, -46);
@@ -462,6 +670,8 @@ const KhanMath = {
     let hiD = 1;
     let midN = 1;
     let midD = 2;
+
+    // eslint-disable-next-line no-constant-condition
     while (true) {
       if (Math.abs(Number(midN / midD) - decimal) <= tolerance) {
         return [midN, midD];
@@ -477,8 +687,11 @@ const KhanMath = {
       midD = loD + hiD;
     }
   },
+  // Returns the format (string) of a given numeric string
+  // Note: purposively more inclusive than answer-types' predicate.forms
+  // That is, it is not necessarily true that interpreted input are numeric
   getNumericFormat: function (text) {
-    text = $.trim(text);
+    text = $__default.default.trim(text);
     text = text.replace(/\u2212/, "-").replace(/([+-])\s+/g, "$1");
     if (text.match(/^[+-]?\d+$/)) {
       return "integer";
@@ -498,12 +711,13 @@ const KhanMath = {
     }
     return null;
   },
+  // Returns a string of the number in a specified format
   toNumericString: function (number$1, format) {
     if (number$1 == null) {
       return "";
     }
     if (number$1 === 0) {
-      return "0";
+      return "0"; // otherwise it might end up as 0% or 0pi
     }
     if (format === "percent") {
       return number$1 * 100 + "%";
@@ -518,21 +732,25 @@ const KhanMath = {
         return sign + (numerator === 1 ? "" : numerator) + pi + (denominator === 1 ? "" : "/" + denominator);
       }
     }
-    if (_(["proper", "improper", "mixed", "fraction"]).contains(format)) {
+    if (___default.default(["proper", "improper", "mixed", "fraction"]).contains(format)) {
       const fraction = toFraction(number$1);
       const numerator = Math.abs(fraction[0]);
       const denominator = fraction[1];
       const sign = number$1 < 0 ? "-" : "";
       if (denominator === 1) {
-        return sign + numerator;
+        return sign + numerator; // for integers, irrational, d > 1000
       }
       if (format === "mixed") {
         const modulus = numerator % denominator;
         const integer = (numerator - modulus) / denominator;
-        return sign + (integer ? integer + " " : "") + modulus + "/" + denominator;
-      }
+        return sign + (
+        // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
+        integer ? integer + " " : "") + modulus + "/" + denominator;
+      } // otherwise proper, improper, or fraction
       return sign + numerator + "/" + denominator;
     }
+
+    // otherwise (decimal, float, long long)
     return String(number$1);
   }
 };
@@ -543,24 +761,40 @@ function add(a, b) {
   return a + b;
 }
 
+/**
+ * A collection of geomtry-related utility functions
+ */
+
+
+// This should really be a readonly tuple of [number, number]
+
+// Given a number, return whether it is positive (1), negative (-1), or zero (0)
 function sign(val) {
-  if (approximateEqual(val, 0)) {
+  if (perseusCore.approximateEqual(val, 0)) {
     return 0;
   }
   return val > 0 ? 1 : -1;
 }
+
+// Determine whether three points are collinear (0), for a clockwise turn (negative),
+// or counterclockwise turn (positive)
 function ccw(a, b, c) {
   return (b[0] - a[0]) * (c[1] - a[1]) - (c[0] - a[0]) * (b[1] - a[1]);
 }
 function collinear(a, b, c) {
-  return approximateEqual(ccw(a, b, c), 0);
+  return perseusCore.approximateEqual(ccw(a, b, c), 0);
 }
+
+// Given rect bounding points A and B, whether point C is inside the rect
 function pointInRect(a, b, c) {
   return c[0] <= Math.max(a[0], b[0]) && c[0] >= Math.min(a[0], b[0]) && c[1] <= Math.max(a[1], b[1]) && c[1] >= Math.min(a[1], b[1]);
 }
+
+// Whether line segment AB intersects line segment CD
+// http://www.geeksforgeeks.org/check-if-two-given-line-segments-intersect/
 function intersects(ab, cd) {
   const triplets = [[ab[0], ab[1], cd[0]], [ab[0], ab[1], cd[1]], [cd[0], cd[1], ab[0]], [cd[0], cd[1], ab[1]]];
-  const orientations = _.map(triplets, function (triplet) {
+  const orientations = ___default.default.map(triplets, function (triplet) {
     return sign(ccw(...triplet));
   });
   if (orientations[0] !== orientations[1] && orientations[2] !== orientations[3]) {
@@ -573,14 +807,21 @@ function intersects(ab, cd) {
   }
   return false;
 }
+
+// Whether any two sides of a polygon intersect each other
 function polygonSidesIntersect(vertices) {
   for (let i = 0; i < vertices.length; i++) {
     for (let k = i + 1; k < vertices.length; k++) {
+      // If any two vertices are the same point, sides overlap
       if (equal$2(vertices[i], vertices[k])) {
         return true;
       }
+
+      // Find the other end of the sides starting at vertices i and k
       const iNext = (i + 1) % vertices.length;
       const kNext = (k + 1) % vertices.length;
+
+      // Adjacent sides always intersect (at the vertex); skip those
       if (iNext === k || kNext === i) {
         continue;
       }
@@ -594,16 +835,20 @@ function polygonSidesIntersect(vertices) {
   return false;
 }
 function vector(a, b) {
-  return _.map(_.zip(a, b), function (pair) {
+  return ___default.default.map(___default.default.zip(a, b), function (pair) {
     return pair[0] - pair[1];
   });
 }
 function reverseVector(vector) {
   return [-vector[0], -vector[1]];
 }
+
+// Returns whether connecting the given sequence of `points` forms a clockwise
+// path (assuming a closed loop, where the last point connects back to the
+// first).
 function clockwise(points) {
-  const segments = _.zip(points, points.slice(1).concat(points.slice(0, 1)));
-  const areas = _.map(segments, function (segment) {
+  const segments = ___default.default.zip(points, points.slice(1).concat(points.slice(0, 1)));
+  const areas = ___default.default.map(segments, function (segment) {
     const p1 = segment[0];
     const p2 = segment[1];
     return (p2[0] - p1[0]) * (p2[1] + p1[1]);
@@ -611,36 +856,44 @@ function clockwise(points) {
   return sum(areas) > 0;
 }
 function magnitude(v) {
-  return Math.sqrt(_.reduce(v, function (memo, el) {
+  return Math.sqrt(___default.default.reduce(v, function (memo, el) {
+    // @ts-expect-error - TS2345 - Argument of type 'Coord' is not assignable to parameter of type 'number'.
     return memo + Math.pow(el, 2);
   }, 0));
 }
 function dotProduct(a, b) {
-  return _.reduce(_.zip(a, b), function (memo, pair) {
+  return ___default.default.reduce(___default.default.zip(a, b), function (memo, pair) {
     return memo + pair[0] * pair[1];
   }, 0);
 }
 function sideLengths(coords) {
-  const segments = _.zip(coords, rotate(coords));
+  const segments = ___default.default.zip(coords, rotate(coords));
   return segments.map(function (segment) {
+    // @ts-expect-error - TS2345 - Argument of type 'number[]' is not assignable to parameter of type 'readonly Coord[]'. | TS2556 - A spread argument must either have a tuple type or be passed to a rest parameter.
     return magnitude(vector(...segment));
   });
 }
+
+// Based on http://math.stackexchange.com/a/151149
 function angleMeasures(coords) {
-  const triplets = _.zip(rotate(coords, -1), coords, rotate(coords, 1));
-  const offsets = _.map(triplets, function (triplet) {
+  const triplets = ___default.default.zip(rotate(coords, -1), coords, rotate(coords, 1));
+  const offsets = ___default.default.map(triplets, function (triplet) {
     const p = vector(triplet[1], triplet[0]);
     const q = vector(triplet[2], triplet[1]);
+    // @ts-expect-error - TS2345 - Argument of type 'number[]' is not assignable to parameter of type 'Coord'. | TS2345 - Argument of type 'number[]' is not assignable to parameter of type 'readonly Coord[]'. | TS2345 - Argument of type 'number[]' is not assignable to parameter of type 'readonly Coord[]'.
     const raw = Math.acos(dotProduct(p, q) / (magnitude(p) * magnitude(q)));
+    // @ts-expect-error - TS2556 - A spread argument must either have a tuple type or be passed to a rest parameter.
     return sign(ccw(...triplet)) > 0 ? raw : -raw;
   });
-  const sum = _.reduce(offsets, function (memo, arg) {
+  const sum = ___default.default.reduce(offsets, function (memo, arg) {
     return memo + arg;
   }, 0);
-  return _.map(offsets, function (offset) {
+  return ___default.default.map(offsets, function (offset) {
     return sum > 0 ? Math.PI - offset : Math.PI + offset;
   });
 }
+
+// Whether two polygons are similar (or if specified, congruent)
 function similar(coords1, coords2, tolerance) {
   if (coords1.length !== coords2.length) {
     return false;
@@ -653,22 +906,30 @@ function similar(coords1, coords2, tolerance) {
   for (let i = 0; i < 2 * n; i++) {
     let angles = angles2.slice();
     let sides = sides2.slice();
+
+    // Reverse angles and sides to allow matching reflected polygons
     if (i >= n) {
       angles.reverse();
       sides.reverse();
+      // Since sides are calculated from two coordinates,
+      // simply reversing results in an off by one error
+      // @ts-expect-error - TS4104 - The type 'readonly number[]' is 'readonly' and cannot be assigned to the mutable type 'number[]'.
       sides = rotate(sides, 1);
     }
+
+    // @ts-expect-error - TS4104 - The type 'readonly number[]' is 'readonly' and cannot be assigned to the mutable type 'number[]'.
     angles = rotate(angles, i);
+    // @ts-expect-error - TS4104 - The type 'readonly number[]' is 'readonly' and cannot be assigned to the mutable type 'number[]'.
     sides = rotate(sides, i);
-    if (approximateDeepEqual(angles1, angles)) {
-      const sidePairs = _.zip(sides1, sides);
-      const factors = _.map(sidePairs, function (pair) {
+    if (perseusCore.approximateDeepEqual(angles1, angles)) {
+      const sidePairs = ___default.default.zip(sides1, sides);
+      const factors = ___default.default.map(sidePairs, function (pair) {
         return pair[0] / pair[1];
       });
-      const same = _.all(factors, function (factor) {
-        return approximateEqual(factors[0], factor);
+      const same = ___default.default.all(factors, function (factor) {
+        return perseusCore.approximateEqual(factors[0], factor);
       });
-      const congruentEnough = _.all(sidePairs, function (pair) {
+      const congruentEnough = ___default.default.all(sidePairs, function (pair) {
         return equal$4(pair[0], pair[1], tolerance);
       });
       if (same && congruentEnough) {
@@ -678,21 +939,32 @@ function similar(coords1, coords2, tolerance) {
   }
   return false;
 }
+
+// Given triangle with sides ABC return angle opposite side C in degrees
 function lawOfCosines(a, b, c) {
   return Math.acos((a * a + b * b - c * c) / (2 * a * b)) * 180 / Math.PI;
 }
-function canonicalSineCoefficients([amplitude, angularFrequency, phase, verticalOffset]) {
+function canonicalSineCoefficients(_ref) {
+  let [amplitude, angularFrequency, phase, verticalOffset] = _ref;
+  // For a curve of the form f(x) = a * Sin(b * x - c) + d,
+  // this function ensures that a, b > 0, and c is its
+  // smallest possible positive value.
+
+  // Guarantee a > 0
   if (amplitude < 0) {
     amplitude *= -1;
     angularFrequency *= -1;
     phase *= -1;
   }
   const period = 2 * Math.PI;
+  // Guarantee b > 0
   if (angularFrequency < 0) {
     angularFrequency *= -1;
     phase *= -1;
     phase += period / 2;
   }
+
+  // Guarantee c is smallest possible positive value
   while (phase > 0) {
     phase -= period;
   }
@@ -701,19 +973,26 @@ function canonicalSineCoefficients([amplitude, angularFrequency, phase, vertical
   }
   return [amplitude, angularFrequency, phase, verticalOffset];
 }
+
+// e.g. rotate([1, 2, 3]) -> [2, 3, 1]
 function rotate(array, n) {
   n = typeof n === "undefined" ? 1 : n % array.length;
   return array.slice(n).concat(array.slice(0, n));
 }
 function getLineEquation(first, second) {
-  if (approximateEqual(first[0], second[0])) {
+  if (perseusCore.approximateEqual(first[0], second[0])) {
     return "x = " + first[0].toFixed(3);
   }
   const m = (second[1] - first[1]) / (second[0] - first[0]);
   const b = first[1] - m * first[0];
   return "y = " + m.toFixed(3) + "x + " + b.toFixed(3);
 }
-function getLineIntersection(firstPoints, secondPoints) {
+
+// Stolen from the wikipedia article
+// http://en.wikipedia.org/wiki/Line-line_intersection
+function getLineIntersection(
+// TODO(LP-10725): update these to be 2-tuples
+firstPoints, secondPoints) {
   const x1 = firstPoints[0][0];
   const y1 = firstPoints[0][1];
   const x2 = firstPoints[1][0];
@@ -724,6 +1003,7 @@ function getLineIntersection(firstPoints, secondPoints) {
   const y4 = secondPoints[1][1];
   const determinant = (x1 - x2) * (y3 - y4) - (y1 - y2) * (x3 - x4);
   if (Math.abs(determinant) < 1e-9) {
+    // Lines are parallel
     return null;
   }
   const x = ((x1 * y2 - y1 * x2) * (x3 - x4) - (x1 - x2) * (x3 * y4 - y3 * x4)) / determinant;
@@ -760,16 +1040,25 @@ var geometry = /*#__PURE__*/Object.freeze({
     vector: vector
 });
 
+// This file contains helper functions for working with angles.
+
 function convertDegreesToRadians(degrees) {
   return degrees / 180 * Math.PI;
 }
 function convertRadiansToDegrees(radians) {
   const degree = radians / Math.PI * 180;
+  // Account for floating point errors.
   return Number(degree.toPrecision(15));
 }
-function calculateAngleInDegrees([x, y]) {
+
+// Returns a value between -180 and 180, inclusive. The angle is measured
+// between the positive x-axis and the given vector.
+function calculateAngleInDegrees(_ref) {
+  let [x, y] = _ref;
   return Math.atan2(y, x) * 180 / Math.PI;
 }
+
+// Converts polar coordinates to cartesian. The th(eta) parameter is in degrees.
 function polar(r, th) {
   if (typeof r === "number") {
     r = [r, r];
@@ -777,19 +1066,37 @@ function polar(r, th) {
   th = th * Math.PI / 180;
   return [r[0] * Math.cos(th), r[1] * Math.sin(th)];
 }
+// This function calculates the angle between two points and an optional vertex.
+// If the vertex is not provided, the angle is measured between the two points.
+// This does not account for reflex angles or clockwise position.
 const getAngleFromVertex = (point, vertex) => {
   const x = point[0] - vertex[0];
   const y = point[1] - vertex[1];
+  // eslint-disable-next-line @typescript-eslint/strict-boolean-expressions
   if (!x && !y) {
     return 0;
   }
   return (180 + Math.atan2(-y, -x) * 180 / Math.PI + 360) % 360;
 };
-const getClockwiseAngle = (coords, allowReflexAngles = false) => {
+
+// This function calculates the clockwise angle between three points,
+// and is used to generate the labels and equation strings of the
+// current angle for the interactive graph.
+const getClockwiseAngle = function (coords) {
+  let allowReflexAngles = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : false;
   const coordsCopy = [...coords];
+  // The coords are saved as [point1, vertex, point2] in the interactive graph
   const areClockwise = clockwise([coordsCopy[0], coordsCopy[2], coordsCopy[1]]);
+
+  // We may need to reverse the coordinates if we allow
+  // reflex angles and the points are not in clockwise order.
   const shouldReverseCoords = !areClockwise || allowReflexAngles;
+
+  // Reverse the coordinates accordingly to ensure the angle is calculated correctly
   const clockwiseCoords = shouldReverseCoords ? coordsCopy.reverse() : coordsCopy;
+
+  // Calculate the angles between the two points and get the difference
+  // between the two angles to get the clockwise angle.
   const startAngle = getAngleFromVertex(clockwiseCoords[0], clockwiseCoords[1]);
   const endAngle = getAngleFromVertex(clockwiseCoords[2], clockwiseCoords[1]);
   const angle = (startAngle + 360 - endAngle) % 360;
@@ -806,21 +1113,30 @@ var angles = /*#__PURE__*/Object.freeze({
     polar: polar
 });
 
+// TODO: there's another, very similar getSinusoidCoefficients function
+// they should probably be merged
 function getSinusoidCoefficients(coords) {
+  // It's assumed that p1 is the root and p2 is the first peak
   const p1 = coords[0];
   const p2 = coords[1];
+
+  // Resulting coefficients are canonical for this sine curve
   const amplitude = p2[1] - p1[1];
   const angularFrequency = Math.PI / (2 * (p2[0] - p1[0]));
   const phase = p1[0] * angularFrequency;
   const verticalOffset = p1[1];
   return [amplitude, angularFrequency, phase, verticalOffset];
 }
+// TODO: there's another, very similar getQuadraticCoefficients function
+// they should probably be merged
 function getQuadraticCoefficients(coords) {
   const p1 = coords[0];
   const p2 = coords[1];
   const p3 = coords[2];
   const denom = (p1[0] - p2[0]) * (p1[0] - p3[0]) * (p2[0] - p3[0]);
   if (denom === 0) {
+    // Many of the callers assume that the return value is always defined.
+    // @ts-expect-error - TS2322 - Type 'undefined' is not assignable to type 'QuadraticCoefficient'.
     return;
   }
   const a = (p3[0] * (p2[1] - p1[1]) + p2[0] * (p1[1] - p3[1]) + p1[0] * (p3[1] - p2[1])) / denom;
@@ -835,5 +1151,15 @@ var coefficients = /*#__PURE__*/Object.freeze({
     getSinusoidCoefficients: getSinusoidCoefficients
 });
 
-export { KhanMath, angles, coefficients, geometry, libVersion, line, number, point, ray, sum, vector$1 as vector };
+exports.KhanMath = KhanMath;
+exports.angles = angles;
+exports.coefficients = coefficients;
+exports.geometry = geometry;
+exports.libVersion = libVersion;
+exports.line = line;
+exports.number = number;
+exports.point = point;
+exports.ray = ray;
+exports.sum = sum;
+exports.vector = vector$1;
 //# sourceMappingURL=index.js.map