iterall - npm Package Compare versions

Comparing version 1.1.3 to 1.1.4

index.js

@@ -19,7 +19,4 @@ /**
  *
- * @typedef {Object} Iterator
- * @template T The type of each iterated value
- * @property {function (): { value: T, done: boolean }} next
- *   A method which produces either the next value in a sequence or a result
- *   where the `done` property is `true` indicating the end of the Iterator.
+ * @external Iterator
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterator|MDN Iteration protocols}
  */
@@ -30,3 +27,4 @@
  * is a *protocol* which when implemented allows a JavaScript object to define
- * their iteration behavior, such as what values are looped over in a `for..of`
+ * their iteration behavior, such as what values are looped over in a
+ * [`for...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of)
  * loop or `iterall`'s `forEach` function. Many [built-in types](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#Builtin_iterables)
@@ -38,6 +36,4 @@ * implement the Iterable protocol, including `Array` and `Map`.
  *
- * @typedef {Object} Iterable
- * @template T The type of each iterated value
- * @property {function (): Iterator<T>} Symbol.iterator
- *   A method which produces an Iterator for this Iterable.
+ * @external Iterable
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterable|MDN Iteration protocols}
  */
@@ -56,3 +52,3 @@
  * but do not use it for accessing existing Iterables, instead use
- * `getIterator()` or `isIterable()`.
+ * {@link getIterator} or {@link isIterable}.
  *
@@ -230,3 +226,3 @@ * @example
 /**
- * Similar to `getIterator()`, this method returns a new Iterator given an
+ * Similar to {@link getIterator}, this method returns a new Iterator given an
  * Iterable. However it will also create an Iterator for a non-Iterable
@@ -374,34 +370,33 @@ * Array-like collection, such as Array in a non-ES2015 environment.
 /**
- * [AsyncIterator](https://tc39.github.io/proposal-async-iteration/)
- * is a *protocol* which describes a standard way to produce and consume an
- * asynchronous sequence of values, typically the values of the AsyncIterable
- * represented by this AsyncIterator.
+ * [AsyncIterable](https://tc39.github.io/proposal-async-iteration/#sec-asynciterable-interface)
+ * is a *protocol* which when implemented allows a JavaScript object to define
+ * an asynchronous iteration behavior, such as what values are looped over in
+ * a [`for-await-of`](https://tc39.github.io/proposal-async-iteration/#sec-for-in-and-for-of-statements)
+ * loop or `iterall`'s {@link forAwaitEach} function.
  *
- * AsyncIterator is similar to Observable or Stream.
- *
  * While described as a proposed addition to the [ES2017 version of JavaScript](https://tc39.github.io/proposal-async-iteration/)
  * it can be utilized by any version of JavaScript.
  *
- * @typedef {Object} AsyncIterator
+ * @external AsyncIterable
+ * @see {@link https://tc39.github.io/proposal-async-iteration/#sec-asynciterable-interface|Async Iteration Proposal}
  * @template T The type of each iterated value
- * @property {function (): Promise<{ value: T, done: boolean }>} next
- *   A method which produces a Promise which resolves to either the next value
- *   in a sequence or a result where the `done` property is `true` indicating
- *   the end of the sequence of values. It may also produce a Promise which
- *   becomes rejected, indicating a failure.
+ * @property {function (): AsyncIterator<T>} Symbol.asyncIterator
+ *   A method which produces an AsyncIterator for this AsyncIterable.
  */
 
 /**
- * AsyncIterable is a *protocol* which when implemented allows a JavaScript
- * object to define their asynchronous iteration behavior, such as what values
- * are looped over in a `for-await-of` loop or `iterall`'s `forAwaitEach`
- * function.
+ * [AsyncIterator](https://tc39.github.io/proposal-async-iteration/#sec-asynciterator-interface)
+ * is a *protocol* which describes a standard way to produce and consume an
+ * asynchronous sequence of values, typically the values of the
+ * {@link AsyncIterable} represented by this {@link AsyncIterator}.
  *
+ * AsyncIterator is similar to Observable or Stream. Like an {@link Iterator} it
+ * also as a `next()` method, however instead of an IteratorResult,
+ * calling this method returns a {@link Promise} for a IteratorResult.
+ *
  * While described as a proposed addition to the [ES2017 version of JavaScript](https://tc39.github.io/proposal-async-iteration/)
  * it can be utilized by any version of JavaScript.
  *
- * @typedef {Object} AsyncIterable
- * @template T The type of each iterated value
- * @property {function (): AsyncIterator<T>} Symbol.asyncIterator
- *   A method which produces an AsyncIterator for this AsyncIterable.
+ * @external AsyncIterator
+ * @see {@link https://tc39.github.io/proposal-async-iteration/#sec-asynciterator-interface|Async Iteration Proposal}
  */
@@ -420,3 +415,3 @@
  * `Symbol.asyncIterator`, but do not use it for accessing existing Iterables,
- * instead use `getAsyncIterator()` or `isAsyncIterable()`.
+ * instead use {@link getAsyncIterator} or {@link isAsyncIterable}.
  *
@@ -436,11 +431,11 @@ * @example
  *     next () {
- *       return new Promise(function (resolve) {
+ *       return new Promise(resolve => {
  *         if (this.num >= this.to) {
  *           resolve({ value: undefined, done: true })
  *         } else {
- *           setTimeout(function () {
+ *           setTimeout(() => {
  *             resolve({ value: this.num++, done: false })
  *           }, 1000)
  *         }
- *       }
+ *       })
  *     }
@@ -538,3 +533,3 @@ *   }
 /**
- * Similar to `getAsyncIterator()`, this method returns a new AsyncIterator
+ * Similar to {@link getAsyncIterator}, this method returns a new AsyncIterator
  * given an AsyncIterable. However it will also create an AsyncIterator for a
@@ -609,3 +604,3 @@ * non-async Iterable as well as non-Iterable Array-like collection, such as
  *
- * Use `forAwaitEach` where you would expect to use a `for-await-of` loop.
+ * Use `forAwaitEach` where you would expect to use a [for-await-of](https://tc39.github.io/proposal-async-iteration/#sec-for-in-and-for-of-statements) loop.
  *
@@ -656,3 +651,3 @@ * Similar to [Array#forEach][], the `callback` function accepts three
       function next() {
-        return asyncIterator
+        asyncIterator
           .next()
@@ -667,4 +662,8 @@ .then(function(step) {
             }
+            // Explicitly return null, silencing bluebird-style warnings.
+            return null
           })
           .catch(reject)
+        // Explicitly return null, silencing bluebird-style warnings.
+        return null
       }
@@ -671,0 +670,0 @@ next()

package.json

 {
   "name": "iterall",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Minimal zero-dependency utilities for using JavaScript Iterables in all environments.",
@@ -14,4 +14,4 @@ "main": "index.js",
     "testonly": "nyc --check-coverage --statements 100 node test.js",
-    "testdocs": "if [ \"$(documentation readme -dgs API | grep -vF 'up to date')\" ]; then echo 'Must run: npm run docs'; exit 1; fi;",
-    "docs": "documentation readme -gs API",
+    "testdocs": "if [ \"$(documentation readme -ds API | grep -vF 'up to date')\" ]; then echo 'Must run: npm run docs'; exit 1; fi;",
+    "docs": "documentation readme -s API",
     "travis": "npm run lint-check && npm run flow && npm run testdocs && npm run testonly && nyc report --reporter=text-lcov | coveralls"
@@ -43,8 +43,9 @@ },
   "devDependencies": {
-    "coveralls": "2.13.1",
-    "documentation": "4.0.0-beta.19",
+    "coveralls": "3.0.0",
+    "documentation": "5.3.5",
     "flow-bin": "0.49.1",
-    "nyc": "11.0.3",
-    "prettier": "1.5.2"
+    "nyc": "11.4.1",
+    "prettier": "1.10.2",
+    "regression": "2.0.1"
   }
 }

README.md

@@ -174,2 +174,54 @@ # JavaScript [Iterators][] and [AsyncIterators][] for all!
 
+> How do I break out of a `forEach` or `forAwaitEach` loop early?
+
+While `for of` and `for await of` loops allow breaking out of a loop early with
+a `break` statement, the `forEach()` and `forAwaitEach()` functions (much like
+Array's `forEach`)  do not support early breaking.
+
+Similar to the "higher order" functions described above, this library can be the
+basis for this extended behavior. To support early break outs, you can use a
+wrapping function supporting early breaking by throwing a `BREAK` sentinel value
+from the callback and using a try/catch block to early break:
+
+```js
+const BREAK = {}
+
+function forEachBreakable (collection, callback) {
+  try {
+    forEach(collection, callback)
+  } catch (error) {
+    if (error !== BREAK) {
+      throw error
+    }
+  }
+}
+
+async function forAwaitEachBreakable (collection, callback) {
+  try {
+    await forAwaitEach(collection, callback)
+  } catch (error) {
+    if (error !== BREAK) {
+      throw error
+    }
+  }
+}
+
+// Example usages:
+forEachBreakable(obj, function (value) {
+  if (shouldBreakOn(value)) {
+    throw BREAK
+  }
+  console.log(value)
+})
+
+forAwaitEachBreakable(obj, async function (value) {
+  if (await shouldBreakOn(value)) {
+    throw BREAK
+  }
+  console.log(value)
+})
+```
+
+Note: This technique also works with the native Array `forEach` method!
+
 <!--
@@ -190,7 +242,31 @@
 
+#### Table of Contents
+
+-   [Iterable](#iterable)
+-   [Iterator](#iterator)
+-   [$$iterator](#iterator-1)
+-   [isIterable](#isiterable)
+-   [isArrayLike](#isarraylike)
+-   [isCollection](#iscollection)
+-   [getIterator](#getiterator)
+-   [getIteratorMethod](#getiteratormethod)
+-   [createIterator](#createiterator)
+-   [forEach](#foreach)
+-   [AsyncIterable](#asynciterable)
+-   [AsyncIterator](#asynciterator)
+-   [$$asyncIterator](#asynciterator-1)
+-   [isAsyncIterable](#isasynciterable)
+-   [getAsyncIterator](#getasynciterator)
+-   [getAsyncIteratorMethod](#getasynciteratormethod)
+-   [createAsyncIterator](#createasynciterator)
+-   [forAwaitEach](#forawaiteach)
+
 ### Iterable
 
+-   **See: [MDN Iteration protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterable)**
+
 [Iterable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterable)
 is a _protocol_ which when implemented allows a JavaScript object to define
-their iteration behavior, such as what values are looped over in a `for..of`
+their iteration behavior, such as what values are looped over in a
+[`for...of`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Statements/for...of)
 loop or `iterall`'s `forEach` function. Many [built-in types](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#Builtin_iterables)
@@ -202,10 +278,6 @@ implement the Iterable protocol, including `Array` and `Map`.
 
-Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+### Iterator
 
-**Properties**
+-   **See: [MDN Iteration protocols](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterator)**
 
--   `Symbol.iterator` **function (): [Iterator](#iterator)&lt;T>** A method which produces an Iterator for this Iterable.
-
-### Iterator
-
 [Iterator](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Iteration_protocols#iterator)
@@ -218,9 +290,2 @@ is a _protocol_ which describes a standard way to produce a sequence of
 
-Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
-
-**Properties**
-
--   `next` **function (): {value: T, done: [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)}** A method which produces either the next value in a sequence or a result
-      where the `done` property is `true` indicating the end of the Iterator.
-
 ### $$iterator
@@ -235,3 +300,3 @@
 but do not use it for accessing existing Iterables, instead use
-`getIterator()` or `isIterable()`.
+[getIterator](#getiterator) or [isIterable](#isiterable).
 
@@ -286,3 +351,3 @@ **Examples**
 
-Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if Iterable.
+Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if Iterable.
 
@@ -309,3 +374,3 @@ ### isArrayLike
 
-Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if Array-like.
+Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if Array-like.
 
@@ -346,3 +411,3 @@ ### isCollection
 
-Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if Iterable or Array-like Object.
+Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if Iterable or Array-like Object.
 
@@ -398,3 +463,3 @@ ### getIterator
 
-Similar to `getIterator()`, this method returns a new Iterator given an
+Similar to [getIterator](#getiterator), this method returns a new Iterator given an
 Iterable. However it will also create an Iterator for a non-Iterable
@@ -412,3 +477,3 @@ Array-like collection, such as Array in a non-ES2015 environment.
 
--   `collection` **([Iterable](#iterable)&lt;T> | {length: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)})** An Iterable or Array-like object to produce an Iterator.
+-   `collection` **([Iterable](#iterable)&lt;T> | {length: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)})** An Iterable or Array-like object to produce an Iterator.
 
@@ -450,4 +515,4 @@ **Examples**
 
--   `collection` **([Iterable](#iterable)&lt;T> | {length: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)})** The Iterable or array to iterate over.
--   `callback` **function (T, [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** Function to execute for each iteration, taking up to three arguments
+-   `collection` **([Iterable](#iterable)&lt;T> | {length: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)})** The Iterable or array to iterate over.
+-   `callback` **function (T, [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number), [object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))** Function to execute for each iteration, taking up to three arguments
 -   `thisArg`  Optional. Value to use as `this` when executing `callback`.
@@ -477,10 +542,11 @@
 
-### AsyncIterator
+### AsyncIterable
 
-[AsyncIterator](https://tc39.github.io/proposal-async-iteration/)
-is a _protocol_ which describes a standard way to produce and consume an
-asynchronous sequence of values, typically the values of the AsyncIterable
-represented by this AsyncIterator.
+-   **See: [Async Iteration Proposal](https://tc39.github.io/proposal-async-iteration/#sec-asynciterable-interface)**
 
-AsyncIterator is similar to Observable or Stream.
+[AsyncIterable](https://tc39.github.io/proposal-async-iteration/#sec-asynciterable-interface)
+is a _protocol_ which when implemented allows a JavaScript object to define
+an asynchronous iteration behavior, such as what values are looped over in
+a [`for-await-of`](https://tc39.github.io/proposal-async-iteration/#sec-for-in-and-for-of-statements)
+loop or `iterall`'s [forAwaitEach](#forawaiteach) function.
 
@@ -490,27 +556,18 @@ While described as a proposed addition to the [ES2017 version of JavaScript](https://tc39.github.io/proposal-async-iteration/)
 
-Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
+### AsyncIterator
 
-**Properties**
+-   **See: [Async Iteration Proposal](https://tc39.github.io/proposal-async-iteration/#sec-asynciterator-interface)**
 
--   `next` **function (): [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;{value: T, done: [boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)}>** A method which produces a Promise which resolves to either the next value
-      in a sequence or a result where the `done` property is `true` indicating
-      the end of the sequence of values. It may also produce a Promise which
-      becomes rejected, indicating a failure.
+[AsyncIterator](https://tc39.github.io/proposal-async-iteration/#sec-asynciterator-interface)
+is a _protocol_ which describes a standard way to produce and consume an
+asynchronous sequence of values, typically the values of the
+[AsyncIterable](#asynciterable) represented by this [AsyncIterator](#asynciterator).
 
-### AsyncIterable
+AsyncIterator is similar to Observable or Stream. Like an [Iterator](#iterator) it
+also as a `next()` method, however instead of an IteratorResult,
+calling this method returns a [Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise) for a IteratorResult.
 
-AsyncIterable is a _protocol_ which when implemented allows a JavaScript
-object to define their asynchronous iteration behavior, such as what values
-are looped over in a `for-await-of` loop or `iterall`'s `forAwaitEach`
-function.
-
 While described as a proposed addition to the [ES2017 version of JavaScript](https://tc39.github.io/proposal-async-iteration/)
 it can be utilized by any version of JavaScript.
 
-Type: [Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)
-
-**Properties**
-
--   `Symbol.asyncIterator` **function (): [AsyncIterator](#asynciterator)&lt;T>** A method which produces an AsyncIterator for this AsyncIterable.
-
 ### $$asyncIterator
@@ -525,3 +582,3 @@
 `Symbol.asyncIterator`, but do not use it for accessing existing Iterables,
-instead use `getAsyncIterator()` or `isAsyncIterable()`.
+instead use [getAsyncIterator](#getasynciterator) or [isAsyncIterable](#isasynciterable).
 
@@ -542,11 +599,11 @@ **Examples**
     next () {
-      return new Promise(function (resolve) {
+      return new Promise(resolve => {
         if (this.num >= this.to) {
           resolve({ value: undefined, done: true })
         } else {
-          setTimeout(function () {
+          setTimeout(() => {
             resolve({ value: this.num++, done: false })
           }, 1000)
         }
-      }
+      })
     }
@@ -579,3 +636,3 @@ }
 
-Returns **[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if AsyncIterable.
+Returns **[boolean](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean)** true if AsyncIterable.
 
@@ -630,3 +687,3 @@ ### getAsyncIterator
 
-Similar to `getAsyncIterator()`, this method returns a new AsyncIterator
+Similar to [getAsyncIterator](#getasynciterator), this method returns a new AsyncIterator
 given an AsyncIterable. However it will also create an AsyncIterator for a
@@ -649,3 +706,3 @@ non-async Iterable as well as non-Iterable Array-like collection, such as
 
--   `source` **([AsyncIterable](#asynciterable)&lt;T> | [Iterable](#iterable)&lt;T> | {length: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)})** An AsyncIterable, Iterable, or Array-like object to produce an Iterator.
+-   `source` **([AsyncIterable](#asynciterable)&lt;T> | [Iterable](#iterable)&lt;T> | {length: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)})** An AsyncIterable, Iterable, or Array-like object to produce an Iterator.
 
@@ -672,3 +729,3 @@ **Examples**
 
-Use `forAwaitEach` where you would expect to use a `for-await-of` loop.
+Use `forAwaitEach` where you would expect to use a [for-await-of](https://tc39.github.io/proposal-async-iteration/#sec-for-in-and-for-of-statements) loop.
 
@@ -684,4 +741,4 @@ Similar to [Array#forEach][], the `callback` function accepts three
 
--   `source` **([AsyncIterable](#asynciterable)&lt;T> | [Iterable](#iterable)&lt;([Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;T> | T)> | {length: [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number)})** The AsyncIterable or array to iterate over.
--   `callback` **function (T, [number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number), [object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object))** Function to execute for each iteration, taking up to three arguments
+-   `source` **([AsyncIterable](#asynciterable)&lt;T> | [Iterable](#iterable)&lt;([Promise](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise)&lt;T> | T)> | {length: [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number)})** The AsyncIterable or array to iterate over.
+-   `callback` **function (T, [number](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number), [object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object))** Function to execute for each iteration, taking up to three arguments
 -   `thisArg`  Optional. Value to use as `this` when executing `callback`.
@@ -688,0 +745,0 @@

No alert changes

Improved metrics

Total package byte prevSize

62786

increased by3.27%

Number of lines in readme file

809

increased by7.58%

Worsened metrics

Dev dependency count

6

increased by20%

Lines of code

710

decreased by-0.14%

No dependency changes