iteration-typeguards

iteration-typeguards
====================


Installation
------------
Install with npm

npm install iteration-typeguards

Requirements
------------
This module assumes a javascript environment implementing ES6, as it defines iterators and
iterability based on the ES6 iteration protocols.

Module Contents
---------------
This module consists of two typeguard functions, isIterable and isIterator that accept
any javascript value as a single argument and return a boolean for whether or not that
value is a Iterable or an Iterator in the ES6 sense, respectively.

Usage with Typescript
---------------------
A typescript compiler --target argument of es6 should be used. Both of the functions
isIterable and isIterator are defined as typescript typeguards for the built-in
iterfaces: Iterable and Iterator, respectively.

$3

``typescript
import {isIterable} from "iteration-typeguards";

isIterable(5); // false
isIterable("oh hai"); // true
isIterable(null); // false
isIterable([1,2,3]); // true
isIterable(new Map([
["hi", 3],
[{water: true}, "summer"]]
)); // true
isIterable({
[Symbol.iterator]: function() {
return {
next: function() {
return 47;
},
done: false
}
}
}); // true
`

$3

`typescript
import {isIterator} from "iteration-typeguards";

isIterator(5); // false
isIterator("oh hai"); // false
isIterator("oh hai"[Symbol.iterator]());// true
isIterator(null); // false
isIterator([1,2,3]); // false
isIterator([1,2,3][Symbol.iterator]); // true
isIterator({
next: function() {
return 47;
},
done: false
}); // true
`

Usage without Typescript
------------------------
Usage without typescript in nodejs is very similar to the typescript examples above
without the type annotations. Since an ES6 environment is assumed, the import statements
above should work. The more traditional nodejs require statements shown below also work.

`javascript
var itGuards = require("iteration-typeguards");

itGuards.isIterable([1,2,3]) // true
itGuards.isIterator([1,2,3][Symbol.iterator]) // true
``

Contributions
-------------
If you come across a case in which these typeguards do not perform as expected, please
submit an issue (outlining the case) or a pull request (again, outlining the case and a
possible solution).

License
-------
MIT --- open source