seqit - npm Package Compare versions

Comparing version 1.0.0 to 1.0.1

package.json

 {
   "name": "seqit",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "Iterate over anything, in a style reminiscent of C++.",
@@ -5,0 +5,0 @@ "main": "seqit.js",

README.md

@@ -1,9 +0,10 @@
-# seqit - Sequential Iterator
+# seqit
+## Sequential Iterator
 
-Sometimes the JavaScript `forEach` loop is not dynamic enough, especially when you have to break out of the loop early, visit elements in a different order, or modify the object you are iterating over in-place. And functions like `map` or `reduce` and many of the functions provided by a library like lo-dash can be easily accomplished using a traditional loop without extra abstraction. This is where `seqit` comes in.
+Sometimes the JavaScript `forEach` loop is not dynamic enough, especially when you have to break out of the loop early, visit elements in a different order, or modify the object you are iterating over in-place. 
 
-`seqit` is a general-purpose iterator module incompatible with both Node.js and the browser, designed to provide a simple method of looping over an array or object using `for` or `while`, inspired by C++ iterators. You can wrap any array or object with the `seqit` function and iterate over its elements or keys. You can also edit the values you're iterating over in-place. `seqit` does not copy any data; it simply binds to an existing structure.
+`seqit` is a general-purpose iterator module compatible with both Node.js and the browser, designed to provide a simple method of looping over an array or object using `for` or `while`, inspired by C++ iterators. You can wrap any array or object with the `seqit` function and iterate over its elements or keys. You can also edit the values you're iterating over in-place. `seqit` does not copy any data; it simply binds to an existing structure.
 
-## Usage
-```
+## Examples
+```js
 var seqit = require('seqit');
@@ -16,3 +17,3 @@ var array = [5, 4, 3, 5, 6, 7, 8, 9, 10];
 Equivalently, in a while loop,
-```
+```js
 var it = seqit(array)
@@ -24,3 +25,3 @@ while (it.hasNext) {
 Looping over an object:
-```
+```js
 var obj = { a: 5, b: 'woop' };
@@ -32,7 +33,7 @@ for (var it = seqit(obj); it !== it.end; it.next) {
 Editing an object in place:
-```
+```js
 var obj = { a: 'woop', b: 'doop' }
 for (var it = seqit(obj); it !== it.end; it.next) {
-  it().key = it().key + 'a';
-  it().value = it().value + 'a';
+  it().key += 'a';
+  it().value += 'a';
 }
@@ -43,3 +44,3 @@ console.log(obj);
 Editing an array in place:
-```
+```js
 var array = [5, 4, 3, 5, 6, 7, 8, 9, 10];
@@ -53,3 +54,3 @@ for (var it = seqit(array); it !== it.end; it.next) {
 Using the iteration index:
-```
+```js
 var array = [5, 4, 3, 5, 6, 7, 8, 9, 10];
@@ -62,10 +63,95 @@ for (var it = seqit(array); it !== it.end; it.next) {
 You can also set `it.index` if you want to manually change where you are in the loop.
-Using `it.begin`
+
+More examples to come...
+
+## Documentation
+
+- `seqit(*val, config)`
+  Function that returns an `Iterator` instance. If the first arguments are numbers, `seqit` will return an `Iterator` that iterates over a range of numbers. The first number is inclusive and the second is exclusive. You can also pass a single number to start from 0 implicitly, and you can pass a third number to indicate the step size. For example, `seqit(7)` will iterate over values 0 through 6, `seqit(1, 7)` will iterate over values 1 through 6, and `seqit(1, 7, 2)` will iterate over values 1, 3, and 5. If you pass an object to `seqit` it will return an iterator that iterates over the key value pairs of an object. If you pass an array to `seqit` the `Iterator` will iterate over each element. The last argument to `seqit` can be a configuration object, where you can pass `{ reversed: true, step: number }` to specify that you want to iterate in reverse order or set the step size.
+
+- `Iterator(val)`
+  If you call the iterator with no argument, it will return the current element being iterated over. If you pass a value in, it will set the current element to that value.
+
+- `Iterator.size`
+  Returns the amount of elements in the collection being iterated over.
+
+- `Iterator.size = val`
+  Manually set the size of collection being iterated over.
+
+- `Iterator.end`
+  A function that returns the last element in the collection, or the first if you are in reverse order. If you have reached the end of the iteration this function will be equal to the `Iterator` itself.
+
+- `Iterator.end = val`
+  Sets the last element of the array to `val`, or the first if you are in reverse order.
+
+- `Iterator.begin`
+  A function that returns the first element in the collection, or the last element if you are in reverse order. If you are at the beginning of the iteration this function will be equal to the `Iterator` itself.
+
+- `Iterator.begin = val`
+  Sets the first element of the array to `val`, or the last if you are in reverse order.
+
+- `Iterator.reversed`
+  Equal to `true` if you are in reverse order, false otherwise.
+
+- `Iterator.reversed = true/false`
+  Set the order of the iteration.
+
+- `Iterator.step`
+  Accessing this property will advance the iteration by one step.
+
+- `Iterator.step = n`
+  This will set the step size of the iteration to `n`.
+
+- `Iterator.step(n)`
+  This will advance the iteration by `n` step sizes.
+
+- `Iterator.back`
+  Accessing this property will advance the iteration by one step in the direction opposite to the iteration order.
+
+- `Iterator.back(n)`
+  This will advance the iteration by `n` step sizes in the direction opposite to the iteration order.
+
+- `Iterator.index`
+  Equal to the current index in the array being iterated over.
+
+- `Iterator.index = val`
+  Set the current index of the iteration.
+
+- `Iterator.next`
+  Acceessing this property returns the current element then advances the iteration forward by one step.
+
+- `Iterator.prev`
+  Accessing this property returns the current element then advances the iteration backward by one step.
+
+- `Iterator.hasNext`
+  Will be `true` if it is possible to call `Iterator.next`, `false` otherwise.
+
+- `Iterator.hasPrev`
+  Will be `true` if it is possible to call `Iterator.prev`, `false` otherwise.
+
+- `Iterator.reset`
+  Accessing this property will reset the iteration to the state it was in when the `Iterator` was constructed.
+
+- `Iterator.find(function or value)`
+  This will advance the iteration to the next element where the function you pass in returns `true`. If you are iterating over an array the function receives as its arguments: the current element, the current index, and the whole array, in that order. If you are iterating over an object the function is passed four arguments: the current value, the current key, the current index, and the whole object. If you pass `find` a value instead of a function, it will find the next element where the value is equal to the supplied value. If you pass an object as the value, `find` will iterate until it encounters an object that contains at least those keys and associated values. `find` will return `true` if it found a match, and `false` if it reached the end of the iteration without finding a match.
+
+- `Iterator.select(function or value)`
+  This function takes the same type of parameter as `find`, but it changes the behavior of the iteration so that it only visits matching elements. If you access `Iterator.reset` or call `Iterator.select()` with no argument it resets this behavior. `select` returns the iterator itself.
+
+Examples of `select` and `find`:
+```js
+var it = seqit([5, 1, 4, 2, 3]);
+while (it.find(function (v) { return v > 3; })) {
+  console.log(it());
+}
+// console: '5' '4'
 ```
-for (var it = seqit(array); it !== it.end; it.next) {
-  if (it.begin === it) {
-    console.log('iterating over the first element of the array');
-  }
+or equivalently:
+```
+for (var it = seqit([5, 1, 4, 2, 3]).select(function (v) { return v > 3; }); it !== it.end; it.next) {
+  console.log(it());
 }
 ```
-More examples to come...
+
+## License
+MIT

seqit.js

 (function () {
   var root = this;
   function seqit () {
-    var reversed = false, config = {}, args = [].slice.call(arguments), stepSize = 1, obj;
+    var reversed = false, config = {}, args = [].slice.call(arguments), stepSize = 1, obj, selectFunction;
     if (args.length > 1 && typeof args[args.length - 1] === 'object' && !Array.isArray(args[args.length - 1])) {
@@ -17,2 +17,5 @@ config = args[args.length - 1];
       }
+      if (typeof config.select !== 'undefined') {
+        selectFunction = config.select
+      }
     }
@@ -39,5 +42,10 @@ switch (typeof args[0]) {
           return (function (arr) {
+            var searchedFirst = false;
             var step = stepSize;
             var index = (reversed ? (arr.length - 1) : 0);
-            var factory = Propertizer(Iterator);
+            var selector = selectFunction;
+            var reversedCopy = reversed;
+            delete Iterator.prototype;
+            var IteratorPrototype = Object.create(Function.prototype);
+            var factory = Propertizer(IteratorPrototype);
             factory
@@ -83,11 +91,15 @@ .prop('size')
                 .get(function () {
+                  if (typeof selector !== 'undefined') {
+                    for (var i = 0; i < step; ++i) {
+                      this.find(selector);
+                    }
+                    return this.index;
+                  }
+                  var saved = index, self = this;
                   if (reversed) index -= step;
                   else index += step;
                   return function (v) {
-                    if (reversed) {
-                      index += step;
-                      index -= v;
-                    } else {
-                      index -= step;
-                      index += v;
+                    index = saved;
+                    for (var i = 0; i < v; ++i) {
+                      self.step;
                     }
@@ -103,12 +115,18 @@ return index;
                 .get(function () {
+                  if (selector) {
+                    this.reversed = Boolean(this.reversed ^ 1);
+                    for (var i = 0; i < step; ++i) {
+                      this.find(selector);
+                    }
+                    this.reversed = Boolean(this.reversed ^ 1);
+                    return this.index;
+                  }
+                  var saved = index, self = this;
                   if (reversed) index += step;
                   else index -= step;
                   return function (v) {
+                    index = saved;
                     if (typeof v === 'number') {
-                      if (reversed) {
-                        index -= step;
-                        index += v;
-                      } else {
-                        index += step;
-                        index -= v;
+                      for (var i = 0; i < v; ++i) {
+                        self.back;
                       }
@@ -126,2 +144,3 @@ }
                   index = v;
+                  searchedFirst = false;
                 })
@@ -159,4 +178,73 @@ .prop('prev')
             .apply();
+            IteratorPrototype.find = find;
+            IteratorPrototype.select = select;
+            Iterator.__proto__ = IteratorPrototype;
             return Iterator;
-            function reset () { index = 0; step = 1; return 0; }
+            function move(n) {
+              if (reversed) index -= n;
+              else index += n;
+            }
+            function select(fn) {
+              selector = fn;
+              this.find(fn);
+              return this;
+            }
+            function find (fn) {
+              if (this !== this.end) {
+                if (searchedFirst) move(1);
+                else searchedFirst = true;
+              }
+              switch (typeof fn) {
+                case 'function':
+                  if (!obj) {
+                    while (this !== this.end) {
+                      if (fn(this(), this.index, arr)) return true;
+                      move(1);
+                    }
+                  } else {
+                    while (this !== this.end) {
+                      if (fn(this().value, this().key, this.index, obj)) return true;
+                      move(1);
+                    }
+                  }
+                  return false;
+                  break;
+                case 'object':
+                  if (!obj) {
+                    while (this !== this.end) {
+                      if (propertyMatch(this(), fn)) return true;
+                      move(1);
+                    }
+                  } else {
+                    while (this !== this.end) {
+                      if (propertyMatch(this().value, fn)) return true;
+                      move(1);
+                    }
+                  }
+                  return false;
+                  break;
+                default:
+                  if (!obj) {
+                    while (this !== this.end) {
+                      if (this() === fn) return true;
+                      move(1);
+                    }
+                  } else {
+                    while (this !== this.end) {
+                      if (this().value === fn) return true;
+                      move(1);
+                    }
+                  }
+                  return false;
+                  break;
+              } 
+            }
+            function reset () {
+              reversed = reversedCopy;
+              index = (reversed ? arr.length - 1 : 0);
+              step = stepSize;
+              selector = void 0;
+              searchedFirst = false;
+              return 0;
+            }
             function Iterator(v) {
@@ -194,2 +282,13 @@ if (index < 0 || index >= arr.length) throw RangeError('Out of range.');
   }
+  function propertyMatch(a, b) {
+    if (typeof a !== typeof b) return false;
+    if (typeof a === 'object') {
+      var keys = Object.getOwnPropertyNames(b);
+      for (var i = 0; i < keys.length; ++i) {
+        if (!propertyMatch(a[keys[i]], b[keys[i]])) return false;
+      }
+      return true;
+    }
+    return a === b;
+  }
   function ellipses(value, length) {
@@ -196,0 +295,0 @@ if (!length) length = 20;

seqit.min.js

@@ -1,1 +0,1 @@
-(function(){function t(){var e,u=!1,i={},s=[].slice.call(arguments),p=1;switch(s.length>1&&"object"==typeof s[s.length-1]&&!Array.isArray(s[s.length-1])&&(i=s[s.length-1],s.splice(s.length-1,1),"boolean"==typeof i.reversed&&(u=i.reversed),"number"==typeof i.step&&(p=i.step),"object"!=typeof i.obj||Array.isArray(i.obj)||(e=i.obj)),typeof s[0]){case"string":return t([].slice.call(s[0]),i);case"number":var f=0,c=s[0],h=1;if(s.length>1){if("number"!=typeof s[1])throw TypeError("Ending range value must be a number.");c=s[1],f=s[0]}if(s.length>2){if("number"!=typeof s[2])throw TypeError("Step size must be a number.");h=s[2]}return t(o(f,c,h),i);case"object":return Array.isArray(s[0])?function(t){function n(){return s=0,i=1,0}function o(n){if(0>s||s>=t.length)throw RangeError("Out of range.");return"undefined"==typeof n?t[s]:void(e?t[s].value=n:t[s]=n)}var i=p,s=u?t.length-1:0,f=r(o);return f.prop("size").get(function(){return t.length}).set(function(e){t.length=e}).prop("end").get(function(){return(u?0>s:s>=t.length)?o:function(n){return"undefined"==typeof n?t[u?0:t.length-1]:(e?t[u?0:t.length-1].value=n:t[u?0:t.length-1]=n,n)}}).set(function(n){e?t[u?0:t.length-1].value=n:t[u?0:t.length-1]=n}).prop("reversed").get(function(){return u}).set(function(t){if("boolean"!=typeof t)throw TypeError("Must be a boolean.");u=t}).prop("begin").get(function(){return(u?s!==t.length-1:s)?function(n){return"undefined"==typeof n?t[u?t.length-1:0]:(e?t[u?t.length-1:0].value=n:t[u?t.length-1:0]=n,n)}:o}).set(function(n){e?t[u?t.length-1:0].value=val:t[u?t.length-1:0]=n}).prop("step").get(function(){return u?s-=i:s+=i,function(t){return u?(s+=i,s-=t):(s-=i,s+=t),s}}).set(function(t){if("number"!=typeof t)throw TypeError("Step size must be a number.");i=t}).prop("back").get(function(){return u?s+=i:s-=i,function(t){return"number"==typeof t&&(u?(s-=i,s+=t):(s+=i,s-=t)),s}}).prop("index").get(function(){return s}).set(function(t){if("number"!=typeof t||t%1!==0)throw TypeError("Index must be an integer.");s=t}).prop("prev").get(function(){u&&0>s&&(s=0),!u&&s>=t.length&&(s=t.length-1);var e=this();return this.back,e}).prop("next").get(function(){u&&s>=t.length&&(s=t.length-1),!u&&0>s&&(s=0);var e=this();return this.step,e}).prop("hasNext").get(function(){return u?s>=0:s<t.length}).prop("hasPrev").get(function(){return u?s<t.length:s>=0}).prop("reset").get(n).set(n).prop("current").get(function(){return this()}).set(function(t){return this(t)}).apply(),o}(s[0]):function(e){return t(Object.getOwnPropertyNames(e).map(function(t){return n(e,t)}),i)}(s[0]);default:throw TypeError("Cannot iterate over a "+typeof s[0]+".")}}function e(t,e){e||(e=20);var n=JSON.stringify(t);if("string"==typeof t&&(n="'"+n.substr(1,n.length-2).replace(/\\"/g)+"'"),n.length>e)switch(n=n.substr(0,e-5)+"...",typeof t){case"object":n+=Array.isArray(t)?"]":"}";break;case"string":n+="'"}return n}function n(t,e){if(!(this instanceof n))return new n(t,e);var o=e;r(this).prop("key").set(function(n){if(n!==e){var r=t[e];delete t[e],t[n]=r,o=n}}).get(function(){return o}).prop("value").set(function(e){e!==t[o]&&(t[o]=e)}).get(function(){return t[o]}).apply()}function r(t){return this instanceof r?(this.obj=t,void(this.props={})):new r(t)}function o(t,e,n){for(var r=[],o=t;e>o;o+=n)r.push(o);return r}var u=this;"undefined"!=typeof exports?"undefined"!=typeof module&&(exports=module.exports=t):u.seqit=t,n.prototype.inspect=function(){return"{[Accessor] key: "+e(this.key)+", value: "+e(this.value)+" }"},r.prototype={prop:function(t){return this.props[t]={},this.current=t,this},set:function(t){return this.props[this.current].set=t,this},get:function(t){return this.props[this.current].get=t,this},apply:function(){return Object.getOwnPropertyNames(this.props).forEach(function(t){Object.defineProperty(this.obj,t,{get:this.props[t].get,set:this.props[t].set})},this),this}}}).call(this);
+(function(){function t(){var r,s,u=!1,f={},h=[].slice.call(arguments),p=1;switch(h.length>1&&"object"==typeof h[h.length-1]&&!Array.isArray(h[h.length-1])&&(f=h[h.length-1],h.splice(h.length-1,1),"boolean"==typeof f.reversed&&(u=f.reversed),"number"==typeof f.step&&(p=f.step),"object"!=typeof f.obj||Array.isArray(f.obj)||(r=f.obj),"undefined"!=typeof f.select&&(s=f.select)),typeof h[0]){case"string":return t([].slice.call(h[0]),f);case"number":var c=0,a=h[0],l=1;if(h.length>1){if("number"!=typeof h[1])throw TypeError("Ending range value must be a number.");a=h[1],c=h[0]}if(h.length>2){if("number"!=typeof h[2])throw TypeError("Step size must be a number.");l=h[2]}return t(o(c,a,l),f);case"object":return Array.isArray(h[0])?function(t){function n(t){u?g-=t:g+=t}function o(t){return y=t,this.find(t),this}function f(i){switch(this!==this.end&&(a?n(1):a=!0),typeof i){case"function":if(r)for(;this!==this.end;){if(i(this().value,this().key,this.index,r))return!0;n(1)}else for(;this!==this.end;){if(i(this(),this.index,t))return!0;n(1)}return!1;case"object":if(r)for(;this!==this.end;){if(e(this().value,i))return!0;n(1)}else for(;this!==this.end;){if(e(this(),i))return!0;n(1)}return!1;default:if(r)for(;this!==this.end;){if(this().value===i)return!0;n(1)}else for(;this!==this.end;){if(this()===i)return!0;n(1)}return!1}}function h(){return u=d,g=u?t.length-1:0,l=p,y=void 0,a=!1,0}function c(e){if(0>g||g>=t.length)throw RangeError("Out of range.");return"undefined"==typeof e?t[g]:void(r?t[g].value=e:t[g]=e)}var a=!1,l=p,g=u?t.length-1:0,y=s,d=u;delete c.prototype;var v=Object.create(Function.prototype),b=i(v);return b.prop("size").get(function(){return t.length}).set(function(e){t.length=e}).prop("end").get(function(){return(u?0>g:g>=t.length)?c:function(e){return"undefined"==typeof e?t[u?0:t.length-1]:(r?t[u?0:t.length-1].value=e:t[u?0:t.length-1]=e,e)}}).set(function(e){r?t[u?0:t.length-1].value=e:t[u?0:t.length-1]=e}).prop("reversed").get(function(){return u}).set(function(t){if("boolean"!=typeof t)throw TypeError("Must be a boolean.");u=t}).prop("begin").get(function(){return(u?g!==t.length-1:g)?function(e){return"undefined"==typeof e?t[u?t.length-1:0]:(r?t[u?t.length-1:0].value=e:t[u?t.length-1:0]=e,e)}:c}).set(function(e){r?t[u?t.length-1:0].value=val:t[u?t.length-1:0]=e}).prop("step").get(function(){if("undefined"!=typeof y){for(var t=0;l>t;++t)this.find(y);return this.index}var e=g,r=this;return u?g-=l:g+=l,function(t){g=e;for(var n=0;t>n;++n)r.step;return g}}).set(function(t){if("number"!=typeof t)throw TypeError("Step size must be a number.");l=t}).prop("back").get(function(){if(y){this.reversed=Boolean(1^this.reversed);for(var t=0;l>t;++t)this.find(y);return this.reversed=Boolean(1^this.reversed),this.index}var e=g,r=this;return u?g+=l:g-=l,function(t){if(g=e,"number"==typeof t)for(var n=0;t>n;++n)r.back;return g}}).prop("index").get(function(){return g}).set(function(t){if("number"!=typeof t||t%1!==0)throw TypeError("Index must be an integer.");g=t,a=!1}).prop("prev").get(function(){u&&0>g&&(g=0),!u&&g>=t.length&&(g=t.length-1);var e=this();return this.back,e}).prop("next").get(function(){u&&g>=t.length&&(g=t.length-1),!u&&0>g&&(g=0);var e=this();return this.step,e}).prop("hasNext").get(function(){return u?g>=0:g<t.length}).prop("hasPrev").get(function(){return u?g<t.length:g>=0}).prop("reset").get(h).set(h).prop("current").get(function(){return this()}).set(function(t){return this(t)}).apply(),v.find=f,v.select=o,c.__proto__=v,c}(h[0]):function(e){return t(Object.getOwnPropertyNames(e).map(function(t){return n(e,t)}),f)}(h[0]);default:throw TypeError("Cannot iterate over a "+typeof h[0]+".")}}function e(t,r){if(typeof t!=typeof r)return!1;if("object"==typeof t){for(var n=Object.getOwnPropertyNames(r),i=0;i<n.length;++i)if(!e(t[n[i]],r[n[i]]))return!1;return!0}return t===r}function r(t,e){e||(e=20);var r=JSON.stringify(t);if("string"==typeof t&&(r="'"+r.substr(1,r.length-2).replace(/\\"/g)+"'"),r.length>e)switch(r=r.substr(0,e-5)+"...",typeof t){case"object":r+=Array.isArray(t)?"]":"}";break;case"string":r+="'"}return r}function n(t,e){if(!(this instanceof n))return new n(t,e);var r=e;i(this).prop("key").set(function(n){if(n!==e){var i=t[e];delete t[e],t[n]=i,r=n}}).get(function(){return r}).prop("value").set(function(e){e!==t[r]&&(t[r]=e)}).get(function(){return t[r]}).apply()}function i(t){return this instanceof i?(this.obj=t,void(this.props={})):new i(t)}function o(t,e,r){for(var n=[],i=t;e>i;i+=r)n.push(i);return n}var s=this;"undefined"!=typeof exports?"undefined"!=typeof module&&(exports=module.exports=t):s.seqit=t,n.prototype.inspect=function(){return"{[Accessor] key: "+r(this.key)+", value: "+r(this.value)+" }"},i.prototype={prop:function(t){return this.props[t]={},this.current=t,this},set:function(t){return this.props[this.current].set=t,this},get:function(t){return this.props[this.current].get=t,this},apply:function(){return Object.getOwnPropertyNames(this.props).forEach(function(t){Object.defineProperty(this.obj,t,{get:this.props[t].get,set:this.props[t].set})},this),this}}}).call(this);

test/test.js

@@ -47,2 +47,32 @@ var seqit = require('..'),
   });
+  it('can find elements', function () {
+    var fill = [];
+    var arr = [5, 1, 6, 2, 7];
+    var it = seqit(arr);
+    while (it.find(function (v) { return v > 4; })) {
+      fill.push(it());
+    }
+    expect(fill).to.eql([5, 6, 7]);
+  });
+  it('can search for an object', function () {
+    var arr = [{a: 6, b: 'woop'}, {a: 5, b: 'doop'}];
+    var fill = [];
+    for (var it = seqit(arr).select({ b: 'woop' }); it !== it.end; it.next) {
+      fill.push(it().b);
+    }
+    expect(fill).to.eql(['woop']);
+  });
+  it('can be reset in reversed order', function () {
+    var arr = [5, 3, 1];
+    var fill = [];
+    for (var it = seqit(arr, { reversed: true }); it !== it.end; it.next) {
+      fill.push(it());
+    }
+    it.reset;
+    for (; it !== it.end; it.next) {
+      fill.push(it());
+    }
+    arr.reverse();
+    expect(fill).to.eql(arr.concat(arr));
+  });
 });

No alert changes

Improved metrics

Total package byte prevSize

28772

53.97%

Lines of code

454

39.69%

Number of lines in readme file

152

130.3%

No dependency changes