8000 docs: Document current string concatenation behavior in sum methods (… · flavioespinoza/lodash@58fe2bb · GitHub
[go: up one dir, main page]
Skip to content

Commit 58fe2bb

Browse files
flavioespinozaclaude
flavioespinoza
and
claude
committed
docs: Document current string concatenation behavior in sum methods (lodash#5818)
Update JSDoc and add tests to document the current behavior where non-numeric values in sum/sumBy/mean/meanBy result in string concatenation rather than numeric addition. This documents the existing behavior as reported in lodash#5818. The behavior may change in a future major version (see lodash#6095 for the proposed fix). Changes: - Update JSDoc for sum, sumBy, mean, meanBy to note string concatenation behavior - Update @returns to reflect that string may be returned - Add examples showing the non-numeric behavior - Add tests documenting string concatenation with various non-numeric inputs - Reference lodash#5818 in documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
1 parent 62b439f commit 58fe2bb

File tree

2 files changed

+50
-4
lines changed

2 files changed

+50
-4
lines changed

‎lodash.js‎

Lines changed: 34 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -16450,12 +16450,17 @@
1645016450
/**
1645116451
* Computes the mean of the values in `array`.
1645216452
*
16453+
* **Note:** This method does not coerce values to numbers. If the array
16454+
* contains non-numeric values, unexpected results may occur due to JavaScript's
16455+
* type coercion rules. For predictable results, ensure array contains only numbers.
16456+
* See [#5818](https://github.com/lodash/lodash/issues/5818) for details.
16457+
*
1645316458
* @static
1645416459
* @memberOf _
1645516460
* @since 4.0.0
1645616461
* @category Math
1645716462
* @param {Array} array The array to iterate over.
16458-
* @returns {number} Returns the mean.
16463+
* @returns {number|*} Returns the mean.
1645916464
* @example
1646016465
*
1646116466
* _.mean([4, 2, 8, 6]);
@@ -16470,13 +16475,18 @@
1647016475
* invoked for each element in `array` to generate the value to be averaged.
1647116476
* The iteratee is invoked with one argument: (value).
1647216477
*
16478+
* **Note:** The iteratee should return numeric values. If non-numeric values
16479+
* are returned, unexpected results may occur due to JavaScript's type coercion
16480+
* rules. For predictable results, ensure the iteratee returns only numbers.
16481+
* See [#5818](https://github.com/lodash/lodash/issues/5818) for details.
16482+
*
1647316483
* @static
1647416484
* @memberOf _
1647516485
* @since 4.7.0
1647616486
* @category Math
1647716487
* @param {Array} array The array to iterate over.
1647816488
* @param {Function} [iteratee=_.identity] The iteratee invoked per element.
16479-
* @returns {number} Returns the mean.
16489+
* @returns {number|*} Returns the mean.
1648016490
* @example
1648116491
*
1648216492
* var objects = [{ 'n': 4 }, { 'n': 2 }, { 'n': 8 }, { 'n': 6 }];
@@ -16609,16 +16619,26 @@
1660916619
/**
1661016620
* Computes the sum of the values in `array`.
1661116621
*
16622+
* **Note:** This method does not coerce values to numbers. If the array
16623+
* contains non-numeric values (e.g., strings), JavaScript's `+` operator will
16624+
* perform string concatenation instead of addition, leading to unexpected results.
16625+
* For predictable results, ensure array contains only numbers.
16626+
* See [#5818](https://github.com/lodash/lodash/issues/5818) for details.
16627+
*
1661216628
* @static
1661316629
* @memberOf _
1661416630
* @since 3.4.0
1661516631
* @category Math
1661616632
* @param {Array} array The array to iterate over.
16617-
* @returns {number} Returns the sum.
16633+
* @returns {number|string} Returns the sum, or a string if non-numeric values are present.
1661816634
* @example
1661916635
*
1662016636
* _.sum([4, 2, 8, 6]);
1662116637
* // => 20
16638+
*
16639+
* // Non-numeric values result in string concatenation (not recommended)
16640+
* _.sum(['1', '2']);
16641+
* // => '12'
1662216642
*/
1662316643
function sum(array) {
1662416644
return (array && array.length)
@@ -16631,13 +16651,19 @@
1663116651
* invoked for each element in `array` to generate the value to be summed.
1663216652
* The iteratee is invoked with one argument: (value).
1663316653
*
16654+
* **Note:** The iteratee should return numeric values. If non-numeric values
16655+
* are returned (e.g., strings), JavaScript's `+` operator will perform string
16656+
* concatenation instead of addition, leading to unexpected results.
16657+
* For predictable results, ensure the iteratee returns only numbers.
16658+
* See [#5818](https://github.com/lodash/lodash/issues/5818) for details.
16659+
*
1663416660
* @static
1663516661
* @memberOf _
1663616662
* @since 4.0.0
1663716663
* @category Math
1663816664
* @param {Array} array The array to iterate over.
1663916665
* @param {Function} [iteratee=_.identity] The iteratee invoked per element.
16640-
* @returns {number} Returns the sum.
16666+
* @returns {number|string} Returns the sum, or a string if non-numeric values are present.
1664116667
* @example
1664216668
*
1664316669
* var objects = [{ 'n': 4 }, { 'n': 2 }, { 'n': 8 }, { 'n': 6 }];
@@ -16648,6 +16674,10 @@
1664816674
* // The `_.property` iteratee shorthand.
1664916675
* _.sumBy(objects, 'n');
1665016676
* // => 20
16677+
*
16678+
* // Non-numeric values result in string concatenation (not recommended)
16679+
* _.sumBy([{ 'a': '1' }, { 'a': '2' }], 'a');
16680+
* // => '12'
1665116681
*/
1665216682
function sumBy(array, iteratee) {
1665316683
return (array && array.length)

‎test/test.js‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21574,6 +21574,22 @@
2157421574

2157521575
assert.strictEqual(func(['1', '2']), '12');
2157621576
});
21577+
21578+
// The following tests document current behavior for non-numeric values.
21579+
// This behavior may change in a future major version. See #5818.
21580+
QUnit.test('`_.' + methodName + '` with non-numeric values performs string concatenation (current behavior, see #5818)', function(assert) {
21581+
assert.expect(4);
21582+
21583+
// String values result in concatenation
21584+
assert.strictEqual(func(['a', 'b']), 'ab', 'strings are concatenated');
21585+
assert.strictEqual(func(['1', '2', '3']), '123', 'numeric strings are concatenated');
21586+
21587+
// Mixed numeric and string values
21588+
assert.strictEqual(func([1, '2']), '12', 'number + string results in string');
21589+
21590+
// This is the behavior reported in #5818
21591+
assert.strictEqual(func([1, 'f', null]), '1fnull', 'mixed types produce unexpected results');
21592+
});
2157721593
});
2157821594

2157921595
/*--------------------------------------------------------------------------*/

0 commit comments

Comments
 (0)
0