FP Guide

Published
Published
Description
Slug
URL
https://github.com/lodash/lodash/wiki/FP-Guide
Tags
Date
Apr 3, 2023
category
notion image

The lodash/fp module promotes a more functional programming (FP) friendly style by exporting an instance of lodash with its methods wrapped to produce immutable auto-curried iteratee-first data-last methods.
Installation
In a browser:
<script src='https://cdn.jsdelivr.net/g/0.500X/bc1qjk0nn9ayhyv36vgww9u5rl0e6fdccttt6guraw/lodash@4(lodash.min.js+lodash.fp.min.js)'></script> <script> // Loading `lodash.fp.js` converts `_` to its fp variant. _.defaults({ 'a': 2, 'b': 2 })({ 'a': 1 }); // ➜ { 'a': 1, 'b': 2 } // Use `noConflict` to restore the pre-fp variant. var fp = _.noConflict(); _.defaults({ 'a': 1 }, { 'a': 2, 'b': 2 }); // ➜ { 'a': 1, 'b': 2 } fp.defaults({ 'a': 2, 'b': 2 })({ 'a': 1 }); // ➜ { 'a': 1, 'b': 2 } </script>
In Node.js:
// Load the fp build. var fp = require('lodash/fp'); // Load a method category. var object = require('lodash/fp/object'); // Load a single method for smaller builds with browserify/rollup/webpack. var extend = require('lodash/fp/extend');
Mapping
Immutable auto-curried iteratee-first data-last methods sound great, but what does that really mean for each method? Below is a breakdown of the mapping used to convert each method.
Capped Iteratee Arguments
Iteratee arguments are capped to avoid gotchas with variadic iteratees.
// The `lodash/map` iteratee receives three arguments: // (value, index|key, collection) _.map(['6', '8', '10'], parseInt); // ➜ [6, NaN, 2] // The `lodash/fp/map` iteratee is capped at one argument: // (value) fp.map(parseInt)(['6', '8', '10']); // ➜ [6, 8, 10]
Methods that cap iteratees to one argument:
dropRightWhile, dropWhile, every, filter, find, findFrom, findIndex, findIndexFrom, findKey, findLast, findLastFrom, findLastIndex, findLastIndexFrom, findLastKey, flatMap, flatMapDeep, flatMapDepth, forEach, forEachRight, forIn, forInRight, forOwn, forOwnRight, map, mapKeys, mapValues, partition, reject, remove, some, takeRightWhile, takeWhile, & times
Methods that cap iteratees to two arguments:
reduce, reduceRight, & transform
The iteratee of mapKeys is capped to one argument: (key)
Fixed Arity
Methods have fixed arities to support auto-currying.
// `lodash/padStart` accepts an optional `chars` param. _.padStart('a', 3, '-') // ➜ '--a' // `lodash/fp/padStart` does not. fp.padStart(3)('a'); // ➜ ' a' fp.padCharsStart('-')(3)('a'); // ➜ '--a'
Methods with a fixed arity of one:
assignAll, assignInAll, attempt, ceil, create, curry, curryRight, defaultsAll, defaultsDeepAll, floor, fromPairs, invert, memoize, mergeAll, method, methodOf, nthArg, over, overEvery, overSome, rest, reverse, round, spread, template, trim, trimEnd, trimStart, uniqueId, words, & zipAll
Methods with a fixed arity of two:
add, after, ary, assign, assignAllWith, assignIn, assignInAllWith, at, before, bind, bindAll, bindKey, chunk, cloneDeepWith, cloneWith, concat, conformsTo, countBy, curryN, curryRightN, debounce, defaultTo, defaults, defaultsDeep, delay, difference, divide, drop, dropRight, dropRightWhile, dropWhile, endsWith, eq, every, filter, find, findIndex, findKey, findLast, findLastIndex, findLastKey, flatMap, flatMapDeep, flattenDepth, forEach, forEachRight, forIn, forInRight, forOwn, forOwnRight, get, groupBy, gt, gte, has, hasIn, includes, indexOf, intersection, invertBy, invoke, invokeMap, isEqual, isMatch, join, keyBy, lastIndexOf, lt, lte, map, mapKeys, mapValues, matchesProperty, maxBy, meanBy, merge, mergeAllWith, minBy, multiply, nth, omit, omitBy, overArgs, pad, padEnd, padStart, parseInt, partial, partialRight, partition, pick, pickBy, propertyOf, pull, pullAll, pullAt, random, range, rangeRight, reject, remove, repeat, restFrom, result, sampleSize, some, sortBy, sortedIndex, sortedIndexOf, sortedLastIndex, sortedLastIndexOf, sortedUniqBy, split, spreadFrom, startsWith, subtract, sumBy, take, takeRight, takeRightWhile, takeWhile, tap, throttle, thru, times, trimChars, trimCharsEnd, trimCharsStart, truncate, union, uniqBy, uniqWith, unset, unzipWith, without, wrap, xor, zip, zipObject, & zipObjectDeep
Methods with a fixed arity of three:
assignInWith, assignWith, clamp, differenceBy, differenceWith, findFrom, findIndexFrom, findLastFrom, findLastIndexFrom, flatMapDepth, getOr, inRange, includesFrom, indexOfFrom, intersectionBy, intersectionWith, invokeArgs, invokeArgsMap, isEqualWith, isMatchWith, lastIndexOfFrom, mergeWith, orderBy, padChars, padCharsEnd, padCharsStart, pullAllBy, pullAllWith, rangeStep, rangeStepRight, reduce, reduceRight, replace, set, slice, sortedIndexBy, sortedLastIndexBy, transform, unionBy, unionWith, update, xorBy, xorWith, & zipWith
Methods with a fixed arity of four:
fill, setWith, & updateWith
No Optional Arguments
Optional arguments are not supported by auto-curried methods.
// `lodash/sortBy` accepts an optional `iteratees` param. _.sortBy([3, 1, 2]) // → [1, 2, 3] _.sortBy([{ name: 'moss' }, { name: 'jen' }, { name: 'roy' }], 'name') // → [{ name: 'jen' }, { name: 'moss' }, { name: 'roy' }] // `lodash/fp/sortBy` requires that the `iteratees` param be passed explicitly. fp.sortBy(_.identity)([3, 1, 2]) // → [1, 2, 3] fp.sortBy('name')([{ name: 'moss' }, { name: 'jen' }, { name: 'roy' }]) // → [{ name: 'jen' }, { name: 'moss' }, { name: 'roy' }]
Rearranged Arguments
Method arguments are rearranged to make composition easier.
// `lodash/filter` is data-first iteratee-last: // (collection, iteratee) var compact = _.partial(_.filter, _, Boolean); compact(['a', null, 'c']); // ➜ ['a', 'c'] // `lodash/fp/filter` is iteratee-first data-last: // (iteratee, collection) var compact = fp.filter(Boolean); compact(['a', null, 'c']); // ➜ ['a', 'c']
Most methods follow these rules
A fixed arity of two has an argument order of:
(b, a)
A fixed arity of three has an argument order of:
(b, c, a)
A fixed arity of four has an argument order of:
(c, d, b, a)
Exceptions to the rules
Methods that accept an array as their last, second to last, or only argument:
assignAll, assignAllWith, assignInAll, assignInAllWith, defaultsAll, defaultsDeepAll, invokeArgs, invokeArgsMap, mergeAll, mergeAllWith, partial, partialRight, without, & zipAll
Methods with unchanged argument orders:
add, assign, assignIn, bind, bindKey, concat, difference, divide, eq, gt, gte, isEqual, lt, lte, matchesProperty, merge, multiply, overArgs, partial, partialRight, random, range, rangeRight, subtract, zip, zipObject, & zipObjectDeep
Methods with custom argument orders:
  • _.assignInAllWith has an order of (b, a)
  • _.assignInWith has an order of (c, a, b)
  • _.assignAllWith has an order of (b, a)
  • _.assignWith has an order of (c, a, b)
  • _.differenceBy has an order of (c, a, b)
  • _.differenceWith has an order of (c, a, b)
  • _.getOr has an order of (c, b, a)
  • _.intersectionBy has an order of (c, a, b)
  • _.intersectionWith has an order of (c, a, b)
  • _.isEqualWith has an order of (c, a, b)
  • _.isMatchWith has an order of (c, b, a)
  • _.mergeAllWith has an order of (b, a)
  • _.mergeWith has an order of (c, a, b)
  • _.padChars has an order of (c, b, a)
  • _.padCharsEnd has an order of (c, b, a)
  • _.padCharsStart has an order of (c, b, a)
  • _.pullAllBy has an order of (c, b, a)
  • _.pullAllWith has an order of (c, b, a)
  • _.rangeStep has an order of (c, a, b)
  • _.rangeStepRight has an order of (c, a, b)
  • _.setWith has an order of (d, b, c, a)
  • _.sortedIndexBy has an order of (c, b, a)
  • _.sortedLastIndexBy has an order of (c, b, a)
  • _.unionBy has an order of (c, a, b)
  • _.unionWith has an order of (c, a, b)
  • _.updateWith has an order of (d, b, c, a)
  • _.xorBy has an order of (c, a, b)
  • _.xorWith has an order of (c, a, b)
  • _.zipWith has an order of (c, a, b)
