Remeda

A utility library for JavaScript and TypeScript.

Functional programmingUtils
remeda/remedaremedajs.comremeda

README

Remeda
=============

The first "data-first" and "data-last" utility library designed especially for TypeScript.

Installation
  1. ```bash
  2. npm i remeda
  3. yarn add remeda
  4. ```
Then in .js or .ts

  1. ```js
  2. import * as R from 'remeda'; // tree-shaking supported!
  3. ```


Why Remeda?
There are no good utility libraries that work well with TypeScript. When working with Lodash or Ramda you must sometimes annotate types manually.
Remeda is written and tested in TypeScript and that means there won't be any problems with custom typings.



What's "data-first" and "data-last"?
Functional programming is nice, and it makes the code more readable. However there are situations where you don't need "pipes", and you want to call just a single function.

  1. ```js
  2. // Remeda
  3. R.pick(obj, ['firstName', 'lastName']);

  5. // Ramda
  6. R.pick(['firstName', 'lastName'], obj);

  8. // Lodash
  9. _.pick(obj, ['firstName', 'lastName']);
  10. ```

For readers looking for data-last forms like R.filter(fn)(array), Remeda supports it. Keep reading along!


In the above example, "data-first" approach is more natural and more programmer friendly because when you type the second argument, you get the auto-complete from IDE. It's not possible to get the auto-complete in Ramda because the data argument is not provided.

"data-last" approach is helpful when writing data transformations aka pipes.

  1. ```js
  2. const users = [
  3.   {name: 'john', age: 20, gender: 'm'},
  4.   {name: 'marry', age: 22, gender: 'f'},
  5.   {name: 'samara', age: 24, gender: 'f'},
  6.   {name: 'paula', age: 24, gender: 'f'},
  7.   {name: 'bill', age: 33, gender: 'm'},
  8. ]

  10. // Remeda
  11. R.pipe(
  12.   users,
  13.   R.filter(x => x.gender === 'f'),
  14.   R.groupBy(x => x.age),
  15. );

  17. // Ramda
  18. R.pipe(
  19.   R.filter(x => x.gender === 'f'),
  20.   R.groupBy(x => x.age),
  21. )(users) // broken typings in TS :(

  23. // Lodash
  24. _(users)
  25.   .filter(x => x.gender === 'f')
  26.   .groupBy(x => x.age)
  27.   .value()

  29. // Lodash-fp
  30. _.flow(
  31.   _.filter(x => x.gender === 'f'),
  32.   _.groupBy(x => x.age),
  33. )(users)// broken typings in TS :(
  34. ```

Mixing paradigms can be cumbersome in Lodash because it requires importing two different methods.
Remeda implements all methods in two versions, and the correct overload is picked based on the number of provided arguments.
The "data-last" version must always have one argument less than the "data-first" version.

  1. ```js
  2. // Remeda
  3. R.pick(obj, ['firstName', 'lastName']); // data-first
  4. R.pipe(obj, R.pick(['firstName', 'lastName'])); // data-last

  6. R.pick(['firstName', 'lastName'], obj); // error, this won't work!
  7. R.pick(['firstName', 'lastName'])(obj); // this will work but the types cannot be inferred

  9. ```


Lazy evaluation
Many functions support lazy evaluation when using pipe or createPipe. These functions have a pipeable tag in the documentation.
Lazy evaluation is not supported in Ramda and only partially supported in lodash.

  1. ```js
  2. // Get first 3 unique values
  3. const arr = [1, 2, 2, 3, 3, 4, 5, 6];

  5. const result = R.pipe(
  6.   arr,                    // only four iterations instead of eight (array.length)
  7.   R.map(x => {
  8.     console.log('iterate', x);
  9.     return x;
  10.   }),
  11.   R.uniq(),
  12.   R.take(3)
  13. ); // => [1, 2, 3]

  15. /**
  16. * Console output:
  17. * iterate 1
  18. * iterate 2
  19. * iterate 2
  20. * iterate 3
  21. * /

  23. ```


Indexed version
Iterable functions have an extra property indexed which is the same function with iterator (element, index, array).

  1. ```js
  2. const arr = [10, 12, 13, 3];

  4. // filter even values
  5. R.filter(arr, x => x % 2 === 0); // => [10, 12]

  7. // filter even indexes
  8. R.filter.indexed(arr, (x, i) => i % 2 === 0); // => [10, 13]
  9. ```

For Lodash and Ramda users
Please check function mapping in mapping.md.


Remeda Design Goals
1. The usage must be programmer friendly, and that's more important than following XYZ paradigm strictly.
2. Manual annotation should never be required, and proper typings should infer everything. The only exception is the first function in createPipe.
3. ES6 polyfill is required. Core methods are reused, and data structure (like Map/Set) are not re-implemented.
4. The implementation of each function should be as minimal as possible. Tree-shaking is supported by default. (Do you know that lodash.keyBy has 14KB after minification?)
5. All functions are immutable, and there are no side-effects.
6. Fixed number of arguments.

MIT