feat: Update types and comments.

docs/api/op.md

@@ -54,14 +54,6 @@ Merges two or more arrays in sequence, returning a new array.
 
 * *values*: The arrays to merge.
 
-<hr/><a id="join" href="#join">#</a>
-<em>op</em>.<b>join</b>(<i>array</i>[, <i>delimiter</i>]) · [Source](https://github.com/uwdata/arquero/blob/master/src/op/functions/array.js)
-
-Creates and returns a new string by concatenating all of the elements in an *array* (or an array-like object), separated by commas or a specified *delimiter* string. If the *array* has only one item, then that item will be returned without using the delimiter.
-
-* *array*: The input array value.
-* *join*: The delimiter string (default `','`).
-
 <hr/><a id="includes" href="#includes">#</a>
 <em>op</em>.<b>includes</b>(<i>array</i>, <i>value</i>[, <i>index</i>]) · [Source](https://github.com/uwdata/arquero/blob/master/src/op/functions/array.js)
 
@@ -79,6 +71,14 @@ Returns the first index at which a given *value* can be found in the *sequence*
 * *sequence*: The input array or string value.
 * *value*: The value to search for.
 
+<hr/><a id="join" href="#join">#</a>
+<em>op</em>.<b>join</b>(<i>array</i>[, <i>delimiter</i>]) · [Source](https://github.com/uwdata/arquero/blob/master/src/op/functions/array.js)
+
+Creates and returns a new string by concatenating all of the elements in an *array* (or an array-like object), separated by commas or a specified *delimiter* string. If the *array* has only one item, then that item will be returned without using the delimiter.
+
+* *array*: The input array value.
+* *delimiter*: The delimiter string (default `','`).
+
 <hr/><a id="lastindexof" href="#lastindexof">#</a>
 <em>op</em>.<b>lastindexof</b>(<i>sequence</i>, <i>value</i>) · [Source](https://github.com/uwdata/arquero/blob/master/src/op/functions/array.js)
 
@@ -102,21 +102,12 @@ Returns a new array in which the given *property* has been extracted for each el
 * *array*: The input array value.
 * *property*: The property name string to extract. Nested properties are not supported: the input `"a.b"` will indicates a property with that exact name, *not* a nested property `"b"` of the object `"a"`.
 
-<hr/><a id="slice" href="#slice">#</a>
-<em>op</em>.<b>slice</b>(<i>sequence</i>[, <i>start</i>, <i>end</i>]) · [Source](https://github.com/uwdata/arquero/blob/master/src/op/functions/array.js)
-
-Returns a copy of a portion of the input *sequence* (array or string) selected from *start* to *end* (*end* not included) where *start* and *end* represent the index of items in the sequence.
-
-* *sequence*: The input array or string value.
-* *start*: The starting integer index to copy from (inclusive, default `0`).
-* *end*: The ending integer index to copy from (exclusive, default `sequence.length`).
-
 <hr/><a id="reverse" href="#reverse">#</a>
-<em>op</em>.<b>reverse</b>(<i>array</i>) · [Source](https://github.com/uwdata/arquero/blob/master/src/op/functions/array.js)
+<em>op</em>.<b>reverse</b>(<i>sequence</i>) · [Source](https://github.com/uwdata/arquero/blob/master/src/op/functions/array.js)
 
-Returns a new array with the element order reversed: the first *array* element becomes the last, and the last *array* element becomes the first. The input *array* is unchanged.
+Returns a new array or string with the element order reversed: the first *sequence* element becomes the last, and the last *sequence* element becomes the first. The input *sequence* is unchanged.
 
-* *array*: The input array value.
+* *sequence*: The input array or string value.
 
 <hr/><a id="sequence" href="#sequence">#</a>
 <em>op</em>.<b>sequence</b>([<i>start</i>,] <i>stop</i>[, <i>step</i>]) · [Source](https://github.com/uwdata/arquero/blob/master/src/op/functions/sequence.js)
@@ -127,6 +118,14 @@ Returns an array containing an arithmetic sequence from the *start* value to the
 * *stop*: The stopping value of the sequence. The stop value is exclusive; it is not included in the result.
 * *step*: The step increment between sequence values (default `1`).
 
+<hr/><a id="slice" href="#slice">#</a>
+<em>op</em>.<b>slice</b>(<i>sequence</i>[, <i>start</i>, <i>end</i>]) · [Source](https://github.com/uwdata/arquero/blob/master/src/op/functions/array.js)
+
+Returns a copy of a portion of the input *sequence* (array or string) selected from *start* to *end* (*end* not included) where *start* and *end* represent the index of items in the sequence.
+
+* *sequence*: The input array or string value.
+* *start*: The starting integer index to copy from (inclusive, default `0`).
+* *end*: The ending integer index to copy from (exclusive, default `sequence.length`).
 
 <br>
 
@@ -683,7 +682,7 @@ Compare two values for equality, using join semantics in which `null !== null`.
 Returns a boolean indicating whether the *object* has the specified *key* as its own property (as opposed to inheriting it). If the *object* is a [Map](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Map) or [Set](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Set) instance, the `has` method will be invoked directly on the object, otherwise `Object.hasOwnProperty` is used.
 
 * *object*: The object, Map, or Set to test for property membership.
-* *property*: The string property name to test for.
+* *key*: The string key (property name) to test for.
 
 <hr/><a id="keys" href="#keys">#</a>
 <em>op</em>.<b>keys</b>(<i>object</i>) · [Source](https://github.com/uwdata/arquero/blob/master/src/op/functions/object.js)
@@ -811,6 +810,7 @@ If specified, the *index* looks up a value of the resulting match. If *index* is
 
 * *value*: The input string value.
 * *regexp*: The [regular expression](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Regular_Expressions) to match against.
+* *index*: The index into the match result array or capture group.
 
 *Examples*
 

src/format/value.js

@@ -45,6 +45,7 @@ export default function(v, options = {}) {
     } else {
       const s = JSON.stringify(
         v,
+        // @ts-ignore
         (k, v) => isTypedArray(v) ? Array.from(v) : v
       );
       // @ts-ignore

src/op/functions/array.js

@@ -6,20 +6,123 @@ import isValid from '../../util/is-valid.js';
 const isSeq = (seq) => isArrayType(seq) || isString(seq);
 
 export default {
-  compact:      (arr) => isArrayType(arr) ? arr.filter(v => isValid(v)) : arr,
-  concat:       (...values) => [].concat(...values),
-  includes:     (seq, value, index) => isSeq(seq)
-                  ? seq.includes(value, index)
-                  : false,
-  indexof:      (seq, value) => isSeq(seq) ? seq.indexOf(value) : -1,
-  join:         (arr, delim) => isArrayType(arr) ? arr.join(delim) : NULL,
-  lastindexof:  (seq, value) => isSeq(seq) ? seq.lastIndexOf(value) : -1,
-  length:       (seq) => isSeq(seq) ? seq.length : 0,
-  pluck:        (arr, prop) => isArrayType(arr)
-                  ? arr.map(v => isValid(v) ? v[prop] : NULL)
-                  : NULL,
-  reverse:      (seq) => isArrayType(seq) ? seq.slice().reverse()
-                  : isString(seq) ? seq.split('').reverse().join('')
-                  : NULL,
-  slice:        (seq, start, end) => isSeq(seq) ? seq.slice(start, end) : NULL
+  /**
+   * Returns a new compacted array with invalid values
+   * (`null`, `undefined`, `NaN`) removed.
+   * @template T
+   * @param {T[]} array The input array.
+   * @return {T[]} A compacted array.
+   */
+  compact: (array) => isArrayType(array)
+    ? array.filter(v => isValid(v))
+    : array,
+
+  /**
+   * Merges two or more arrays in sequence, returning a new array.
+   * @template T
+   * @param {...(T|T[])} values The arrays to merge.
+   * @return {T[]} The merged array.
+   */
+  concat: (...values) => [].concat(...values),
+
+  /**
+   * Determines whether an *array* includes a certain *value* among its
+   * entries, returning `true` or `false` as appropriate.
+   * @template T
+   * @param {T[]} sequence The input array value.
+   * @param {T} value The value to search for.
+   * @param {number} [index=0] The integer index to start searching
+   *  from (default `0`).
+   * @return {boolean} True if the value is included, false otherwise.
+   */
+  includes: (sequence, value, index) => isSeq(sequence)
+    ? sequence.includes(value, index)
+    : false,
+
+  /**
+   * Returns the first index at which a given *value* can be found in the
+   * *sequence* (array or string), or -1 if it is not present.
+   * @template T
+   * @param {T[]|string} sequence The input array or string value.
+   * @param {T} value The value to search for.
+   * @return {number} The index of the value, or -1 if not present.
+   */
+  indexof: (sequence, value) => isSeq(sequence)
+    // @ts-ignore
+    ? sequence.indexOf(value)
+    : -1,
+
+  /**
+   * Creates and returns a new string by concatenating all of the elements
+   * in an *array* (or an array-like object), separated by commas or a
+   * specified *delimiter* string. If the *array* has only one item, then
+   * that item will be returned without using the delimiter.
+   * @template T
+   * @param {T[]} array The input array value.
+   * @param {string} delim The delimiter string (default `','`).
+   * @return {string} The joined string.
+   */
+  join: (array, delim) => isArrayType(array) ? array.join(delim) : NULL,
+
+  /**
+   * Returns the last index at which a given *value* can be found in the
+   * *sequence* (array or string), or -1 if it is not present.
+   * @template T
+   * @param {T[]|string} sequence The input array or string value.
+   * @param {T} value The value to search for.
+   * @return {number} The last index of the value, or -1 if not present.
+   */
+  lastindexof: (sequence, value) => isSeq(sequence)
+    // @ts-ignore
+    ? sequence.lastIndexOf(value)
+    : -1,
+
+  /**
+   * Returns the length of the input *sequence* (array or string).
+   * @param {Array|string} sequence The input array or string value.
+   * @return {number} The length of the sequence.
+   */
+  length: (sequence) => isSeq(sequence) ? sequence.length : 0,
+
+  /**
+   * Returns a new array in which the given *property* has been extracted
+   * for each element in the input *array*.
+   * @param {Array} array The input array value.
+   * @param {string} property The property name string to extract. Nested
+   *  properties are not supported: the input `"a.b"` will indicates a
+   *  property with that exact name, *not* a nested property `"b"` of
+   *  the object `"a"`.
+   * @return {Array} An array of plucked properties.
+   */
+  pluck: (array, property) => isArrayType(array)
+    ? array.map(v => isValid(v) ? v[property] : NULL)
+    : NULL,
+
+  /**
+   * Returns a new array or string with the element order reversed: the first
+   * *sequence* element becomes the last, and the last *sequence* element
+   * becomes the first. The input *sequence* is unchanged.
+   * @template T
+   * @param {T[]|string} sequence The input array or string value.
+   * @return {T[]|string} The reversed sequence.
+   */
+  reverse: (sequence) => isArrayType(sequence) ? sequence.slice().reverse()
+    : isString(sequence) ? sequence.split('').reverse().join('')
+    : NULL,
+
+  /**
+   * Returns a copy of a portion of the input *sequence* (array or string)
+   * selected from *start* to *end* (*end* not included) where *start* and
+   * *end* represent the index of items in the sequence.
+   * @template T
+   * @param {T[]|string} sequence The input array or string value.
+   * @param {number} [start=0] The starting integer index to copy from
+   *  (inclusive, default `0`).
+   * @param {number} [end] The ending integer index to copy from (exclusive,
+   *  default `sequence.length`).
+   * @return {T[]|string} The sliced sequence.
+   */
+  slice: (sequence, start, end) => isSeq(sequence)
+    ? sequence.slice(start, end)
+    : NULL
 };

src/op/functions/bin.js

@@ -3,11 +3,11 @@
  * Useful for creating equal-width histograms.
  * Values outside the [min, max] range will be mapped to
  * -Infinity (< min) or +Infinity (> max).
- * @param {number} value - The value to bin.
- * @param {number} min - The minimum bin boundary.
- * @param {number} max - The maximum bin boundary.
- * @param {number} step - The step size between bin boundaries.
- * @param {number} [offset=0] - Offset in steps by which to adjust
+ * @param {number} value The value to bin.
+ * @param {number} min The minimum bin boundary.
+ * @param {number} max The maximum bin boundary.
+ * @param {number} step The step size between bin boundaries.
+ * @param {number} [offset=0] Offset in steps by which to adjust
  *  the bin value. An offset of 1 will return the next boundary.
  */
 export default function(value, min, max, step, offset) {