@khanacademy/kmath 0.0.4 → 0.0.6

package/package.json

@@ -1,10 +1,19 @@
 {
+    "name": "@khanacademy/kmath",
+    "description": "Khan Academy's Javascript Numeric Math Utilities",
+    "author": "Khan Academy",
+    "license": "MIT",
+    "version": "0.0.6",
     "publishConfig": {
         "access": "public"
     },
-    "name": "@khanacademy/kmath",
-    "version": "0.0.4",
-    "description": "Khan Academy's Javascript Numeric Math Utilities",
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/Khan/kmath.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Khan/perseus/issues"
+    },
     "module": "dist/es/index.js",
     "main": "dist/index.js",
     "source": "src/index.js",
@@ -13,12 +22,11 @@
     },
     "dependencies": {},
     "devDependencies": {
-        "perseus-build-settings": "^0.0.1",
+        "perseus-build-settings": "^0.0.3",
         "underscore": "1.4.4"
     },
     "peerDependencies": {
         "underscore": "1.4.4"
     },
-    "author": "Khan Academy",
-    "license": "MIT"
+    "keywords": []
 }

package/src/line.js

@@ -15,10 +15,7 @@ export function distanceToPoint(line: Line, point: Point): number {
     return kpoint.distanceToLine(point, line);
 }
 