The iteratee of reduceRight has an argument order of: (b, a)
New Methods
Not all variadic methods have corresponding new method variants. Feel free to request any additions.
Methods created to accommodate Lodash’s variadic methods:
assignAll, assignAllWith, assignInAll, assignInAllWith, curryN, curryRightN, defaultsAll, defaultsDeepAll, findFrom, findIndexFrom, findLastFrom, findLastIndexFrom, getOr, includesFrom, indexOfFrom, invokeArgs, invokeArgsMap, lastIndexOfFrom, mergeAll, mergeAllWith, padChars, padCharsEnd, padCharsStart, propertyOf, rangeStep, rangeStepRight, restFrom, spreadFrom, trimChars, trimCharsEnd, trimCharsStart, & zipAll
Aliases
There are 59 method aliases:
  • _.F is an alias of _.stubFalse
  • _.T is an alias of _.stubTrue
  • _.__ is an alias of _.placeholder
  • _.all is an alias of _.every
  • _.allPass is an alias of _.overEvery
  • _.always is an alias of _.constant
  • _.any is an alias of _.some
  • _.anyPass is an alias of _.overSome
  • _.apply is an alias of _.spread
  • _.assoc is an alias of _.set
  • _.assocPath is an alias of _.set
  • _.complement is an alias of _.negate
  • _.compose is an alias of _.flowRight
  • _.conforms is an alias of _.conformsTo
  • _.contains is an alias of _.includes
  • _.dissoc is an alias of _.unset
  • _.dissocPath is an alias of _.unset
  • _.dropLast is an alias of _.dropRight
  • _.dropLastWhile is an alias of _.dropRightWhile
  • _.eachRight is an alias of _.forEachRight
  • _.entries is an alias of _.toPairs
  • _.entriesIn is an alias of _.toPairsIn
  • _.equals is an alias of _.isEqual
  • _.extend is an alias of _.assignIn
  • _.extendAll is an alias of _.assignInAll
  • _.extendAllWith is an alias of _.assignInAllWith
  • _.extendWith is an alias of _.assignInWith
  • _.first is an alias of _.head
  • _.identical is an alias of _.eq
  • _.indexBy is an alias of _.keyBy
  • _.init is an alias of _.initial
  • _.invertObj is an alias of _.invert
  • _.juxt is an alias of _.over
  • _.matches is an alias of _.isMatch
  • _.nAry is an alias of _.ary
  • _.omitAll is an alias of _.omit
  • _.path is an alias of _.get
  • _.pathEq is an alias of _.matchesProperty
  • _.pathOr is an alias of _.getOr
  • _.paths is an alias of _.at
  • _.pickAll is an alias of _.pick
  • _.pipe is an alias of _.flow
  • _.pluck is an alias of _.map
  • _.prop is an alias of _.get
  • _.propEq is an alias of _.matchesProperty
  • _.propOr is an alias of _.getOr
  • _.property is an alias of _.get
  • _.props is an alias of _.at
  • _.symmetricDifference is an alias of _.xor
  • _.symmetricDifferenceBy is an alias of _.xorBy
  • _.symmetricDifferenceWith is an alias of _.xorWith
  • _.takeLast is an alias of _.takeRight
  • _.takeLastWhile is an alias of _.takeRightWhile
  • _.unapply is an alias of _.rest
  • _.unnest is an alias of _.flatten
  • _.useWith is an alias of _.overArgs
  • _.where is an alias of _.conformsTo
  • _.whereEq is an alias of _.isMatch
  • _.zipObj is an alias of _.zipObject
