Add JSDoc based types

.gitignore

@@ -1,5 +1,6 @@
+.DS_Store
+*.d.ts
 *.log
 coverage/
 node_modules/
-.DS_Store
 yarn.lock

index.js

@@ -1,6 +1,17 @@
 var own = {}.hasOwnProperty
 
-export function arrayIterate(values, callback, context) {
+/**
+ * Perform the specified action for each element in an array.
+ * When `callbackFn` returns a `number`, moves to the element at that index next.
+ *
+ * @template {any} Value
+ * @template {ArrayLike<Value>} Values
+ * @param {Values} values Values to iterate over
+ * @param {(value: Value, index: number, array: Values) => number | void} callbackFn A function that accepts up to three arguments
+ * @param {any} [thisArg] thisArg An object to which the this keyword can refer in `callbackFn`. If `thisArg` is omitted, `undefined` is used as the `this` value.
+ * @returns {void}
+ */
+export function arrayIterate(values, callbackFn, thisArg) {
   var index = -1
   var result
 
@@ -12,7 +23,7 @@ export function arrayIterate(values, callback, context) {
     throw new Error('Iterate requires that |this| has a `length`')
   }
 
-  if (typeof callback !== 'function') {
+  if (typeof callbackFn !== 'function') {
     throw new Error('`callback` must be a function')
   }
 
@@ -23,7 +34,7 @@ export function arrayIterate(values, callback, context) {
       continue
     }
 
-    result = callback.call(context, values[index], index, values)
+    result = callbackFn.call(thisArg, values[index], index, values)
 
     // If `callback` returns a `number`, move `index` over to `number`.
     if (typeof result === 'number') {

package.json

@@ -22,22 +22,30 @@
   "sideEffects": false,
   "type": "module",
   "main": "index.js",
+  "types": "index.d.ts",
   "files": [
+    "index.d.ts",
     "index.js"
   ],
   "devDependencies": {
+    "@types/tape": "^4.0.0",
     "c8": "^7.0.0",
     "prettier": "^2.0.0",
     "remark-cli": "^9.0.0",
     "remark-preset-wooorm": "^8.0.0",
+    "rimraf": "^3.0.0",
     "tape": "^5.0.0",
+    "typescript": "^4.0.0",
     "xo": "^0.38.0"
   },
   "scripts": {
+    "prepublishOnly": "npm run build && npm run format",
     "format": "remark . -qfo && prettier . -w --loglevel warn && xo --fix",
+    "prebuild": "rimraf \"*.d.ts\"",
+    "build": "tsc",
     "test-api": "node test",
     "test-coverage": "c8 --check-coverage --branches 100 --functions 100 --lines 100 --statements 100 --reporter lcov node test.js",
-    "test": "npm run format && npm run test-coverage"
+    "test": "npm run build && npm run format && npm run test-coverage"
   },
   "prettier": {
     "tabWidth": 2,

readme.md

@@ -24,11 +24,11 @@ npm install array-iterate
 import {arrayIterate} from 'array-iterate'
 
 var isFirst = true
-var context = {hello: 'world'}
+var thisArg = {hello: 'world'}
 
-arrayIterate([1, 2, 3, 4], callback, context)
+arrayIterate([1, 2, 3, 4], callbackFn, thisArg)
 
-function callback(value, index, values) {
+function callbackFn(value, index, values) {
   console.log(this, value, index, values)
 
   if (isFirst && index + 1 === values.length) {
@@ -56,18 +56,23 @@ Yields:
 This package exports the following identifiers: `arrayIterate`.
 There is no default export.
 
-### `arrayIterate(values, callback[, context])`
+### `arrayIterate(values, callbackFn[, thisArg])`
 
-Works just like [`Array#forEach()`][foreach], but when `callback` returns a
-`number`, iterates over the item at `number` next.
+Perform the specified action for each element in an array, so works just like
+[`Array#forEach()`][foreach].
+When `callbackFn` returns a `number`, moves to the element at that index next.
 
 ###### Parameters
 
-*   `values` (`Array`-like thing) — Values to iterate over
-*   `callback` ([`Function`][callback]) — Callback given to `iterate`
-*   `context` (`*`, optional) — Context object to use when invoking `callback`
+*   `values` (`Array`-like thing)
+    — Values to iterate over
+*   `callbackFn` ([`Function`][callback])
+    — A function that accepts up to three arguments
+*   `thisArg` (`*`, optional)
+    — An object to which the this keyword can refer in `callbackFn`.
+    If `thisArg` is omitted, `undefined` is used as the `this` value
 
-#### `function callback(value, index, values)`
+#### `function callbackFn(value, index, values)`
 
 Callback given to `iterate`.
 
@@ -79,7 +84,7 @@ Callback given to `iterate`.
 
 ###### Context
 
-`context`, when given to `iterate`.
+`thisArg` when given to `arrayIterate` or `undefined`
 
 ###### Returns
 
@@ -115,4 +120,4 @@ Callback given to `iterate`.
 
 [foreach]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach
 
-[callback]: #function-callbackvalue-index-values
+[callback]: #function-callbackfnvalue-index-values

test.js

@@ -4,6 +4,7 @@ import {arrayIterate} from './index.js'
 test('arrayIterate()', function (t) {
   t.throws(
     function () {
+      // @ts-ignore
       arrayIterate()
     },
     /^Error: Iterate requires that \|this\| not be undefined$/,
@@ -12,6 +13,7 @@ test('arrayIterate()', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore
       arrayIterate({})
     },
     /Error: Iterate requires that \|this\| has a `length`/,
@@ -20,6 +22,7 @@ test('arrayIterate()', function (t) {
 
   t.throws(
     function () {
+      // @ts-ignore
       arrayIterate([])
     },
     /^Error: `callback` must be a function$/,

tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "files": ["index.js"],
+  "include": ["*.js"],
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "module": "ES2020",
+    "moduleResolution": "node",
+    "allowJs": true,
+    "checkJs": true,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "allowSyntheticDefaultImports": true,
+    "skipLibCheck": true
+  }
+}