-export function reflectPoint(
-    line: Line,
-    point: Point,
-): $ReadOnlyArray<number> /* TODO: convert to Point */ {
+export function reflectPoint(line: Line, point: Point): Point {
     return kpoint.reflectOverLine(point, line);
 }
 

package/src/logo.js

@@ -1,13 +1,15 @@
+/* eslint-disable import/no-default-export */
+// @flow
 // This file describes the graphie source code of the kmath logo
 // currently used on khan.github.io.
 //
 // Also located at http://ka-perseus-graphie.s3.amazonaws.com/42ef3cbadc3e6464124533191728c3c5c55c7355.svg
 
-// eslint-disable-next-line flowtype/no-types-missing-file-annotation
+// eslint-disable-next-line ft-flow/no-types-missing-file-annotation
 declare var init: $FlowFixMe;
-// eslint-disable-next-line flowtype/no-types-missing-file-annotation
+// eslint-disable-next-line ft-flow/no-types-missing-file-annotation
 declare var ellipse: $FlowFixMe;
-// eslint-disable-next-line flowtype/no-types-missing-file-annotation
+// eslint-disable-next-line ft-flow/no-types-missing-file-annotation
 declare var line: $FlowFixMe;
 
 const GREEN = "#28AE7B";

package/src/point.js

@@ -6,14 +6,14 @@
 
 import _ from "underscore";
 
-import * as kvector from "./vector.js";
 import * as knumber from "./number.js";
+import * as kvector from "./vector.js";
 
 // A point, in 2D, 3D, or nD space.
 export type Point = $ReadOnlyArray<number>;
 
 // Rotate point (around origin unless a center is specified)
-export function rotateRad(point: Point, theta: number, center: Point): Point {
+export function rotateRad(point: Point, theta: number, center?: Point): Point {
     if (center === undefined) {
         return kvector.rotateRad(point, theta);
     } else {
@@ -24,7 +24,7 @@ export function rotateRad(point: Point, theta: number, center: Point): Point {
     }
 }
 
-export function rotateDeg(point: Point, theta: number, center: Point): Point {
+export function rotateDeg(point: Point, theta: number, center?: Point): Point {
     if (center === undefined) {
         return kvector.rotateDeg(point, theta);
     } else {
@@ -50,10 +50,7 @@ export function distanceToLine(point: Point, line: [Point, Point]): number {
 }
 
 // Reflect point over line
-export function reflectOverLine(
-    point: Point,
-    line: [Point, Point],
-): $ReadOnlyArray<number> /* TODO: convert to Point */ {
+export function reflectOverLine<P: Point>(point: P, line: [P, P]): P {
     const lv = kvector.subtract(line[1], line[0]);
     const pv = kvector.subtract(point, line[0]);
     const projectedPv = kvector.projection(pv, lv);

package/src/ray.js

@@ -6,14 +6,14 @@
  * traveling along the positive x-axis.
  */
 
-import * as kvector from "./vector.js";
 import * as kpoint from "./point.js";
+import * as kvector from "./vector.js";
 
 import type {Point} from "./point";
 
 export type Ray = [Point, Point];
 
-export function equal(ray1: Ray, ray2: Ray, tolerance: number): boolean {
+export function equal(ray1: Ray, ray2: Ray, tolerance?: number): boolean {
     // Compare the directions of the rays
     const v1 = kvector.subtract(ray1[1], ray1[0]);
     const v2 = kvector.subtract(ray2[1], ray2[0]);

package/src/vector.js

@@ -5,8 +5,11 @@
  */
 
 import _ from "underscore";
+
 import * as knumber from "./number.js";
 
+type Vector = $ReadOnlyArray<number>;
+
 function arraySum(array: $ReadOnlyArray<number>): number {
     return array.reduce((memo, arg) => memo + arg, 0);
 }
@@ -15,7 +18,15 @@ function arrayProduct(array: $ReadOnlyArray<number>): number {
     return array.reduce((memo, arg) => memo * arg, 1);
 }
 
-export function is<T>(vec: $ReadOnlyArray<T>, dimension: number): boolean {
+/**
+ * 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
+ */
+export function is<T>(vec: $ReadOnlyArray<T>, dimension?: number): boolean {
     if (!_.isArray(vec)) {
         return false;
     }
@@ -26,19 +37,16 @@ export function is<T>(vec: $ReadOnlyArray<T>, dimension: number): boolean {
 }
 
 // Normalize to a unit vector
-export function normalize(v: $ReadOnlyArray<number>): $ReadOnlyArray<number> {
+export function normalize<V: Vector>(v: V): V {
     return scale(v, 1 / length(v));
 }
 
 // Length/magnitude of a vector
-export function length(v: $ReadOnlyArray<number>): number {
+export function length(v: Vector): number {
     return Math.sqrt(dot(v, v));
 }
 // Dot product of two vectors
-export function dot(
-    a: $ReadOnlyArray<number>,
-    b: $ReadOnlyArray<number>,
-): number {
+export function dot(a: Vector, b: Vector): number {
     // $FlowFixMe[incompatible-call] underscore doesn't like $ReadOnlyArray
     const zipped = _.zip(a, b);
     const multiplied = zipped.map(arrayProduct);
@@ -49,43 +57,33 @@ export function dot(
  *
  * add([1, 2], [3, 4]) -> [4, 6]
  */
-export function add(
-    ...vecs: $ReadOnlyArray<$ReadOnlyArray<number>>
-): $ReadOnlyArray<number> {
+export function add<V: Vector>(...vecs: $ReadOnlyArray<V>): V {
     // $FlowFixMe[incompatible-call] underscore doesn't like $ReadOnlyArray
     const zipped = _.zip(...vecs);
     return zipped.map(arraySum);
 }
 
-export function subtract(
-    v1: $ReadOnlyArray<number>,
-    v2: $ReadOnlyArray<number>,
-): $ReadOnlyArray<number> {
+export function subtract<V: Vector>(v1: V, v2: V): V {
     // $FlowFixMe[incompatible-call] underscore doesn't like $ReadOnlyArray
     return _.zip(v1, v2).map((dim) => dim[0] - dim[1]);
 }
 
-export function negate(v: $ReadOnlyArray<number>): $ReadOnlyArray<number> {
+export function negate<V: Vector>(v: V): V {
+    // $FlowFixMe[incompatible-return] Flow's `.map()` libdef is lacking
     return v.map((x) => {
         return -x;
     });
 }
 
 // Scale a vector
-export function scale(
-    v1: $ReadOnlyArray<number>,
-    scalar: number,
-): $ReadOnlyArray<number> {
+export function scale<V: Vector>(v1: V, scalar: number): V {
+    // $FlowFixMe[incompatible-return] Flow's `.map()` libdef is lacking
     return v1.map((x) => {
         return x * scalar;
     });
 }
 
-export function equal(
-    v1: $ReadOnlyArray<number>,
-    v2: $ReadOnlyArray<number>,
-    tolerance?: number,
-): boolean {
+export function equal(v1: Vector, v2: Vector, tolerance?: number): boolean {
     // _.zip will nicely deal with the lengths, going through
     // the length of the longest vector. knumber.equal then
     // returns false for any number compared to the undefined
@@ -97,8 +95,8 @@ export function equal(
 }
 
 export function codirectional(
-    v1: $ReadOnlyArray<number>,
-    v2: $ReadOnlyArray<number>,
+    v1: Vector,
+    v2: Vector,
     tolerance?: number,
 ): boolean {
     // The origin is trivially codirectional with all other vectors.
@@ -117,17 +115,15 @@ export function codirectional(
     return equal(v1, v2, tolerance);
 }
 
-export function collinear(
-    v1: $ReadOnlyArray<number>,
-    v2: $ReadOnlyArray<number>,
-    tolerance?: number,
-): boolean {
+export function collinear(v1: Vector, v2: Vector, tolerance?: number): boolean {
     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
 export function polarRadFromCart(
     v: $ReadOnlyArray<number>,
@@ -155,7 +151,6 @@ export function polarDegFromCart(
  *
  * Examples:
  * cartFromPolarRad(5, Math.PI)
- * cartFromPolarRad([5, Math.PI])
  */
 export function cartFromPolarRad(
     radius: number,
@@ -168,7 +163,6 @@ export function cartFromPolarRad(
  *
  * Examples:
  * cartFromPolarDeg(5, 30)
- * cartFromPolarDeg([5, 30])
  */
 export function cartFromPolarDeg(
     radius: number,
@@ -197,34 +191,23 @@ export function rotateDeg(
 }
 
 // Angle between two vectors
-export function angleRad(
-    v1: $ReadOnlyArray<number>,
-    v2: $ReadOnlyArray<number>,
-): number {
+export function angleRad(v1: Vector, v2: Vector): number {
     return Math.acos(dot(v1, v2) / (length(v1) * length(v2)));
 }
 
-export function angleDeg(
-    v1: $ReadOnlyArray<number>,
-    v2: $ReadOnlyArray<number>,
-): number {
+export function angleDeg(v1: Vector, v2: Vector): number {
     return (angleRad(v1, v2) * 180) / Math.PI;
 }
 
 // Vector projection of v1 onto v2
-export function projection(
-    v1: $ReadOnlyArray<number>,
-    v2: $ReadOnlyArray<number>,
-): $ReadOnlyArray<number> {
+export function projection<V: Vector>(v1: V, v2: V): V {
     const scalar = dot(v1, v2) / dot(v2, v2);
     return scale(v2, scalar);
 }
 
 // Round each number to a certain number of decimal places
-export function round(
-    vec: $ReadOnlyArray<number>,
-    precision: $ReadOnlyArray<number> | number,
-): $ReadOnlyArray<number> {
+export function round<V: Vector>(vec: V, precision: V | number): V {
+    // $FlowFixMe[incompatible-return] Flow's `.map()` libdef is lacking
     return vec.map((elem, i) =>
         // $FlowFixMe[prop-missing]
         // $FlowFixMe[incompatible-call]
@@ -233,10 +216,8 @@ export function round(
 }
 
 // Round each number to the nearest increment
-export function roundTo(
-    vec: $ReadOnlyArray<number>,
-    increment: $ReadOnlyArray<number> | number,
-): $ReadOnlyArray<number> {
+export function roundTo<V: Vector>(vec: V, increment: V | number): V {
+    // $FlowFixMe[incompatible-return] Flow's `.map()` libdef is lacking
     return vec.map((elem, i) =>
         // $FlowFixMe[prop-missing]
         // $FlowFixMe[incompatible-call]
@@ -244,10 +225,8 @@ export function roundTo(
     );
 }
 
-export function floorTo(
-    vec: $ReadOnlyArray<number>,
-    increment: $ReadOnlyArray<number> | number,
-): $ReadOnlyArray<number> {
+export function floorTo<V: Vector>(vec: V, increment: V | number): V {
+    // $FlowFixMe[incompatible-return] Flow's `.map()` libdef is lacking
     return vec.map((elem, i) =>
         // $FlowFixMe[prop-missing]
         // $FlowFixMe[incompatible-call]
@@ -255,10 +234,8 @@ export function floorTo(
     );
 }
 
-export function ceilTo(
-    vec: $ReadOnlyArray<number>,
-    increment: $ReadOnlyArray<number> | number,
-): $ReadOnlyArray<number> {
+export function ceilTo<V: Vector>(vec: V, increment: V | number): V {
+    // $FlowFixMe[incompatible-return] Flow's `.map()` libdef is lacking
     return vec.map((elem, i) =>
         // $FlowFixMe[prop-missing]
         // $FlowFixMe[incompatible-call]