Ramda: A Practical Functional Programming Library

Common errors

• TypeError: R.map is not a function

  cause Attempting to use `R.map` or other Ramda functions after importing the library as a default export (`import R from 'ramda';`) instead of a namespace import.
  fix Change your import statement to `import * as R from 'ramda';` for a namespace import, or `import { map } from 'ramda';` for specific functions.

• ReferenceError: R is not defined

  cause The Ramda library (or its global variable `R`) was not correctly imported or loaded into the current scope.
  fix Ensure `const R = require('ramda');` (CommonJS) or `import * as R from 'ramda';` (ESM) is at the top of your file, or that the `<script>` tag is loaded in a browser environment.

• TypeError: Cannot read properties of undefined (reading 'length')

  cause A Ramda function expecting a collection (like `map`, `filter`, `reduce`) received `undefined` or `null` as its data argument, often due to incorrect currying or argument order in a pipeline.
  fix Review the function call chain to ensure that intermediate results are not `undefined` or `null` before being passed to functions expecting a valid collection. Use `R.when`, `R.unless`, `R.defaultTo`, or `R.isNil` to handle potentially missing values defensively.

• Incorrect arity or argument handling in complex compositions (e.g., `R.converge`)

  cause Ramda's 'magical currying' can sometimes lead to unexpected arity behavior or issues when combining functions with differing argument counts, especially with functions like `R.converge` where the arity of the resulting function depends on the maximum arity of the transforming functions.
  fix Explicitly manage arity using `R.unary`, `R.nAry`, or `R.curryN` if you encounter issues with argument counts. Sometimes, explicitly wrapping a function (e.g., `const mult = (a) => (b) => a * b;`) can resolve such ambiguities, or debugging with logging tools (`R_.log` from `ramda-extension`) to inspect intermediate values in a pipe/compose chain.

Warnings

• breaking The parameter order for `propEq` and `pathEq` functions changed in `v0.29.0`. This could lead to incorrect comparisons if not updated.
  Fix: Review calls to `R.propEq` and `R.pathEq`. The correct order is now `(propertyName, value, object)` for `propEq` and `(pathArray, value, object)` for `pathEq`.
• breaking Ramda versions greater than `0.25` no longer provide a default export. Attempting `import R from 'ramda'` will cause a `TypeError`.
  Fix: Use named imports (`import { func } from 'ramda'`) or import the entire library as a namespace (`import * as R from 'ramda'`).
• gotcha A security vulnerability related to the `trim` function was patched in `v0.27.2`. Users on `v0.27.0` or `v0.27.1` are advised to upgrade immediately.
  Fix: Upgrade to `ramda@0.27.2` or newer to incorporate the security patch.
• gotcha Ramda functions are automatically curried and expect data to be the last argument. Misunderstanding this paradigm can lead to incorrect function application, argument order issues, and unexpected behavior, especially when composing functions.
  Fix: Always provide arguments in the order expected by Ramda (data last), or explicitly curry/partial apply functions as needed. Familiarize yourself with `R.curry`, `R.partial`, and `R.pipe`/`R.compose`.
• gotcha While Ramda supports TypeScript typings (often via `@types/ramda` or `types-ramda`), some types, especially for complex curried functions or conditional types, might require explicit assertions or careful usage, particularly around `undefined` or `null` values.
  Fix: Be mindful of `undefined` and `null` when working with types. For example, `R.head('')` returns `undefined`, which might require non-null assertions or explicit checks (`R.isNil`, `R.isNotNil`) depending on `types-ramda` version. Ensure `@types/ramda` is kept in sync with the Ramda library version.

Install

• npm install ramda npm
• yarn add ramda yarn
• pnpm add ramda pnpm

Imports

• R
  wrong:

  import R from 'ramda';

  correct:

  import * as R from 'ramda';

  Since v0.25, Ramda no longer has a default export; `import R from 'ramda'` will result in a TypeError. The recommended approach for bundling the entire library with tree-shaking support is `import * as R from 'ramda'`.
• map
  wrong:

  import map from 'ramda/src/map';

  correct:

  import { map } from 'ramda';

  Named imports are supported and often preferred for tree-shaking. Directly importing from `ramda/src/map` is generally discouraged as it bypasses build optimizations and might break with internal changes.
• R

  const R = require('ramda');

  This is the standard CommonJS import pattern for Node.js environments.
• R (Deno)

  import * as R from "https://deno.land/x/ramda@v0.27.2/mod.ts";

  For Deno environments, import directly from the Deno.land URL, ensuring to specify the desired version to avoid unexpected breaking changes.

Quickstart

Demonstrates Ramda's core features: piping, filtering, mapping, currying, and immutability to process and transform a list of user objects.

import * as R from 'ramda';

interface User {
  id: number;
  name: string;
  email: string;
  isActive: boolean;
}

const users: User[] = [
  { id: 1, name: 'Alice', email: 'alice@example.com', isActive: true },
  { id: 2, name: 'Bob', email: 'bob@example.com', isActive: false },
  { id: 3, name: 'Charlie', email: 'charlie@example.com', isActive: true },
  { id: 4, name: 'David', email: 'david@example.com', isActive: false },
];

// Get active user names, sorted alphabetically
const getActiveUserNames = R.pipe(
  R.filter(R.propEq('isActive', true)),
  R.map(R.prop('name')),
  R.sort(R.ascend(R.identity))
);

const activeNames = getActiveUserNames(users);
console.log('Active users (names):', activeNames);

// Create a curried function to update a user's status
const deactivateUser = R.curry((userId: number, userList: User[]) =>
  R.map((user: User) =>
    R.when(R.propEq('id', userId), R.assoc('isActive', false))(user)
  )(userList)
);

const updatedUsers = deactivateUser(1, users);
console.log('Updated users (deactivated ID 1):', updatedUsers.find(u => u.id === 1));

// Example of partial application
const getEmails = R.map(R.prop('email'));
const allEmails = getEmails(users);
console.log('All user emails:', allEmails);