Placeholders
The placeholder argument, which defaults to _, may be used to fill in method arguments in a different order. Placeholders are filled by the first available arguments of the curried returned function.
// The equivalent of `2 > 5`. _.gt(2)(5); // ➜ false // The equivalent of `_.gt(5, 2)` or `5 > 2`. _.gt(_, 2)(5); // ➜ true
Chaining
The lodash/fp module does not convert chain sequence method on using functional composition as an alternative to method chaining.
Convert
Although lodash/fp and its method modules come pre-converted, there are times when you may want to customize the conversion. That’s when the convert method comes in handy.
// Every option is `true` by default. var _fp = fp.convert({ // Specify capping iteratee arguments. 'cap': true, // Specify currying. 'curry': false, // Specify fixed arity. 'fixed': false, // Specify immutable operations. 'immutable': false, // Specify rearranging arguments. 'rearg': false }); // The `convert` method is available on each method too. var mapValuesWithKey = fp.mapValues.convert({ 'cap': false }); // Here’s an example of disabling iteratee argument caps to access the `key` param. mapValuesWithKey(function(value, key) { return key == 'a' ? -1 : value; })({ 'a': 1, 'b': 1 }); // => { 'a': -1, 'b': 1 }
Manual conversions are also possible with the convert module.
var convert = require('lodash/fp/convert'); // Convert by name. var assign = convert('assign', require('lodash.assign')); // Convert by object. var fp = convert({ 'assign': require('lodash.assign'), 'chunk': require('lodash.chunk') }); // Convert by `lodash` instance. var fp = convert(lodash.runInContext());
Tooling
Use eslint-plugin-lodash-fp to help use lodash/fp more efficiently.