ecomp-portal-FE/client/bower_components/lodash/lib/fp/template/doc/wiki.jst

   1 ## lodash/fp
   2
   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.
   7
   8 ## Installation
   9
  10 In a browser:
  11 ```html
  12 <script src='path/to/lodash.js'></script>
  13 <script src='path/to/lodash.fp.js'></script>
  14 <script>
  15 // Loading `lodash.fp.js` converts `_` to its fp variant.
  16 _.defaults({ 'a': 2, 'b': 2 })({ 'a': 1 });
  17 // → { 'a: 1, 'b': 2 }
  18
  19 // Use `noConflict` to restore the pre-fp variant.
  20 var fp = _.noConflict();
  21
  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 }
  26 </script>
  27 ```
  28
  29 In Node.js:
  30 ```js
  31 // Load the fp build.
  32 var fp = require('lodash/fp');
  33
  34 // Load a method category.
  35 var object = require('lodash/fp/object');
  36
  37 // Load a single method for smaller builds with browserify/rollup/webpack.
  38 var extend = require('lodash/fp/extend');
  39 ```
  40
  41 ## Mapping
  42
  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.
  46
  47 #### Capped Iteratee Arguments
  48
  49 Iteratee arguments are capped to avoid gotchas with variadic iteratees.
  50 ```js
  51 // The `lodash/map` iteratee receives three arguments:
  52 // (value, index|key, collection)
  53 _.map(['6', '8', '10'], parseInt);
  54 // → [6, NaN, 2]
  55
  56 // The `lodash/fp/map` iteratee is capped at one argument:
  57 // (value)
  58 fp.map(parseInt)(['6', '8', '10']);
  59 // → [6, 8, 10]
  60 ```
  61
  62 Methods that cap iteratees to one argument:<br>
  63 <%= toFuncList(_.keys(_.pickBy(mapping.iterateeAry, _.partial(_.eq, _, 1)))) %>
  64
  65 Methods that cap iteratees to two arguments:<br>
  66 <%= toFuncList(_.keys(_.pickBy(mapping.iterateeAry, _.partial(_.eq, _, 2)))) %>
  67
  68 The iteratee of `mapKeys` is invoked with one argument: (key)
  69
  70 #### Fixed Arity
  71
  72 Methods have fixed arities to support auto-currying.
  73 ```js
  74 // `lodash/padStart` accepts an optional `chars` param.
  75 _.padStart('a', 3, '-')
  76 // → '--a'
  77
  78 // `lodash/fp/padStart` does not.
  79 fp.padStart(3)('a');
  80 // → '  a'
  81 fp.padCharsStart('-')(3)('a');
  82 // → '--a'
  83 ```
  84
  85 Methods with a fixed arity of one:<br>
  86 <%= toFuncList(_.difference(mapping.aryMethod[1], _.keys(mapping.skipFixed))) %>
  87
  88 Methods with a fixed arity of two:<br>
  89 <%= toFuncList(_.difference(mapping.aryMethod[2], _.keys(mapping.skipFixed))) %>
  90
  91 Methods with a fixed arity of three:<br>
  92 <%= toFuncList(_.difference(mapping.aryMethod[3], _.keys(mapping.skipFixed))) %>
  93
  94 Methods with a fixed arity of four:<br>
  95 <%= toFuncList(_.difference(mapping.aryMethod[4], _.keys(mapping.skipFixed))) %>
  96
  97 #### Rearranged Arguments
  98
  99 Method arguments are rearranged to make composition easier.
 100 ```js
 101 // `lodash/filter` is data-first iteratee-last:
 102 // (collection, iteratee)
 103 var compact = _.partial(_.filter, _, Boolean);
 104 compact(['a', null, 'c']);
 105 // → ['a', 'c']
 106
 107 // `lodash/fp/filter` is iteratee-first data-last:
 108 // (iteratee, collection)
 109 var compact = fp.filter(Boolean);
 110 compact(['a', null, 'c']);
 111 // → ['a', 'c']
 112 ```
 113
 114 ##### Most methods follow these rules
 115
 116 A fixed arity of two has an argument order of:<br>
 117 <%= toArgOrder(mapping.aryRearg[2]) %>
 118
 119 A fixed arity of three has an argument order of:<br>
 120 <%= toArgOrder(mapping.aryRearg[3]) %>
 121
 122 A fixed arity of four has an argument order of:<br>
 123 <%= toArgOrder(mapping.aryRearg[4]) %>
 124
 125 ##### Exceptions to the rules
 126
 127 Methods that accept an array of arguments as their second parameter:<br>
 128 <%= toFuncList(_.keys(mapping.methodSpread)) %>
 129
 130 Methods with unchanged argument orders:<br>
 131 <%= toFuncList(_.keys(mapping.skipRearg)) %>
 132
 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);
 137 }).join('\n') %>
 138
 139 #### New Methods
 140
 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)
 143 any additions.
 144
 145 Methods created to accommodate Lodash’s variadic methods:<br>
 146 <%= toFuncList(_.keys(mapping.remap)) %>
 147
 148 #### Aliases
 149
 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 + '`';
 154 }).join('\n') %>
 155
 156 ## Placeholders
 157
 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.
 161 ```js
 162 // The equivalent of `2 > 5`.
 163 _.gt(2)(5);
 164 // → false
 165
 166 // The equivalent of `_.gt(5, 2)` or `5 > 2`.
 167 _.gt(_, 2)(5);
 168 // → true
 169 ```
 170
 171 ## Chaining
 172
 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.
 176
 177 ## Convert
 178
 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
 181 comes in handy.
 182 ```js
 183 // Every option is `true` by default.
 184 var _fp = fp.convert({
 185   // Specify capping iteratee arguments.
 186   'cap': true,
 187   // Specify currying.
 188   'curry': true,
 189   // Specify fixed arity.
 190   'fixed': true,
 191   // Specify immutable operations.
 192   'immutable': true,
 193   // Specify rearranging arguments.
 194   'rearg': true
 195 });
 196
 197 // The `convert` method is available on each method too.
 198 var mapValuesWithKey = fp.mapValues.convert({ 'cap': false });
 199
 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 }
 205 ```
 206
 207 Manual conversions are also possible with the `convert` module.
 208 ```js
 209 var convert = require('lodash/fp/convert');
 210
 211 // Convert by name.
 212 var assign = convert('assign', require('lodash.assign'));
 213
 214 // Convert by object.
 215 var fp = convert({
 216   'assign': require('lodash.assign'),
 217   'chunk': require('lodash.chunk')
 218 });
 219
 220 // Convert by `lodash` instance.
 221 var fp = convert(lodash.runInContext());
 222 ```
 223
 224 ## Tooling
 225
 226 Use [eslint-plugin-lodash-fp](https://www.npmjs.com/package/eslint-plugin-lodash-fp)
 227 to help use `lodash/fp` more efficiently.