fp-ts

What is fp-ts?

The fp-ts npm package is a library for functional programming in TypeScript. It provides developers with tools to write code in a functional style, leveraging concepts like type-safe functional combinators, monads, and other abstractions that enable expressive and concise code.

What are fp-ts's main functionalities?

Option Type

The Option type represents encapsulation of an optional value. A value of type Option<T> can either be some<T> if it exists or none if it does not. This is useful for handling cases where a value might be missing without resorting to null or undefined.

import { Option, some, none } from 'fp-ts/Option';

function find<T>(predicate: (a: T) => boolean, arr: T[]): Option<T> {
  for (const item of arr) {
    if (predicate(item)) {
      return some(item);
    }
  }
  return none;
}

const result = find(x => x > 10, [1, 2, 3]);
console.log(result); // output: none

Either Type

The Either type represents a value of one of two possible types (a disjoint union). An instance of Either is either an instance of left or right. It is useful for error handling where left can be used to hold an error value and right can hold a success value.

import { Either, left, right } from 'fp-ts/Either';

function divide(a: number, b: number): Either<string, number> {
  return b === 0 ? left('Cannot divide by zero') : right(a / b);
}

const result = divide(10, 0);
console.log(result); // output: left('Cannot divide by zero')

IO Type

The IO type represents a computation that can perform side effects when executed. It is a way to manage side effects in a functional way by deferring their execution.

import { IO } from 'fp-ts/IO';

const log: IO<void> = () => console.log('Hello, fp-ts!');

log(); // output: 'Hello, fp-ts!'

Function Composition

Function composition is a core concept in functional programming, allowing you to combine multiple functions into a single function. The flow function from fp-ts helps you to compose functions easily.

import { flow } from 'fp-ts/function';

const toUpperCase = (s: string) => s.toUpperCase();
const exclaim = (s: string) => `${s}!`;
const shout = flow(toUpperCase, exclaim);

console.log(shout('hello')); // output: 'HELLO!'

Other packages similar to fp-ts

ramda

Ramda is a popular functional programming library for JavaScript. It emphasizes a functional style and provides many utilities for working with functions and data. Compared to fp-ts, Ramda is less focused on type safety and does not provide as many abstractions related to category theory.

sanctuary

Sanctuary is a functional programming library that provides type-safe functional data types and utility functions. It is similar to fp-ts in its emphasis on type safety and functional programming concepts, but it has its own set of abstractions and API design choices.

README

Functional programming in TypeScript

Typed functional programming in TypeScript

fp-ts is a library for typed functional programming in TypeScript.

fp-ts aims to allow developers to use popular patterns and abstractions that are available in most functional languages. For this, it includes the most popular data types, type classes and abstractions such as Option, Either, IO, Task, Functor, Applicative, Monad to empower users to write pure FP apps and libraries built atop higher order abstractions.

A distinctive feature of fp-ts with respect to other functional libraries is its implementation of Higher Kinded Types, which TypeScript doesn't support natively.

Inspired by

• Haskell
• PureScript
• Scala

Table of contents

• Installation
  • TypeScript compatibility
• Documentation
• Development
• License

Installation

To install the stable version:

npm install fp-ts

Make sure to always have a single version of fp-ts installed in your project. Multiple versions are known to cause tsc to hang during compilation. You can check the versions currently installed using npm ls fp-ts (make sure there's a single version and all the others are marked as deduped).

Consuming fp-ts

Most examples will use the following import syntax:

import { Option, some, none } from 'fp-ts/lib/Option'

This will give you the widest support across tools, as you will be importing CommonJS modules.

If you use a bundler such as webpack or Rollup that supports tree-shaking, you can take advantage of this by opting to import ECMAScript modules instead:

import { Option, some, none } from 'fp-ts/es6/Option'

Note that there are caveats such as some tools (e.g. Jest) not supporting ES6 module syntax natively yet.

TypeScript compatibility

Strictness – This library is conceived, tested and is supposed to be consumed by TypeScript with the strict flag turned on.

fp-ts version	required typescript version
2.0.x+	3.5+
1.15.x+	3.1+
<= 1.14.4	2.8+ (*)

(*) If you are running < typescript@3.0.1 you have to polyfill the unknown type. You can use unknown-ts as a polyfill.

Documentation

• Docs
• Tutorial
• Ecosystem
• API Reference
  • version 2.x (current)
  • version 1.x

Development

• Code conventions

License

The MIT License (MIT)

Changelog

2.0.3

• Bug Fix
  • fix sequenceT, sequenceS implementations, closes #914 (@gcanti)