3 The `lodash/fp` module promotes a more
4 [functional programming](https://en.wikipedia.org/wiki/Functional_programming)
5 (FP) friendly style by exporting an instance of `lodash` with its methods wrapped
6 to produce immutable auto-curried iteratee-first data-last methods.
12 <script src='path/to/lodash.js'></script>
13 <script src='path/to/lodash.fp.js'></script>
15 // Loading `lodash.fp.js` converts `_` to its fp variant.
16 _.defaults({ 'a': 2, 'b': 2 })({ 'a': 1 });
17 // → { 'a: 1, 'b': 2 }
19 // Use `noConflict` to restore the pre-fp variant.
20 var fp = _.noConflict();
22 _.defaults({ 'a': 1 }, { 'a': 2, 'b': 2 });
23 // → { 'a: 1, 'b': 2 }
24 fp.defaults({ 'a': 2, 'b': 2 })({ 'a': 1 });
25 // → { 'a: 1, 'b': 2 }
32 var fp = require('lodash/fp');
34 // Load a method category.
35 var object = require('lodash/fp/object');
37 // Load a single method for smaller builds with browserify/rollup/webpack.
38 var extend = require('lodash/fp/extend');
43 Immutable auto-curried iteratee-first data-last methods sound great, but what
44 does that really mean for each method? Below is a breakdown of the mapping used
45 to convert each method.
47 #### Capped Iteratee Arguments
49 Iteratee arguments are capped to avoid gotchas with variadic iteratees.
51 // The `lodash/map` iteratee receives three arguments:
52 // (value, index|key, collection)
53 _.map(['6', '8', '10'], parseInt);
56 // The `lodash/fp/map` iteratee is capped at one argument:
58 fp.map(parseInt)(['6', '8', '10']);
62 Methods that cap iteratees to one argument:<br>
63 <%= toFuncList(_.keys(_.pickBy(mapping.iterateeAry, _.partial(_.eq, _, 1)))) %>
65 Methods that cap iteratees to two arguments:<br>
66 <%= toFuncList(_.keys(_.pickBy(mapping.iterateeAry, _.partial(_.eq, _, 2)))) %>
68 The iteratee of `mapKeys` is invoked with one argument: (key)
72 Methods have fixed arities to support auto-currying.
74 // `lodash/padStart` accepts an optional `chars` param.
75 _.padStart('a', 3, '-')
78 // `lodash/fp/padStart` does not.
81 fp.padCharsStart('-')(3)('a');
85 Methods with a fixed arity of one:<br>
86 <%= toFuncList(_.difference(mapping.aryMethod[1], _.keys(mapping.skipFixed))) %>
88 Methods with a fixed arity of two:<br>
89 <%= toFuncList(_.difference(mapping.aryMethod[2], _.keys(mapping.skipFixed))) %>
91 Methods with a fixed arity of three:<br>
92 <%= toFuncList(_.difference(mapping.aryMethod[3], _.keys(mapping.skipFixed))) %>
94 Methods with a fixed arity of four:<br>
95 <%= toFuncList(_.difference(mapping.aryMethod[4], _.keys(mapping.skipFixed))) %>
97 #### Rearranged Arguments
99 Method arguments are rearranged to make composition easier.
101 // `lodash/filter` is data-first iteratee-last:
102 // (collection, iteratee)
103 var compact = _.partial(_.filter, _, Boolean);
104 compact(['a', null, 'c']);
107 // `lodash/fp/filter` is iteratee-first data-last:
108 // (iteratee, collection)
109 var compact = fp.filter(Boolean);
110 compact(['a', null, 'c']);
114 ##### Most methods follow these rules
116 A fixed arity of two has an argument order of:<br>
117 <%= toArgOrder(mapping.aryRearg[2]) %>
119 A fixed arity of three has an argument order of:<br>
120 <%= toArgOrder(mapping.aryRearg[3]) %>
122 A fixed arity of four has an argument order of:<br>
123 <%= toArgOrder(mapping.aryRearg[4]) %>
125 ##### Exceptions to the rules
127 Methods that accept an array of arguments as their second parameter:<br>
128 <%= toFuncList(_.keys(mapping.methodSpread)) %>
130 Methods with unchanged argument orders:<br>
131 <%= toFuncList(_.keys(mapping.skipRearg)) %>
133 Methods with custom argument orders:<br>
134 <%= _.map(_.keys(mapping.methodRearg), function(methodName) {
135 var orders = mapping.methodRearg[methodName];
136 return ' * `_.' + methodName + '` has an order of ' + toArgOrder(orders);
141 Not all variadic methods have corresponding new method variants. Feel free to
142 [request](https://github.com/lodash/lodash/blob/master/.github/CONTRIBUTING.md#feature-requests)
145 Methods created to accommodate Lodash’s variadic methods:<br>
146 <%= toFuncList(_.keys(mapping.remap)) %>
150 There are <%= _.size(mapping.aliasToReal) %> method aliases:<br>
151 <%= _.map(_.keys(mapping.aliasToReal).sort(), function(alias) {
152 var realName = mapping.aliasToReal[alias];
153 return ' * `_.' + alias + '` is an alias of `_.' + realName + '`';
158 The placeholder argument, which defaults to `_`, may be used to fill in method
159 arguments in a different order. Placeholders are filled by the first available
160 arguments of the curried returned function.
162 // The equivalent of `2 > 5`.
166 // The equivalent of `_.gt(5, 2)` or `5 > 2`.
173 The `lodash/fp` module **does not** convert chain sequence methods. See
174 [Izaak Schroeder’s article](https://medium.com/making-internets/why-using-chain-is-a-mistake-9bc1f80d51ba)
175 on using functional composition as an alternative to method chaining.
179 Although `lodash/fp` & its method modules come pre-converted, there are times
180 when you may want to customize the conversion. That’s when the `convert` method
183 // Every option is `true` by default.
184 var _fp = fp.convert({
185 // Specify capping iteratee arguments.
189 // Specify fixed arity.
191 // Specify immutable operations.
193 // Specify rearranging arguments.
197 // The `convert` method is available on each method too.
198 var mapValuesWithKey = fp.mapValues.convert({ 'cap': false });
200 // Here’s an example of disabling iteratee argument caps to access the `key` param.
201 mapValuesWithKey(function(value, key) {
202 return key == 'a' ? -1 : value;
203 })({ 'a': 1, 'b': 1 });
204 // => { 'a': -1, 'b': 1 }
207 Manual conversions are also possible with the `convert` module.
209 var convert = require('lodash/fp/convert');
212 var assign = convert('assign', require('lodash.assign'));
214 // Convert by object.
216 'assign': require('lodash.assign'),
217 'chunk': require('lodash.chunk')
220 // Convert by `lodash` instance.
221 var fp = convert(lodash.runInContext());
226 Use [eslint-plugin-lodash-fp](https://www.npmjs.com/package/eslint-plugin-lodash-fp)
227 to help use `lodash/fp` more efficiently.