0
# lodash.rest
1

2
lodash.rest provides the lodash method `_.rest` as a standalone module. This utility creates a function that invokes the original function with arguments from a specified start position and beyond provided as a rest parameter array. It implements the ES6 rest parameters pattern, allowing you to collect trailing function arguments into an array.
3

4
## Package Information
5

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

11
## Core Imports
12

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

17
ES6/Modern Node.js:
18
```javascript
19
const rest = require('lodash.rest');
20
```
21

22
## Basic Usage
23

24
```javascript
25
const rest = require('lodash.rest');
26

27
// Create a function that collects trailing arguments
28
const say = rest(function(what, names) {
29
  return what + ' ' + names.slice(0, -1).join(', ') +
30
    (names.length > 1 ? ', & ' : '') + names[names.length - 1];
31
});
32

33
console.log(say('hello', 'fred', 'barney', 'pebbles'));
34
// => 'hello fred, barney, & pebbles'
35

36
// Using with a custom start position  
37
const greet = rest(function(greeting, separator, names) {
38
  return greeting + separator + names.join(', ');
39
}, 2);
40

41
console.log(greet('Hello', ': ', 'Alice', 'Bob', 'Charlie'));
42
// => 'Hello: Alice, Bob, Charlie'
43
```
44

45
## Capabilities
46

47
### Rest Function
48

49
Creates a function that invokes the original function with arguments from start position and beyond provided as an array.
50

51
```javascript { .api }
52
/**
53
 * Creates a function that invokes `func` with the `this` binding of the
54
 * created function and arguments from `start` and beyond provided as
55
 * an array.
56
 *
57
 * @param {Function} func - The function to apply a rest parameter to
58
 * @param {number} [start=func.length-1] - The start position of the rest parameter
59
 * @returns {Function} Returns the new function
60
 * @throws {TypeError} Throws if `func` is not a function
61
 * @since 4.0.0
62
 * @category Function
63
 */
64
function rest(func, start);
65
```
66

67
**Parameters:**
68
- `func` (Function): The function to apply a rest parameter to. Must be a valid function.
69
- `start` (number, optional): The start position of the rest parameter. Defaults to `func.length - 1`. Must be a non-negative integer.
70

71
**Returns:**
72
- (Function): Returns a new function that collects arguments from the start position onwards into an array passed as the parameter at the start position.
73

74
**Throws:**
75
- `TypeError`: When `func` is not a function, throws "Expected a function"
76

77
**Usage Examples:**
78

79
```javascript
80
const rest = require('lodash.rest');
81

82
// Basic usage - collect last N arguments
83
const variadic = rest(function(a, b, others) {
84
  console.log('a:', a);
85
  console.log('b:', b); 
86
  console.log('others:', others);
87
});
88

89
variadic('first', 'second', 'third', 'fourth');
90
// a: first
91
// b: second  
92
// others: ['third', 'fourth']
93

94
// Custom start position
95
const customStart = rest(function(prefix, args) {
96
  return prefix + ': ' + args.join(', ');
97
}, 1);
98

99
console.log(customStart('Items', 'apple', 'banana', 'cherry'));
100
// => 'Items: apple, banana, cherry'
101

102
// Edge case - start position 0 collects all arguments
103
const collectAll = rest(function(allArgs) {
104
  return allArgs.length;
105
}, 0);
106

107
console.log(collectAll('a', 'b', 'c')); // => 3
108
```
109

110
## Implementation Notes
111

112
- Based on the ES6 rest parameters specification  
113
- Handles edge cases like undefined start positions and invalid functions
114
- Optimized for performance with internal helper functions
115
- Compatible with CommonJS module systems
116
- Part of the modular lodash ecosystem for selective imports
117
- Maintains proper `this` binding when the returned function is called
118
- Start position is coerced to a non-negative integer internally