0
# lodash.countby
1

2
Modular build of lodash's `countBy` function that creates an object composed of keys generated from running each element of a collection through an iteratee. The corresponding value of each key is the number of times the key was returned by the iteratee.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
## Basic Usage
18

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

22
// Basic function iteratee
23
var result1 = countBy([4.3, 6.1, 6.4], function(n) {
24
  return Math.floor(n);
25
});
26
// => { '4': 1, '6': 2 }
27

28
// Property name as iteratee
29
var result2 = countBy(['one', 'two', 'three'], 'length');
30
// => { '3': 2, '5': 1 }
31

32
// Array of objects
33
var users = [
34
  { 'user': 'barney', 'active': true },
35
  { 'user': 'betty', 'active': true },
36
  { 'user': 'fred', 'active': false }
37
];
38

39
var result3 = countBy(users, 'active');
40
// => { 'true': 2, 'false': 1 }
41
```
42

43
## Capabilities
44

45
### Collection Counting
46

47
Creates an object composed of keys generated from the results of running each element of a collection through an iteratee function. The corresponding value represents the count of elements that generated each key.
48

49
```javascript { .api }
50
/**
51
 * Creates an object composed of keys generated from running each element 
52
 * of collection through iteratee. The corresponding value of each key is 
53
 * the number of times the key was returned by iteratee.
54
 * 
55
 * @param {Array|Object|string} collection - The collection to iterate over
56
 * @param {Function|Object|string} [iteratee=_.identity] - The function invoked per iteration
57
 * @param {*} [thisArg] - The `this` binding of iteratee
58
 * @returns {Object} Returns the composed aggregate object
59
 */
60
function countBy(collection, iteratee, thisArg);
61
```
62

63
#### Parameters
64

65
- **collection** (`Array|Object|string`): The collection to iterate over. Can be an array, object, or string.
66
- **iteratee** (`Function|Object|string`, optional): The function invoked per iteration. Defaults to identity function if not provided.
67
  - **Function**: Custom function `(value, index|key, collection) => any` - return value becomes the grouping key
68
  - **Property name string**: Creates a property accessor that returns the specified property value as the key
69
  - **Property name + thisArg**: When both property name and thisArg are provided, creates a `_.matchesProperty` style callback that returns `true`/`false` based on whether the property value matches thisArg
70
  - **Object**: Creates a matcher that returns `true`/`false` based on whether elements match the provided object properties
71
- **thisArg** (`*`, optional): The `this` binding of iteratee when iteratee is a function, or the value to match against when iteratee is a property name
72

73
#### Return Value
74

75
- **Object**: An object where keys are the values returned by the iteratee and values are the count of elements that generated each key
76

77
#### Iteratee Behavior Examples
78

79
```javascript
80
var countBy = require('lodash.countby');
81

82
// Function iteratee with Math context
83
var numbers = [4.3, 6.1, 6.4];
84
var floored = countBy(numbers, function(n) {
85
  return this.floor(n);
86
}, Math);
87
// => { '4': 1, '6': 2 }
88

89
// Property name iteratee
90
var words = ['one', 'two', 'three'];
91
var byLength = countBy(words, 'length');
92
// => { '3': 2, '5': 1 }
93

94
// Property name + thisArg (matchesProperty pattern)
95
var users = [
96
  { 'user': 'barney', 'age': 36 },
97
  { 'user': 'betty', 'age': 24 },
98
  { 'user': 'fred', 'age': 36 }
99
];
100

101
var ageMatches = countBy(users, 'age', 36);
102
// => { 'false': 2, 'true': 1 } (counts based on age === 36 match result)
103

104
// Object matcher iteratee  
105
var users = [
106
  { 'user': 'barney', 'age': 36, 'active': true },
107
  { 'user': 'betty', 'age': 24, 'active': false },
108
  { 'user': 'fred', 'age': 40, 'active': true }
109
];
110

111
var activeCount = countBy(users, { 'active': true });
112
// => { 'false': 1, 'true': 2 } (counts based on match result)
113
```
114

115
#### Collection Type Support
116

117
The function supports various collection types:
118

119
```javascript
120
// Array collection
121
countBy([1, 2, 1, 3, 2], function(n) { return n; });
122
// => { '1': 2, '2': 2, '3': 1 }
123

124
// Object collection  
125
countBy({ 'a': 1, 'b': 2, 'c': 1 }, function(value) { return value; });
126
// => { '1': 2, '2': 1 }
127

128
// String collection
129
countBy('hello', function(char) { return char; });
130
// => { 'h': 1, 'e': 1, 'l': 2, 'o': 1 }
131
```