documentation of `_.transform` doesn't match implimentation.

[graingert]

Documentation claims to use string keyed properties:

An alternative to _.reduce; this method transforms object to a new accumulator object which is the result of running each of its own enumerable string keyed properties thru iteratee, with each invocation potentially mutating the accumulator object. If accumulator is not provided, a new object with the same [[Prototype]] will be used. The iteratee is invoked with four arguments: (accumulator, value, key, object). Iteratee functions may exit iteration early by explicitly returning false.

However in the source it checks for Array, and switches to arrayEach https://github.com/lodash/lodash/blob/4.13.1/lodash.js#L13130

Here's a demo of the difference in behaviour:

https://runkit.com/graingert/transform-bad-docs

const assert = require('assert');
const _ = require('lodash');

const collection = [1, 2, 3];

collection.foo = 4;

const newCollection = [];
for (let x in collection) {
  if (Object.prototype.hasOwnProperty.call(collection, x)) {
    newCollection.push(collection[x]);
  }
}
assert.deepEqual(newCollection, [1, 2, 3, 4]);

const newCollection2 = _.transform(collection, (acc, next) => { acc.push(next) }, []);
assert.deepEqual(newCollection2, [1, 2, 3]);

console.log('iterating own string keyed properties', newCollection)
console.log('using transform', newCollection2);

Perhaps the documentation should be updated like:

An alternative to _.reduce; this method transforms object to a new accumulator object which if object is a Array-like is the result of running each element in object thu iteratee, else is the result of running each of its own enumerable string keyed properties thru iteratee, with each invocation potentially mutating the accumulator object. If accumulator is not provided, a new object with the same [[Prototype]] will be used. The iteratee is invoked with four arguments: (accumulator, value, key, object). Iteratee functions may exit iteration early by explicitly returning false.

Or the check should be removed and _.transform should always use string keyed properties

[jdalton]

The method wasn't really a collections method so fell to the objects category. A PR to clarify the docs for it would be welcomed.

[graingert]

@jdalton can you give me a hand with the wording of it

[jdalton]

Your write-up is a good start. Avoid array-like and just be explicit with it being an array or typed array.

[graingert]

@jdalton where is the docs source?

[jdalton]

In the method module.

[graingert]

How about I create a _.reduceOwn method that behaves as _.transform does, and document and implement _.transform so that it delegates to _.reduce or _.reduceOwn based on the argument type?

[graingert]

Hmm actually _.transform is subtly different from _.reduce in another way:

If accumulator is not provided, a new object with the same [[Prototype]] will be used.

[jdalton]

I'm up for documentation tweaks for now. I'd hold off on new methods.

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.