or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

algebraic.mdarray.mdeither.mdfunction.mdindex.mdio.mdoption.mdpipeable.mdrecord.mdtask-either.mdtask.mdtype-classes.md
tile.json

index.mddocs/

fp-ts

fp-ts is a library for typed functional programming in TypeScript. It provides essential data types, type classes, and abstractions from functional programming, implementing Higher Kinded Types which TypeScript doesn't natively support. The library enables developers to write pure functional programs with mathematical precision and type safety.

Package Information

  • Package Name: fp-ts
  • Package Type: npm
  • Language: TypeScript
  • Installation: npm install fp-ts

Core Imports

import { option, either, array, io, task, record } from "fp-ts";
import { Option, some, none } from "fp-ts/lib/Option";
import { Either, left, right } from "fp-ts/lib/Either";
import { pipe } from "fp-ts/lib/pipeable";
import { pipeable } from "fp-ts/lib/pipeable";

For CommonJS:

const { option, either, array, io, task, record } = require("fp-ts");
const { Option, some, none } = require("fp-ts/lib/Option");
const { Either, left, right } = require("fp-ts/lib/Either");
const { pipe, pipeable } = require("fp-ts/lib/pipeable");

Basic Usage

import { some, none, Option } from "fp-ts/lib/Option";
import { left, right, Either } from "fp-ts/lib/Either";
import { pipe } from "fp-ts/lib/pipeable";

// Working with optional values
const maybeValue: Option<number> = some(42);
const emptyValue: Option<number> = none;

// Pattern matching
const result = maybeValue.fold(
  () => "No value",
  (value) => `Value: ${value}`
);

// Working with Either for error handling
const parseNumber = (input: string): Either<string, number> => {
  const num = parseInt(input, 10);
  return isNaN(num) ? left("Invalid number") : right(num);
};

// Chain operations
const doubled = parseNumber("21")
  .map(n => n * 2)
  .fold(
    error => `Error: ${error}`,
    value => `Result: ${value}`
  );

Architecture

fp-ts is built around several core concepts:

  • Higher Kinded Types (HKT): Type-level encoding allowing generic programming over type constructors
  • Data Types: Core abstractions like Option, Either, IO, Task for modeling different computational contexts
  • Type Classes: Mathematical abstractions like Functor, Monad, Semigroup providing generic operations
  • Combinators: Small, composable functions that can be combined to build complex functionality
  • Pipeable Operations: Modern functional style using pipe() for chaining operations
  • Lawful Instances: All implementations follow mathematical laws ensuring predictable behavior

Capabilities

Option Type

Safe handling of nullable values with explicit presence/absence modeling.

type Option<A> = Some<A> | None<A>;

function some<A>(a: A): Option<A>;
const none: Option<never>;
function fromNullable<A>(a: A | null | undefined): Option<A>;

Option Operations

Either Type

Modeling computations that may fail with explicit error handling.

type Either<L, A> = Left<L, A> | Right<L, A>;

function left<L, A>(l: L): Either<L, A>;
function right<L, A>(a: A): Either<L, A>;
function fromOption<L>(onNone: L): <A>(fa: Option<A>) => Either<L, A>;

Either Operations

Array Operations

Functional array operations with type safety and immutability.

function getMonoid<A>(): Monoid<Array<A>>;
function getEq<A>(E: Eq<A>): Eq<Array<A>>;

Array Operations

IO Type

Synchronous side-effectful computations with explicit effect modeling.

class IO<A> {
  constructor(run: () => A);
  run(): A;
}

function io<A>(a: A): IO<A>;

IO Operations

Task Type

Asynchronous computations that never fail.

class Task<A> {
  constructor(run: () => Promise<A>);
  run(): Promise<A>;
}

function task<A>(a: A): Task<A>;

Task Operations

Task Either Type

Asynchronous computations that may fail with error handling.

type TaskEither<L, A> = Task<Either<L, A>>;

function left<L, A>(l: L): TaskEither<L, A>;
function right<L, A>(a: A): TaskEither<L, A>;
function tryCatch<A>(f: () => Promise<A>): TaskEither<Error, A>;

TaskEither Operations

Type Classes

Mathematical abstractions providing generic operations across different data types.

interface Functor<F> {
  map: <A, B>(fa: HKT<F, A>, f: (a: A) => B) => HKT<F, B>;
}

interface Monad<F> extends Applicative<F>, Chain<F> {}

interface Semigroup<A> {
  concat: (x: A, y: A) => A;
}

Type Classes

Function Utilities

Core function manipulation and composition utilities.

function identity<A>(a: A): A;
function constant<A>(a: A): () => A;
type Predicate<A> = (a: A) => boolean;
type Refinement<A, B extends A> = (a: A) => a is B;

Function Utilities

Algebraic Structures

Mathematical structures like Semigroup, Monoid, Group providing composable operations.

interface Semigroup<A> {
  concat: (x: A, y: A) => A;
}

interface Monoid<A> extends Semigroup<A> {
  empty: A;
}

Algebraic Structures

Pipeable Operations

Modern functional programming utilities for chainable operations using the pipe function.

function pipe<A>(a: A): A;
function pipe<A, B>(a: A, ab: (a: A) => B): B;
function pipe<A, B, C>(a: A, ab: (a: A) => B, bc: (b: B) => C): C;
// ... continues up to 10 parameters

function pipeable<F>(I: { URI: F } & I): PipeableOperators<F, I>;

Pipeable Operations

Record Operations

Functional utilities for working with JavaScript objects as immutable records.

function map<A, B>(f: (a: A) => B, d: Record<string, A>): Record<string, B>;
function filter<A>(predicate: Predicate<A>, d: Record<string, A>): Record<string, A>;
function collect<A, B>(f: (k: string, a: A) => B, d: Record<string, A>): Array<B>;
function lookup<A>(k: string, d: Record<string, A>): Option<A>;

Record Operations

Validation

Accumulating validation errors while preserving successful values.

type Validation<L, A> = Either<L, A>;

function getApplicative<L>(S: Semigroup<L>): Applicative2C<URI, L>;
function getAlt<L>(S: Semigroup<L>): Alt2C<URI, L>;

Validation

Types

// Higher Kinded Types
interface HKT<URI, A> {
  readonly _URI: URI;
  readonly _A: A;
}

// Option
type Option<A> = Some<A> | None<A>;
class Some<A> {
  constructor(readonly value: A);
}
class None<A> {
  readonly _tag: 'None';
}

// Either
type Either<L, A> = Left<L, A> | Right<L, A>;
class Left<L, A> {
  constructor(readonly value: L);
}
class Right<L, A> {
  constructor(readonly value: A);
}

// Function types
type Lazy<A> = () => A;
type Predicate<A> = (a: A) => boolean;
type Refinement<A, B extends A> = (a: A) => a is B;
type Endomorphism<A> = (a: A) => A;