iterall - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

index.d.ts

@@ -15,2 +15,4 @@ /**
 
+  export function isArrayLike(obj: any): boolean
+
   export function isCollection(obj: any): boolean
@@ -21,9 +23,9 @@
 
-  export function getIteratorMethod(iterable: Iterable<TValue>): () => Iterator<TValue>
+  export function getIteratorMethod<TValue>(iterable: Iterable<TValue>): () => Iterator<TValue>
   export function getIteratorMethod(iterable: any): void | () => Iterator<any>
 
-  export function forEach<TCollection extends Iterable<TValue>>(collection: TCollection, callbackFn: (value: TValue, index: number, collection: TCollection) => any, thisArg?: any): void
+  export function forEach<TValue, TCollection extends Iterable<TValue>>(collection: TCollection, callbackFn: (value: TValue, index: number, collection: TCollection) => any, thisArg?: any): void
   export function forEach<TCollection extends { length: number }>(collection: TCollection, callbackFn: (value: any, index: number, collection: TCollection) => any, thisArg?: any): void
 
-  export function createIterator(collection: Iterable<TValue>): Iterator<TValue>
+  export function createIterator<TValue>(collection: Iterable<TValue>): Iterator<TValue>
   export function createIterator(collection: { length: number }): Iterator<any>
@@ -30,0 +32,0 @@ export function createIterator(collection: any): void | Iterator<any>

index.js

@@ -15,32 +15,42 @@ /**
 /**
- * A property name to be used as the name of an Iterable's method reponsible
+ * A property name to be used as the name of an Iterable's method responsible
  * for producing an Iterator. Typically represents the value `Symbol.iterator`.
  *
  * `Symbol` is defined in ES2015 environments, however some transitioning
- * JavaScript environments, such as older versions of Node define Symbol, but
+ * JavaScript environments, such as older versions of Node define `Symbol`, but
  * do not define `Symbol.iterator`. Older versions of Mozilla Firefox,
  * which originally introduced the Iterable protocol, used the string
- * value `"@@iterator"`. This string value is used when Symbol.iterator is
+ * value `"@@iterator"`. This string value is used when `Symbol.iterator` is
  * not defined.
  *
  * Use `$$ITERATOR` for defining new Iterables instead of `Symbol.iterator`,
- * but do not use it for accessing existing Iterables, instead use `getIterator`
- * or `isIterable`.
+ * but do not use it for accessing existing Iterables, instead use
+ * `getIterator()` or `isIterable()`.
  *
  * @example
  *
- * var $$ITERABLE = require('iterall').$$ITERABLE
+ * var $$ITERATOR = require('iterall').$$ITERATOR
  *
- * function Counter(to) {
+ * function Counter (to) {
  *   this.to = to
- *   this.num = 0
  * }
  *
  * Counter.prototype[$$ITERATOR] = function () {
- *   if (this.num >= this.to) {
- *     return { value: undefined, done: true }
+ *   return {
+ *     to: this.to,
+ *     num: 0,
+ *     next () {
+ *       if (this.num >= this.to) {
+ *         return { value: undefined, done: true }
+ *       }
+ *       return { value: this.num++, done: false }
+ *     }
  *   }
- *   return { value: this.num++ }
  * }
  *
+ * var counter = new Counter(3)
+ * for (var number of counter) {
+ *   console.log(number) // 0 ... 1 ... 2
+ * }
+ *
  * @type {Symbol|string}
@@ -53,3 +63,3 @@ */
  * Returns true if the provided object implements the Iterator protocol via
- * either implementing Symbol.iterator or '@@iterator' method.
+ * either implementing a `Symbol.iterator` or `"@@iterator"` method.
  *
@@ -61,7 +71,9 @@ * @example
  * isIterable('ABC') // true
+ * isArrayLike({ length: 1, 0: 'Alpha' }) // false
  * isIterable({ key: 'value' }) // false
+ * isIterable(new Map()) // true
  *
