0
# Lodash Sum
1

2
Lodash Sum is a modular implementation of lodash's `_.sum` function that calculates the sum of values in collections. It provides optimized array processing and flexible handling of arrays, objects, and strings with optional iteratee functions for transforming values before summation.
3

4
## Package Information
5

6
- **Package Name**: lodash.sum
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install lodash.sum`
10

11
## Core Imports
12

13
```javascript
14
var sum = require('lodash.sum');
15
```
16

17
## Basic Usage
18

19
```javascript
20
var sum = require('lodash.sum');
21

22
// Direct array summation
23
sum([4, 6]);
24
// => 10
25

26
// Object value summation
27
sum({ 'a': 4, 'b': 6 });
28
// => 10
29

30
// With iteratee function
31
var objects = [
32
  { 'n': 4 },
33
  { 'n': 6 }
34
];
35

36
sum(objects, function(object) {
37
  return object.n;
38
});
39
// => 10
40

41
// Using property shorthand
42
sum(objects, 'n');
43
// => 10
44
```
45

46
## Capabilities
47

48
### Sum Function
49

50
Gets the sum of the values in a collection with support for iteratee functions and lodash callback shorthands.
51

52
```javascript { .api }
53
/**
54
 * Gets the sum of the values in collection.
55
 * 
56
 * @param {Array|Object|string} collection - The collection to iterate over
57
 * @param {Function|Object|string} [iteratee] - The function invoked per iteration, or property path/object for callback shorthand
58
 * @param {*} [thisArg] - The this binding of iteratee
59
 * @returns {number} Returns the sum
60
 */
61
function sum(collection, iteratee, thisArg);
62
```
63

64
**Parameters:**
65

66
- **collection** (`Array|Object|string`): The collection to iterate over. Can be:
67
  - Arrays of numbers: `[1, 2, 3]`
68
  - Objects with numeric values: `{ a: 1, b: 2 }`
69
  - Strings (characters converted to numbers): `"123"`
70
  - Arrays of objects requiring iteratee: `[{ n: 1 }, { n: 2 }]`
71

72
- **iteratee** (`Function|Object|string`, optional): The function invoked per iteration. Supports:
73
  - **Function**: Custom transformation function `(value, index, collection) => number`
74
  - **String**: Property path shorthand `'propertyName'`
75
  - **Object**: Partial object match shorthand `{ key: value }`
76
  - When omitted, values are summed directly using unary plus operator
77

78
- **thisArg** (`*`, optional): The `this` binding of iteratee function
79

80
**Returns:**
81
- `number`: The sum of all values after iteratee transformation
82

83
**Key Features:**
84
- Automatic type coercion using unary plus operator (`+value`)
85
- Null and undefined values treated as 0
86
- Optimized array processing when iteratee has length 1
87
- Supports lodash callback shorthands for common use cases
88
- Works with collections of any size and type
89

90
**Usage Examples:**
91

92
```javascript
93
var sum = require('lodash.sum');
94

95
// Basic numeric arrays
96
sum([1, 2, 3, 4]);
97
// => 10
98

99
// Mixed types (strings converted to numbers)
100
sum(['1', '2', '3']);
101
// => 6
102

103
// Objects with numeric values
104
sum({ x: 1, y: 2, z: 3 });
105
// => 6
106

107
// Arrays with null/undefined (treated as 0)
108
sum([1, null, 3, undefined, 5]);
109
// => 9
110

111
// Complex objects with iteratee function
112
var products = [
113
  { name: 'laptop', price: 999 },
114
  { name: 'mouse', price: 25 },
115
  { name: 'keyboard', price: 75 }
116
];
117

118
sum(products, function(product) {
119
  return product.price;
120
});
121
// => 1099
122

123
// Using property shorthand
124
sum(products, 'price');
125
// => 1099
126

127
// With thisArg binding
128
var multiplier = { factor: 2 };
129
sum([1, 2, 3], function(value) {
130
  return value * this.factor;
131
}, multiplier);
132
// => 12
133

134
// String collection (characters as numbers)
135
sum('123');
136
// => 6 (1 + 2 + 3)
137

138
// Empty collections
139
sum([]);
140
// => 0
141

142
sum({});
143
// => 0
144
```
145

146
**Error Handling:**
147

148
The function is designed to be robust and will not throw errors for typical usage:
149
- Non-numeric values are converted using unary plus (`+value`)
150
- `null` and `undefined` values become 0
151
- Invalid numbers (like `NaN`) are treated as 0 using the `|| 0` fallback
152
- Empty collections return 0
153
- Values that cannot be converted to numbers (e.g., objects, functions) become `NaN` then fallback to 0
154

155
**Performance Notes:**
156

157
- Uses optimized `arraySum` function for arrays when iteratee has arity of 1 (single parameter)
158
- Falls back to `baseSum` for objects and iteratee functions with multiple parameters
159
- Includes automatic iteratee call detection to optimize parameter handling
160
- Minimal overhead for direct numeric array summation
161
- Converts non-arrays to iterable format when using array optimization path