public/bower_components/lodash/lib/fp/template/doc/wiki.jst

   1 ## lodash/fp
   2
   3 The `lodash/fp` module is an instance of `lodash` with its methods wrapped to
   4 produce immutable auto-curried iteratee-first data-last methods.
   5
   6 ## Installation
   7
   8 In a browser:
   9 ```html
  10 <script src='path/to/lodash.js'></script>
  11 <script src='path/to/lodash.fp.js'></script>
  12 <script>
  13 // Loading `lodash.fp.js` converts `_` to its fp variant.
  14 _.defaults({ 'a': 2, 'b': 2 })({ 'a': 1 });
  15 // → { 'a: 1, 'b': 2 }
  16
  17 // Use `noConflict` to restore the pre-fp variant.
  18 var fp = _.noConflict();
  19
  20 _.defaults({ 'a': 1 }, { 'a': 2, 'b': 2 });
  21 // → { 'a: 1, 'b': 2 }
  22 fp.defaults({ 'a': 2, 'b': 2 })({ 'a': 1 });
  23 // → { 'a: 1, 'b': 2 }
  24 </script>
  25 ```
  26
  27 In Node.js:
  28 ```js
  29 // Load the fp build.
  30 var fp = require('lodash/fp');
  31
  32 // Load a method category.
  33 var object = require('lodash/fp/object');
  34
  35 // Load a single method for smaller builds with browserify/rollup/webpack.
  36 var extend = require('lodash/fp/extend');
  37 ```
  38
  39 ## Mapping
  40
  41 Immutable auto-curried iteratee-first data-last methods sound great, but what
  42 does that really mean for each method? Below is a breakdown of the mapping used
  43 to convert each method.
  44
  45 #### Capped Iteratee Arguments
  46
  47 Iteratee arguments are capped to avoid gotchas with variadic iteratees.
  48 ```js
  49 // The `lodash/map` iteratee receives three arguments:
  50 // (value, index|key, collection)
  51 _.map(['6', '8', '10'], parseInt);
  52 // → [6, NaN, 2]
  53
  54 // The `lodash/fp/map` iteratee is capped at one argument:
  55 // (value)
  56 fp.map(parseInt)(['6', '8', '10']);
  57 // → [6, 8, 10]
  58 ```
  59
  60 Methods that cap iteratees to one argument:<br>
  61 <%= toFuncList(_.keys(_.pickBy(mapping.iterateeAry, _.partial(_.eq, _, 1)))) %>
  62
  63 Methods that cap iteratees to two arguments:<br>
  64 <%= toFuncList(_.keys(_.pickBy(mapping.iterateeAry, _.partial(_.eq, _, 2)))) %>
  65
  66 The iteratee of `mapKeys` is invoked with one argument: (key)
  67
  68 #### Fixed Arity
  69
  70 Methods have fixed arities to support auto-currying.
  71 ```js
  72 // `lodash/padStart` accepts an optional `chars` param.
  73 _.padStart('a', 3, '-')
  74 // → '--a'
  75
  76 // `lodash/fp/padStart` does not.
  77 fp.padStart(3)('a');
  78 // → '  a'
  79 fp.padCharsStart('-')(3)('a');
  80 // → '--a'
  81 ```
  82
  83 Methods with a fixed arity of one:<br>
  84 <%= toFuncList(_.difference(mapping.aryMethod[1], _.keys(mapping.skipFixed))) %>
  85
  86 Methods with a fixed arity of two:<br>
  87 <%= toFuncList(_.difference(mapping.aryMethod[2], _.keys(mapping.skipFixed))) %>
  88
  89 Methods with a fixed arity of three:<br>
  90 <%= toFuncList(_.difference(mapping.aryMethod[3], _.keys(mapping.skipFixed))) %>
  91
  92 Methods with a fixed arity of four:<br>
  93 <%= toFuncList(_.difference(mapping.aryMethod[4], _.keys(mapping.skipFixed))) %>
  94
  95 #### Rearranged Arguments
  96
  97 Method arguments are rearranged to make composition easier.
  98 ```js
  99 // `lodash/filter` is data-first iteratee-last:
 100 // (collection, iteratee)
 101 var compact = _.partial(_.filter, _, Boolean);
 102 compact(['a', null, 'c']);
 103 // → ['a', 'c']
 104
 105 // `lodash/fp/filter` is iteratee-first data-last:
 106 // (iteratee, collection)
 107 var compact = fp.filter(Boolean);
 108 compact(['a', null, 'c']);
 109 // → ['a', 'c']
 110 ```
 111
 112 ##### Most methods follow these rules
 113
 114 A fixed arity of two has an argument order of:<br>
 115 <%= toArgOrder(mapping.aryRearg[2]) %>
 116
 117 A fixed arity of three has an argument order of:<br>
 118 <%= toArgOrder(mapping.aryRearg[3]) %>
 119
 120 A fixed arity of four has an argument order of:<br>
 121 <%= toArgOrder(mapping.aryRearg[4]) %>
 122
 123 ##### Exceptions to the rules
 124
 125 Methods that accept an array of arguments as their second parameter:<br>
 126 <%= toFuncList(_.keys(mapping.methodSpread)) %>
 127
 128 Methods with unchanged argument orders:<br>
 129 <%= toFuncList(_.keys(mapping.skipRearg)) %>
 130
 131 Methods with custom argument orders:<br>
 132 <%= _.map(_.keys(mapping.methodRearg), function(methodName) {
 133   var orders = mapping.methodRearg[methodName];
 134   return ' * `_.' + methodName + '` has an order of ' + toArgOrder(orders);
 135 }).join('\n') %>
 136
 137 #### New Methods
 138
 139 Not all variadic methods have corresponding new method variants. Feel free to
 140 [request](https://github.com/lodash/lodash/blob/master/.github/CONTRIBUTING.md#feature-requests)
 141 any additions.
 142
 143 Methods created to accommodate Lodash’s variadic methods:<br>
 144 <%= toFuncList(_.keys(mapping.remap)) %>
 145
 146 #### Aliases
 147
 148 There are <%= _.size(mapping.aliasToReal) %> method aliases:<br>
 149 <%= _.map(_.keys(mapping.aliasToReal).sort(), function(alias) {
 150   var realName = mapping.aliasToReal[alias];
 151   return ' * `_.' + alias + '` is an alias of `_.' + realName + '`';
 152 }).join('\n') %>
 153
 154 ## Placeholders
 155
 156 The placeholder argument, which defaults to `_`, may be used to fill in method
 157 arguments in a different order. Placeholders are filled by the first available
 158 arguments of the curried returned function.
 159 ```js
 160 // The equivalent of `2 > 5`.
 161 _.gt(2)(5);
 162 // → false
 163
 164 // The equivalent of `_.gt(5, 2)` or `5 > 2`.
 165 _.gt(_, 2)(5);
 166 // → true
 167 ```
 168
 169 ## Chaining
 170
 171 The `lodash/fp` module **does not** convert chain sequence methods. See
 172 [Izaak Schroeder’s article](https://medium.com/making-internets/why-using-chain-is-a-mistake-9bc1f80d51ba)
 173 on using functional composition as an alternative to method chaining.
 174
 175 ## Convert
 176
 177 Although `lodash/fp` & its method modules come pre-converted, there are times
 178 when you may want to customize the conversion. That’s when the `convert` method
 179 comes in handy.
 180 ```js
 181 // Every option is `true` by default.
 182 var _fp = fp.convert({
 183   // Specify capping iteratee arguments.
 184   'cap': true,
 185   // Specify currying.
 186   'curry': true,
 187   // Specify fixed arity.
 188   'fixed': true,
 189   // Specify immutable operations.
 190   'immutable': true,
 191   // Specify rearranging arguments.
 192   'rearg': true
 193 });
 194
 195 // The `convert` method is available on each method too.
 196 var mapValuesWithKey = fp.mapValues.convert({ 'cap': false });
 197
 198 // Here’s an example of disabling iteratee argument caps to access the `key` param.
 199 mapValuesWithKey(function(value, key) {
 200   return key == 'a' ? -1 : value;
 201 })({ 'a': 1, 'b': 1 });
 202 // => { 'a': -1, 'b': 1 }
 203 ```
 204
 205 Manual conversions are also possible with the `convert` module.
 206 ```js
 207 var convert = require('lodash/fp/convert');
 208
 209 // Convert by name.
 210 var assign = convert('assign', require('lodash.assign'));
 211
 212 // Convert by object.
 213 var fp = convert({
 214   'assign': require('lodash.assign'),
 215   'chunk': require('lodash.chunk')
 216 });
 217
 218 // Convert by `lodash` instance.
 219 var fp = convert(lodash.runInContext());
 220 ```