- * @param {*} obj
- *   A value which might be implement the Iterable protocol.
- * @return {boolean}
+ * @param obj
+ *   A value which might implement the Iterable protocol.
+ * @return {boolean} true if Iterable.
  */
@@ -74,11 +86,32 @@ function isIterable (obj) {
 /**
+ * Returns true if the provided object implements the Array-like protocol via
+ * defining a positive-integer `length` property.
+ *
+ * @example
+ *
+ * var isArrayLike = require('iterall').isArrayLike
+ * isArrayLike([ 1, 2, 3 ]) // true
+ * isArrayLike('ABC') // true
+ * isArrayLike({ length: 1, 0: 'Alpha' }) // true
+ * isArrayLike({ key: 'value' }) // false
+ * isArrayLike(new Map()) // false
+ *
+ * @param obj
+ *   A value which might implement the Array-like protocol.
+ * @return {boolean} true if Array-like.
+ */
+function isArrayLike (obj) {
+  var length = obj != null && obj.length
+  return typeof length === 'number' && length >= 0 && length % 1 === 0
+}
+exports.isArrayLike = isArrayLike
+
+/**
  * Returns true if the provided object is an Object (i.e. not a string literal)
- * and is either "Array-like" due to having a numeric `length` property, or is
- * Iterable.
+ * and is either Iterable or Array-like.
  *
- * This may be used in place of `Array.isArray(obj)` to determine if an object
- * can be iterated-over. It always excludes string literals and includes Arrays
- * (regardless of if it is Iterable). It also includes other Array-like objects
- * such as NodeList, TypedArray, and Buffer. It also includes any Object which
- * implements the Iterable protocol.
+ * This may be used in place of [Array.isArray()][isArray] to determine if an
+ * object should be iterated-over. It always excludes string literals and
+ * includes Arrays (regardless of if it is Iterable). It also includes other
+ * Array-like objects such as NodeList, TypedArray, and Buffer.
  *
@@ -88,2 +121,10 @@ * @example
  * var isCollection = require('iterall').isCollection
+ * isCollection([ 1, 2, 3 ]) // true
+ * isCollection('ABC') // false
+ * isCollection({ length: 1, 0: 'Alpha' }) // true
+ * isArrayLike({ key: 'value' }) // false
+ * isArrayLike(new Map()) // true
+ *
+ * @example
+ *
  * var forEach = require('iterall').forEach
@@ -96,8 +137,8 @@ * if (isCollection(obj)) {
  *
- * @param {*} obj
+ * @param obj
  *   An Object value which might implement the Iterable or Array-like protocols.
- * @return {boolean}
+ * @return {boolean} true if Iterable or Array-like Object.
  */
 function isCollection (obj) {
-  return Object(obj) === obj && (typeof obj.length === 'number' || isIterable(obj))
+  return Object(obj) === obj && (isArrayLike(obj) || isIterable(obj))
 }
@@ -122,3 +163,3 @@ exports.isCollection = isCollection
  *   An Iterable object which is the source of an Iterator.
- * @return {Iterator<T>}
+ * @return {Iterator<T>} new Iterator instance.
  */
@@ -152,3 +193,3 @@ function getIterator (iterable) {
  *   An Iterable object which defines an `@@iterator` method.
- * @return {function(): Iterator<T>}
+ * @return {function(): Iterator<T>} `@@iterator` method.
  */
@@ -166,14 +207,18 @@ function getIteratorMethod (iterable) {
 /**
- * Given an object which is either Array-like (by having a numeric length
- * property) or implements the Iterable protocol, iterate over it, calling the
- * `callback` at each iteration.
+ * Given an object which either implements the Iterable protocol or is
+ * Array-like, iterate over it, calling the `callback` at each iteration.
  *
- * Similar to Array#forEach, the `callback` function accepts three arguments,
- * and is provided with `thisArg` as the calling context.
+ * Use `forEach` where you would expect to use a `for ... of` loop in ES6.
+ * However `forEach` adheres to the behavior of [Array#forEach][] described in
+ * the ECMAScript specification, skipping over "holes" in Array-likes. It will
+ * also delegate to a `forEach` method on `collection` if one is defined,
+ * ensuring native performance for `Arrays`.
  *
- * `forEach` adheres to the behavior described in the ECMAScript specification,
- * skipping over "holes" in Arrays and Array-likes.
+ * Similar to [Array#forEach][], the `callback` function accepts three
+ * arguments, and is provided with `thisArg` as the calling context.
  *
  * Note: providing an infinite Iterator to forEach will produce an error.
  *
+ * [Array#forEach]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach
+ *
  * @example
@@ -183,10 +228,22 @@ *
  *
- * forEach(myIterable, function (value, index) {
- *   console.log(value, index)
+ * forEach(myIterable, function (value, index, iterable) {
+ *   console.log(value, index, iterable === myIterable)
  * })
  *
+ * @example
+ *
+ * // ES6:
+ * for (let value of myIterable) {
+ *   console.log(value)
+ * }
+ *
+ * // Any JavaScript environment:
+ * forEach(myIterable, function (value) {
+ *   console.log(value)
+ * })
+ *
  * @template T the type of each iterated value
  * @param {Iterable<T>|Array<T>} collection
  *   The Iterable or array to iterate over.
- * @param {function(T, number, [object])} callback
+ * @param {function(T, number, object)} callback
  *   Function to execute for each iteration, taking up to three arguments
@@ -214,3 +271,3 @@ * @param [thisArg]
       }
-    } else if (typeof collection.length === 'number') {
+    } else if (isArrayLike(collection)) {
       for (; i < collection.length; i++) {
@@ -227,3 +284,3 @@ if (collection.hasOwnProperty(i)) {
 /**
- * Similar to `getIterator(obj)`, this method returns a new Iterator given an
+ * Similar to `getIterator()`, this method returns a new Iterator given an
  * Iterable. However it will also create an Iterator for a non-Iterable
@@ -253,3 +310,3 @@ * Array-like collection, such as Array in a non-ES2015 environment.
  *   An Iterable or Array-like object to produce an Iterator.
- * @return {Iterator<T>}
+ * @return {Iterator<T>} new Iterator instance.
  */
@@ -262,4 +319,4 @@ function createIterator (collection) {
     }
-    if (typeof collection.length === 'number') {
-      return new ArraylikeIterator(collection)
+    if (isArrayLike(collection)) {
+      return new ArrayLikeIterator(collection)
     }
@@ -272,3 +329,3 @@ }
 // Array-like, this simple Iterator is created.
-function ArraylikeIterator (obj) {
+function ArrayLikeIterator (obj) {
   this._o = obj
@@ -279,3 +336,3 @@ this._i = 0
 // Note: all Iterators are themselves Iterable.
-ArraylikeIterator.prototype[$$ITERATOR] = function () {
+ArrayLikeIterator.prototype[$$ITERATOR] = function () {
   return this
@@ -286,3 +343,3 @@ }
 // each value in the Array-like object in order of their indicies.
-ArraylikeIterator.prototype.next = function () {
+ArrayLikeIterator.prototype.next = function () {
   if (this._o === void 0 || this._i >= this._o.length) {
@@ -289,0 +346,0 @@ this._o = void 0

package.json

 {
   "name": "iterall",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Minimal zero-dependency utilities for using JavaScript Iterables in all environments.",
   "main": "index.js",
   "scripts": {
-    "test": "npm run lint && npm run testonly",
+    "test": "npm run lint && npm run testonly && npm run testdocs",
     "lint": "standard --verbose index.js test.js",
     "testonly": "nyc --check-coverage --statements 100 node test.js",
-    "docs": "documentation readme -g -s API",
+    "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",
     "travis": "npm run test && nyc report --reporter=text-lcov | coveralls"
@@ -21,3 +22,2 @@ },
     "index.d.ts",
-    "README",
     "LICENSE"
@@ -24,0 +24,0 @@ ],

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

15722

increased by14.64%

Lines of code

343

increased by19.93%

No dependency changes