src/modules/iteration.js
function objectIterator(obj, sort, kv = false) {
  let keys = Object.keys(obj);
  keys = typeof sort === 'function' ? keys.sort(sort) : keys.sort();
  let index = 0;

  return {
    next() {
      if (index < keys.length) {
        const k = keys[index++];
        const value = {};
        if (kv) {
          value.k = k;
          value.v = obj[k];
        } else {
          value[k] = obj[k];
        }
        return {
          value,
          done: false
        };
      }
      return {
        done: true
      };
    }
  };
}
function objectIterator(obj, sort, kv = false) {
  let keys = Object.keys(obj);
  keys = typeof sort === 'function' ? keys.sort(sort) : keys.sort();
  let index = 0;

  return {
    next() {
      if (index < keys.length) {
        const k = keys[index++];
        const value = {};
        if (kv) {
          value.k = k;
          value.v = obj[k];
        } else {
          value[k] = obj[k];
        }
        return {
          value,
          done: false
        };
      }
      return {
        done: true
      };
    }
  };
}
function objectIterator ( obj , sort , kv = false ) { let keys = Object . keys ( obj ) ; keys = typeof sort === 'function' ? keys . sort ( sort ) : keys . sort ( ) ; let index = 0 ; return { next ( ) { if ( index < keys . length ) { const k = keys [ index ++ ] ; const value = { } ; if ( kv ) { value . k = k ; value . v = obj [ k ] ; } else { value [ k ] = obj [ k ] ; } return { value , done : false } ; } return { done : true } ; } } ; }
Creates an iterator over objcts.

Objects are not generally iterable, as there is no defined order for an object, and each "element" of an object
actually has two values, unlike any other collection (a key and a property). However, it's tremendously useful to
be able to use at least some transformers with objects as well. This iterator adds support in two different
ways to make that possible.

The first is that a sort order is defined. Quite simply, it's done alphabetically by key. There is also an option -
through the second parameter `sort` - to provide a different sort function. This should be a function in the style
of `Array.prototype.sort`, where two parameters are compared and -1 is returned if the first is larger, 1 is returned
if the second is larger, and 0 is returned if they're equal. This is applied ONLY TO THE KEYS of the object. If you
wish to sort on values, consider iterating into an array and then sorting the elements by value.

In the public API, this sort function can only be passed through the `{@link module:xduce.iterator|iterator}`
function. If you  wish to use an object sorted in a non-default order, you should create an iterator out of it and
transform that iterator. For example:

| DEFAULT ORDER                        | CUSTOM ORDER                                         |
| ------------------------------------ | ---------------------------------------------------- |
| `var result = sequence(obj, xform);` | `var result = asObject(iterator(obj, sort), xform);` |

The second support feature is the alternative "kv-form" objects. A reasonable way to iterate over objects would be to
produce single-property objects, one per property on the original object (i.e., `{a: 1, b: 2}` would become two
elements: `{a: 1}` and `{b: 2}`). This is fine for straight iteration and reduction, but it can present a challenge
to use a transformer with. Consider this example code, which uppercases the key and adds one to the value.

```
function doObjectSingle(obj) {
var key = Object.keys(obj)[0];
var result = {};
result[key.toUpperCase()] = obj[key] + 1;
return result;
}
```

This is a little unwieldy, so the iterator provides for another kind of iteration. Setting the third parameter,
`kv`, to `true` (which is the default), objects will be iterated into two-property objects with `k` and `v` as the
property names. For example, `{a: 1, b: 2}` will become two elements: `{k: 'a', v: 1}` and `{k: 'b', v: 2}`. This
turns the mapping function shown above into something simpler.

```
function doObjectKv(obj) {
var result = {};
result[obj.k.toUpperCase()]: obj.v + 1;
return result;
}
```

This is the default iteration form for objects internally. If you want to iterate an object into the `{key: value}`
form, for which you would have to use the `doObjectSingle` style transformer, you must call
`{@link module:xduce.iterator|iterator}` with the third parameter explicitly set to `false` and then pass that
iterator to the transducing function. This is availabe in particular for those writing their own transducers.

Still, while this is nice, we can do better. The built-in reducers for arrays, objects, strings, and iterators
recognize the kv-form and know how to reduce it back into a regular key-value form for output. So instead of that
first `doObjectKv`, we could write it this way.

```
function doObjectKvImproved(obj) {
return {k: obj.k.toUpperCase(), v: obj.v + 1};
}
```

The reducer will recognize the form and reduce it correctly. The upshot is that in this library, `doObjectKv` and
`doObjectKvImproved` will produce the SAME RESULT. Which function to use is purely a matter of preference. IMPORTANT
NOTE: If you're adding transducer support to non-supported types, remember that you must decide whether to have your
`step` function recognize kv-form objects and reduce them into key-value. If you don't, then the style of
`doObjectKvImproved` will not be available.

ANOTHER IMPORTANT NOTE: The internal reducers recognize kv-form very explicitly. The object must have exactly two
enumerable properties, and those properties must be named 'k' and 'v'. This is to reduce the chance as much as
possible of having errors because an object that was meant to be two properties was turned into one. (It is possible
to have a transformation function return an object of more than one property; if that happens, and if that object is
not a kv-form object, then all of the properties will be merged into the final object.)

One final consideration: you have your choice of mapping function styles, but the better choice may depend on
language. The above examples are in ES5. If you're using ES2015, however, you have access to destructuring and
dynamic object keys. That may make `doObjectKv` look better, because with those features it can be written like this:

```
doObjectKv = ({k, v}) => {[k.toUpperCase()]: v + 1};
```

And that's about as concise as it gets. Note that some languages that compile into JavaScript, like CoffeeScript and
LiveScript, also support these features.

@private

TL;DR:
1. Iteration order of objects is alphabetical by key, though that can be changed by passing a sort function to
`{@link module:xduce.iterator|iterator}`.
2. Iteration is done internally in kv-form.
3. Transformation functions can output objects in key-value, which is easier in ES2015.
4. Transformation functions can output objects in kv-form, which is easier in ES5.
@param {object} obj The object to iterate over.
@param {module:xduce~sort} [sort] An optional sort function. This is applied to the keys of the object to
determine the order of iteration.
@param {boolean} [kv=false] Whether or not this object should be iterated into kv-form (if false, it remains in the
normal key-value form).
@return {module:xduce~iterator} An iterator that returns one key-value pair per call to `next`.
Creates an iterator over objcts .