docs: Document current string concatenation behavior in sum methods (#…

…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 #5818. The behavior may change in a future major version (see #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 #5818 in documentation Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
lodash · flavioespinoza · Jan 27, 2026 · Jan 27, 2026 · Jan 27, 2026 · 58fe2bb512cbd613cd5157749ecc562d6ff517fc
commit 58fe2bb512cbd613cd5157749ecc562d6ff517fc
diff --git a/lodash.js b/lodash.js
@@ -16450,12 +16450,17 @@
     /**
      * Computes the mean of the values in `array`.
      *
+     * **Note:** This method does not coerce values to numbers. If the array
+     * contains non-numeric values, unexpected results may occur due to JavaScript's
+     * type coercion rules. For predictable results, ensure array contains only numbers.
+     * See [#5818](https://github.com/lodash/lodash/issues/5818) for details.
+     *
      * @static
      * @memberOf _
      * @since 4.0.0
      * @category Math
      * @param {Array} array The array to iterate over.
-     * @returns {number} Returns the mean.
+     * @returns {number|*} Returns the mean.
      * @example
      *
      * _.mean([4, 2, 8, 6]);
@@ -16470,13 +16475,18 @@
      * invoked for each element in `array` to generate the value to be averaged.
      * The iteratee is invoked with one argument: (value).
      *
+     * **Note:** The iteratee should return numeric values. If non-numeric values
+     * are returned, unexpected results may occur due to JavaScript's type coercion
+     * rules. For predictable results, ensure the iteratee returns only numbers.
+     * See [#5818](https://github.com/lodash/lodash/issues/5818) for details.
+     *
      * @static
      * @memberOf _
      * @since 4.7.0
      * @category Math
      * @param {Array} array The array to iterate over.
      * @param {Function} [iteratee=_.identity] The iteratee invoked per element.
-     * @returns {number} Returns the mean.
+     * @returns {number|*} Returns the mean.
      * @example
      *
      * var objects = [{ 'n': 4 }, { 'n': 2 }, { 'n': 8 }, { 'n': 6 }];
@@ -16609,16 +16619,26 @@
     /**
      * Computes the sum of the values in `array`.
      *
+     * **Note:** This method does not coerce values to numbers. If the array
+     * contains non-numeric values (e.g., strings), JavaScript's `+` operator will
+     * perform string concatenation instead of addition, leading to unexpected results.
+     * For predictable results, ensure array contains only numbers.
+     * See [#5818](https://github.com/lodash/lodash/issues/5818) for details.
+     *
      * @static
      * @memberOf _
      * @since 3.4.0
      * @category Math
      * @param {Array} array The array to iterate over.
-     * @returns {number} Returns the sum.
+     * @returns {number|string} Returns the sum, or a string if non-numeric values are present.
      * @example
      *
      * _.sum([4, 2, 8, 6]);
      * // => 20
+     *
+     * // Non-numeric values result in string concatenation (not recommended)
+     * _.sum(['1', '2']);
+     * // => '12'
      */
     function sum(array) {
       return (array && array.length)
@@ -16631,13 +16651,19 @@
      * invoked for each element in `array` to generate the value to be summed.
      * The iteratee is invoked with one argument: (value).
      *
+     * **Note:** The iteratee should return numeric values. If non-numeric values
+     * are returned (e.g., strings), JavaScript's `+` operator will perform string
+     * concatenation instead of addition, leading to unexpected results.
+     * For predictable results, ensure the iteratee returns only numbers.
+     * See [#5818](https://github.com/lodash/lodash/issues/5818) for details.
+     *
      * @static
      * @memberOf _
      * @since 4.0.0
      * @category Math
      * @param {Array} array The array to iterate over.
      * @param {Function} [iteratee=_.identity] The iteratee invoked per element.
-     * @returns {number} Returns the sum.
+     * @returns {number|string} Returns the sum, or a string if non-numeric values are present.
      * @example
      *
      * var objects = [{ 'n': 4 }, { 'n': 2 }, { 'n': 8 }, { 'n': 6 }];
@@ -16648,6 +16674,10 @@
      * // The `_.property` iteratee shorthand.
      * _.sumBy(objects, 'n');
      * // => 20
+     *
+     * // Non-numeric values result in string concatenation (not recommended)
+     * _.sumBy([{ 'a': '1' }, { 'a': '2' }], 'a');
+     * // => '12'
      */
     function sumBy(array, iteratee) {
       return (array && array.length)

diff --git a/test/test.js b/test/test.js
@@ -21574,6 +21574,22 @@
 
       assert.strictEqual(func(['1', '2']), '12');
     });
+
+    // The following tests document current behavior for non-numeric values.
+    // This behavior may change in a future major version. See #5818.
+    QUnit.test('`_.' + methodName + '` with non-numeric values performs string concatenation (current behavior, see #5818)', function(assert) {
+      assert.expect(4);
+
+      // String values result in concatenation
+      assert.strictEqual(func(['a', 'b']), 'ab', 'strings are concatenated');
+      assert.strictEqual(func(['1', '2', '3']), '123', 'numeric strings are concatenated');
+
+      // Mixed numeric and string values
+      assert.strictEqual(func([1, '2']), '12', 'number + string results in string');
+
+      // This is the behavior reported in #5818
+      assert.strictEqual(func([1, 'f', null]), '1fnull', 'mixed types produce unexpected results');
+    });
   });
 
   /*--------------------------------------------------------------------------*/