Prelude.ls Functional Utility Library

Common errors

• ReferenceError: require is not defined

  cause Attempting to use `require('prelude-ls')` in a browser environment without a CommonJS bundler (like Webpack or Browserify) or trying to use `import` in a pure CommonJS Node.js project.
  fix For Node.js, ensure your project is configured for CommonJS modules. For browser usage, use a bundler that can resolve CommonJS modules, or include the `prelude-browser.js` file directly from the package's `browser` directory via a `<script>` tag.

• Error: Cannot find module 'prelude-ls'

  cause The package `prelude-ls` is not installed or the module resolution path is incorrect, or an ES module `import` statement is used in a CommonJS-only context that doesn't transpile it.
  fix First, ensure the package is installed: `npm install prelude-ls`. If in Node.js, verify you are using `require('prelude-ls')`. If using a bundler, check its configuration for module resolution.

• Property 'map' does not exist on type 'typeof import("prelude-ls")'.

  cause This TypeScript error indicates that the type definitions for `prelude-ls` are either missing or incomplete, preventing the TypeScript compiler from recognizing exported functions.
  fix Install the unofficial type definitions: `npm install --save-dev @types/prelude-ls`. If the issue persists for specific functions, you may need to manually augment the type declarations in a local `.d.ts` file.

Warnings

• breaking The `prelude-ls` library is no longer actively maintained, with its last publish occurring approximately six years ago. This means it may not receive updates for new JavaScript features, security vulnerabilities, or compatibility with newer Node.js versions.
  Fix: Consider migrating to a modern, actively maintained functional utility library such as Ramda, Lodash/fp, or a native JavaScript functional approach for new projects. For existing projects, be aware of potential long-term compatibility risks.
• gotcha `prelude-ls` is a CommonJS-only module and does not support ES module `import` syntax natively. Attempting to use `import * as P from 'prelude-ls';` will result in module resolution errors in environments requiring ESM.
  Fix: Always use `const P = require('prelude-ls');` for importing the library in Node.js and other CommonJS environments.
• gotcha The library does not ship with built-in TypeScript type definitions. While an unofficial `@types/prelude-ls` package exists, its accuracy and maintenance status may vary.
  Fix: Install the external type definitions using `npm install --save-dev @types/prelude-ls`. Be prepared to create or augment declaration files (`.d.ts`) for functions not fully covered or if types are outdated.
• gotcha Many functions in `prelude-ls` are curried by default, which can lead to unexpected partial application if not used correctly, especially for developers unfamiliar with this functional programming concept.
  Fix: Ensure you provide all expected arguments to a curried function or explicitly handle the partially applied function. Refer to the prelude.ls documentation on currying for detailed usage examples.
• gotcha The main exported object of `prelude-ls` has many functions directly on it (e.g., `P.map`). However, some functions with the same name behave differently for different data structures (e.g., `List.map` vs `Obj.map`). The top-level `map` typically refers to `List.map`.
  Fix: When working with objects, explicitly use `P.Obj.map` to ensure you are applying the function intended for objects, and similarly for other specific data structure modules.

Install

• npm install prelude-ls npm
• yarn add prelude-ls yarn
• pnpm add prelude-ls pnpm

Imports

• P
  wrong:

  import * as P from 'prelude-ls';

  correct:

  const P = require('prelude-ls');

  This library is CommonJS-only and does not support ES module `import` syntax. The entire library is typically imported as a single object.
• map
  wrong:

  import { map } from 'prelude-ls';

  correct:

  const { map } = require('prelude-ls');

  While possible to destructure, it's more common to import the entire `prelude-ls` object and access functions as `P.map` due to potential name conflicts (e.g., `List.map` vs `Obj.map`).
• Obj.map

  const { Obj } = require('prelude-ls');
  const objectMap = Obj.map;

  Some functions with conflicting names (like `map`) are available directly on sub-modules (e.g., `Obj`, `List`) within the main exported object. Accessing them through their specific module ensures correct behavior.

Quickstart

This quickstart demonstrates how to import `prelude-ls` using CommonJS and utilize its core functional programming utilities, including curried `map`, `filter`, `fold`, and an object-specific `Obj.map` function.

const P = require('prelude-ls');

// Example 1: Basic list mapping with a curried function
const addTwo = P.map(x => x + 2);
const numbers = [1, 2, 3, 4, 5];
const mappedNumbers = addTwo(numbers);
console.log('Mapped numbers:', mappedNumbers); // Expected: [3, 4, 5, 6, 7]

// Example 2: Filtering even numbers, demonstrating currying
const isEven = x => x % 2 === 0;
const filterEven = P.filter(isEven);
const evenNumbers = filterEven(numbers);
console.log('Even numbers:', evenNumbers); // Expected: [2, 4]

// Example 3: Folding (reducing) a list
const sum = P.fold((acc, x) => acc + x, 0);
const total = sum(numbers);
console.log('Sum of numbers:', total); // Expected: 15

// Example 4: Using an object-specific function
const data = { a: 1, b: 2, c: 3 };
const objMapValues = P.Obj.map(x => x * 10);
const mappedObject = objMapValues(data);
console.log('Mapped object:', mappedObject); // Expected: { a: 10, b: 20, c: 30}