0
# lodash.takewhile
1

2
The modularized implementation of lodash's `takeWhile` function, creating array slices with elements taken from the beginning until a predicate returns falsey. This package provides a lightweight, focused utility for array manipulation with support for multiple callback styles.
3

4
## Package Information
5

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

11
## Core Imports
12

13
CommonJS (primary supported format):
14

15
```javascript
16
var takeWhile = require('lodash.takewhile');
17
```
18

19
**Note**: This is a legacy package that predates ES modules and primarily supports CommonJS. For modern projects, consider using the full lodash library with ES module imports.
20

21
## Basic Usage
22

23
```javascript
24
var takeWhile = require('lodash.takewhile');
25

26
// Basic function predicate
27
var result = takeWhile([1, 2, 3, 4, 5], function(n) {
28
  return n < 4;
29
});
30
// => [1, 2, 3]
31

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

39
// Property shorthand - take while 'active' is falsey
40
var inactiveUsers = takeWhile(users, 'active');
41
// => [] (stops immediately since first user has falsey 'active')
42
```
43

44
## Capabilities
45

46
### Array Slicing with Predicate
47

48
Creates a slice of array with elements taken from the beginning until predicate returns falsey.
49

50
```javascript { .api }
51
/**
52
 * Creates a slice of array with elements taken from the beginning.
53
 * Elements are taken until predicate returns falsey.
54
 * 
55
 * @param {Array} array - The array to query
56
 * @param {Function|Object|string} [predicate=_.identity] - The function invoked per iteration
57
 * @param {*} [thisArg] - The this binding of predicate
58
 * @returns {Array} Returns the slice of array
59
 */
60
function takeWhile(array, predicate, thisArg);
61
```
62

63
**Predicate Callback Styles:**
64

65
1. **Function Predicate**: Custom function receiving `(value, index, array)`
66
2. **Property Shorthand**: String property name to check truthiness
67
3. **MatchesProperty Shorthand**: Property name with specific value to match
68
4. **Matches Object Shorthand**: Object with properties to match against
69

70
**Usage Examples:**
71

72
```javascript
73
var takeWhile = require('lodash.takewhile');
74

75
// Function predicate
76
takeWhile([1, 2, 3, 4, 5], function(n) {
77
  return n < 3;
78
});
79
// => [1, 2]
80

81
// Function predicate with index
82
takeWhile(['a', 'b', 'c', 'd'], function(value, index) {
83
  return index < 2;
84
});
85
// => ['a', 'b']
86

87
var users = [
88
  { 'user': 'barney',  'active': false },
89
  { 'user': 'fred',    'active': false },
90
  { 'user': 'pebbles', 'active': true }
91
];
92

93
// Matches object shorthand - take elements matching the object
94
takeWhile(users, { 'active': false });
95
// => [{ 'user': 'barney', 'active': false }, { 'user': 'fred', 'active': false }]
96

97
// MatchesProperty shorthand - property name and value
98
takeWhile(users, 'active', false);
99
// => [{ 'user': 'barney', 'active': false }, { 'user': 'fred', 'active': false }]
100

101
// Property shorthand - check truthiness of property
102
takeWhile(users, 'active');
103
// => [] (first element has falsey 'active', so empty result)
104

105
// Default predicate behavior (no predicate provided)
106
takeWhile([1, 2, 3]);
107
// => [1, 2, 3] (defaults to _.identity predicate, all values are truthy)
108

109
takeWhile([1, 0, 3]);
110
// => [1] (stops at falsey value 0)
111

112
// Empty or invalid input handling
113
takeWhile(null);
114
// => []
115

116
takeWhile([]);
117
// => []
118
```
119

120
**ThisArg Binding:**
121

122
```javascript
123
var context = { threshold: 3 };
124

125
takeWhile([1, 2, 3, 4, 5], function(n) {
126
  return n < this.threshold;
127
}, context);
128
// => [1, 2]
129
```
130

131
## Types
132

133
Since this is a JavaScript package, types are described using JSDoc conventions:
134

135
```javascript { .api }
136
/**
137
 * @typedef {Function} PredicateFunction
138
 * @param {*} value - The current element being processed
139
 * @param {number} index - The index of the current element
140
 * @param {Array} array - The array being processed
141
 * @returns {boolean} True to continue taking elements, false to stop
142
 */
143

144
/**
145
 * @typedef {Object} MatchesObject
146
 * @description Object with properties to match against array elements
147
 */
148

149
/**
150
 * @typedef {string} PropertyPath
151
 * @description Property name or path to check on array elements
152
 */
153

154
/**
155
 * @typedef {PredicateFunction|MatchesObject|PropertyPath} Predicate
156
 * @description Any of the supported predicate formats
157
 */
158
```