What is ramda?
Ramda is a functional programming library for JavaScript that makes it easy to create functional pipelines, without mutating data. It emphasizes a purer functional style, with functions that are automatically curried and composed of small, reusable, and combinable functions.
What are ramda's main functionalities?
Immutability and Side-Effect Free Functions
Ramda functions do not mutate the input data and do not cause side effects, making it easier to reason about code.
const increment = R.map(R.add(1));
const result = increment([1, 2, 3]); // [2, 3, 4]
Function Composition
Ramda provides compose and pipe functions for combining functions into new functions, facilitating functional composition.
const getNames = R.compose(R.map(R.prop('name')), R.filter(R.propEq('isActive', true)));
const users = [{name: 'Alice', isActive: true}, {name: 'Bob', isActive: false}];
const activeUserNames = getNames(users); // ['Alice']
Automatic Currying
Ramda functions are automatically curried, allowing you to easily create new functions by partially applying arguments.
const addFourNumbers = (a, b, c, d) => a + b + c + d;
const curriedAddFourNumbers = R.curry(addFourNumbers);
const f = curriedAddFourNumbers(1, 2);
const g = f(3);
const result = g(4); // 10
Data Transformation
Ramda provides a suite of tools for transforming data structures, such as arrays and objects, in a declarative and functional way.
const sortByAge = R.sortBy(R.prop('age'));
const people = [{name: 'John', age: 23}, {name: 'Jane', age: 21}];
const sortedPeople = sortByAge(people); // [{name: 'Jane', age: 21}, {name: 'John', age: 23}]
Other packages similar to ramda
lodash
Lodash is a JavaScript utility library that offers similar functionality to Ramda, such as data manipulation and functional utilities. However, Lodash is not as strictly functional as Ramda and does not emphasize currying and function composition to the same extent.
underscore
Underscore.js is another utility library that provides functional programming helpers. It is similar to Lodash and predates both Lodash and Ramda. It has a more OOP-style approach and lacks the auto-currying and functional composition features that are core to Ramda.
immutable
Immutable.js provides persistent immutable data structures which can be used in a functional programming style. Unlike Ramda, which works with plain JavaScript types, Immutable.js uses its own types and provides different APIs for manipulating these structures.
fp-ts
fp-ts is a library for typed functional programming in TypeScript. It provides type-safe functional programming structures and utilities, and it is more focused on types and type-level programming compared to Ramda.
Ramda
A practical functional library for JavaScript programmers.
![Gitter](https://badges.gitter.im/Join_Chat.svg)
Why Ramda?
![](http://ramda.jcphillipps.com/logo/ramdaFilled_200x235.png)
There are already several excellent libraries with a functional flavor. Typically, they are meant to be general-purpose toolkits, suitable for working in multiple paradigms. Ramda has a more focused goal. We wanted a library designed specifically for a functional programming style, one that makes it easy to create functional pipelines, one that never mutates user data.
What's Different?
The primary distinguishing features of Ramda are:
-
Ramda emphasizes a purer functional style. Immutability and side-effect free functions
are at the heart of its design philosophy. This can help you get the job done with simple,
elegant code.
-
Ramda functions are automatically curried. This allows you to easily build up new functions
from old ones simply by not supplying the final parameters.
-
The parameters to Ramda functions are arranged to make it convenient for currying. The data
to be operated on is generally supplied last.
The last two points together make it very easy to build functions as sequences of simpler functions, each of which transforms the data and passes it along to the next. Ramda is designed to support this style of coding.
Introductions
Philosophy
Using Ramda should feel much like just using JavaScript.
It is practical, functional JavaScript. We're not introducing
lambda expressions in strings, we're not borrowing consed
lists, we're not porting over all of the Clojure functions.
Our basic data structures are plain JavaScript objects, and our
usual collections are JavaScript arrays. We also keep other
native features of JavaScript, such as functions as objects
with properties.
Functional programming is in good part about immutable objects and
side-effect free functions. While Ramda does not enforce this, it
enables such style to be as frictionless as possible.
We aim for an implementation both clean and elegant, but the API is king.
We sacrifice a great deal of implementation elegance for even a slightly
cleaner API.
Last but not least, Ramda strives for performance. A reliable and quick
implementation wins over any notions of functional purity.
Installation
To use with node:
$ npm install ramda
Then in the console:
const R = require('ramda');
To use directly in the browser:
<script src="path/to/yourCopyOf/ramda.js"></script>
or the minified version:
<script src="path/to/yourCopyOf/ramda.min.js"></script>
or from a CDN, either cdnjs:
<script src="//cdnjs.cloudflare.com/ajax/libs/ramda/0.24.1/ramda.min.js"></script>
or one of the below links from jsDelivr:
<script src="//cdn.jsdelivr.net/ramda/0.24.1/ramda.min.js"></script>
<script src="//cdn.jsdelivr.net/ramda/0.24/ramda.min.js"></script>
<script src="//cdn.jsdelivr.net/ramda/latest/ramda.min.js"></script>
(note that using latest
is taking a significant risk that ramda API changes could break your code.)
These script tags add the variable R
on the browser's global scope.
Or you can inject ramda into virtually any unsuspecting website using the bookmarklet.
Build
- on Unix-based platforms,
npm run build
updates dist/ramda.js and dist/ramda.min.js - on Windows, write the output of
scripts/build --complete
to a temporary file, then rename the temporary file dist/ramda.js.
Partial Builds
It is possible to build Ramda with a subset of the functionality to reduce its file size. Ramda's build system supports this with command line flags. For example if you're using R.compose
, R.reduce
, and R.filter
you can create a partial build with:
./scripts/build -- src/compose.js src/reduce.js src/filter.js > dist/ramda.custom.js
This requires having Node/io.js installed.
Documentation
Please review the API documentation.
The Name
Ok, so we like sheep. That's all. It's a short name, not already
taken. It could as easily have been eweda
, but then we would be
forced to say eweda lamb!, and no one wants that. For non-English
speakers, lambs are baby sheep, ewes are female sheep, and rams are male
sheep. So perhaps ramda is a grown-up lambda... but probably not.
Running The Test Suite
Console:
To run the test suite from the console, you need to have mocha
installed:
npm install -g mocha
Then from the root of the project, you can just call
mocha
Alternately, if you've installed the dependencies, via:
npm install
then you can run the tests (and get detailed output) by running:
npm test
Browser:
You can use testem to
test across different browsers (or even headlessly), with livereloading of
tests. Install testem (npm install -g testem
) and run testem
. Open the
link provided in your browser and you will see the results in your terminal.
If you have PhantomJS installed, you can run testem -l phantomjs
to run the
tests completely headlessly.
Translations
Chinese(中文)
Acknowledgements
Thanks to J. C. Phillipps for the Ramda logo.
Ramda logo artwork © 2014 J. C. Phillipps. Licensed Creative Commons
CC BY-NC-SA 3.0.