Registry / serialization / fp-ts
library2.16.11jsnpmunverified

fp-ts is a TypeScript library providing tools for typed functional programming, including popular algebraic data types like `Option`, `Either`, `IO`, and `Task`, alongside type classes such as `Functor`, `Applicative`, and `Monad`. It uniquely implements Higher Kinded Types to enable robust functional patterns within TypeScript's type system. The current stable version is 2.16.11, last published approximately 8 months ago as of the current date. While actively maintained, recent announcements indicate that the `fp-ts` project is officially merging with the Effect-TS ecosystem, with Effect-TS being positioned as the successor, akin to `fp-ts v3`. This transition implies a future shift in development focus towards the Effect-TS project, offering enhanced capabilities and support for new users.

npm install fp-ts
INSTALL
IMPORT
SIG · FP-TS
F
fp-ts
serializationjavascriptv2.16.11
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

pipe
import { pipe } from 'fp-ts/function';
const { pipe } = require('fp-ts/function');
The `pipe` function is fundamental for functional composition. While `require` works in CommonJS, ESM `import` is preferred for tree-shaking and modern module resolution.
O (Option namespace)
import * as O from 'fp-ts/Option';
import { Option } from 'fp-ts/Option';
fp-ts modules are typically imported as namespaces (e.g., `* as O`) for brevity and to avoid name collisions. Importing individual constructors like `Option` directly is less idiomatic for module-level exports.
E (Either namespace)
import * as E from 'fp-ts/Either';
import { Either } from 'fp-ts/Either';
Similar to `Option`, `Either` and other Algebraic Data Types (ADTs) are best imported as a namespace for convenient access to all module exports (constructors, combinators, etc.).
T (Task namespace)
import * as T from 'fp-ts/Task';
const T = require('fp-ts/Task');
Task is a core asynchronous type. Consistent use of ESM `import * as T` is recommended for tree-shaking and modern module resolution.

This quickstart demonstrates fetching data, parsing JSON, and safely accessing optional properties using `TaskEither`, `Either`, `Option`, and the `pipe` function for functional composition and error handling. It shows how to chain operations that can fail (HTTP request, JSON parsing) and gracefully handle missing values.

import { pipe } from 'fp-ts/function'; import * as O from 'fp-ts/Option'; import * as E from 'fp-ts/Either'; import * as TE from 'fp-ts/TaskEither'; interface User { id: number; name: string; email?: string; } const fetchUser = (userId: number): TE.TaskEither<Error, string> => TE.tryCatch( () => fetch(`https://jsonplaceholder.typicode.com/users/${userId}`).then( (res) => { if (!res.ok) { throw new Error(`HTTP error! status: ${res.status}`); } return res.text(); }, ), (reason) => new Error(String(reason)), ); const parseJson = (s: string): E.Either<Error, User> => E.tryCatch( () => JSON.parse(s) as User, (reason) => new Error(`Failed to parse JSON: ${String(reason)}`), ); const getUserEmail = (user: User): O.Option<string> => O.fromNullable(user.email); // Example usage: const run = async () => { console.log('Fetching user 1...'); const result = await pipe( fetchUser(1), // Fetch user with ID 1 TE.flatMapEither(parseJson), // Parse the response as JSON, converting TaskEither<Error, string> to TaskEither<Error, User> TE.map(getUserEmail), // Map the User to an Option<string> (email) TE.match( (error) => `Error fetching user 1: ${error.message}`, (emailOption) => pipe( emailOption, O.match( () => 'User 1 email not found.', (email) => `User 1 email: ${email}`, ), ), ), )(); console.log(result); console.log('\nAttempting to fetch non-existent user 999...'); const invalidResult = await pipe( fetchUser(999), // Fetch a non-existent user, likely resulting in an HTTP error TE.flatMapEither(parseJson), // This step will likely be skipped or fail due to the upstream error TE.map(getUserEmail), TE.match( (error) => `Error fetching user 999: ${error.message}`, (emailOption) => pipe( emailOption, O.match( () => 'User 999 email not found.', (email) => `User 999 email: ${email}`, ), ), ), )(); console.log(invalidResult); }; run();
Debug
Known issues
breakingThe `fp-ts` project is officially merging with the Effect-TS ecosystem. Effect-TS is positioned as the successor to `fp-ts v2` (effectively `fp-ts v3`), indicating a significant shift in the future roadmap and potentially requiring migration for new projects or major upgrades.
fix
For new projects or major architectural shifts, consider starting with Effect-TS. For existing `fp-ts v2` projects, continue with `fp-ts` for now, but be aware of the long-term migration path to Effect-TS. Review Effect-TS documentation for compatibility and migration guides.
affects: >=2.16.11
gotchaInstalling multiple versions of `fp-ts` in a single project is known to cause `tsc` to hang during compilation. Ensure only a single version is installed.
fix
Use `npm ls fp-ts` to check installed versions and ensure only one `fp-ts` version is present, or that others are `deduped`. Resolve conflicting dependencies by adjusting package versions or using `npm dedupe`.
affects: >=2.0.0
gotchafp-ts is designed for use with TypeScript's `strict` flag turned on. Developing without strict mode may lead to unexpected type behaviors or errors.
fix
Enable the `strict` flag in your `tsconfig.json` to ensure full type safety and compatibility with fp-ts's design principles.
affects: >=2.0.0
deprecatedThe `chain` and `chainW` functions have been superseded by `flatMap` for most data types (e.g., `Option`, `Either`, `Task`, `Array`). While `chain` is still available, `flatMap` is the preferred and more idiomatic name.
fix
Replace calls to `chain` or `chainW` with their `flatMap` equivalents. For example, `pipe(optionValue, O.chain(f))` becomes `pipe(optionValue, O.flatMap(f))`.
affects: >=2.14.0
deprecatedFunctions like `mapLeft` (for `Either`, `These`, etc.) and `bimap` have been aliased or replaced by `mapError` and `mapBoth` respectively for consistency.
fix
Update usage from `mapLeft` to `mapError` and `bimap` to `mapBoth` where applicable to align with the latest API naming conventions.
affects: >=2.16.0
breakingVersion `2.13.0` was identified as a 'BROKEN RELEASE' due to issues with the `exports` field in `package.json`, which affected module resolution in `node12/nodenext` environments and could lead to import errors.
fix
Avoid using `fp-ts@2.13.0`. Upgrade to `2.13.1` or newer immediately if you encounter module resolution issues related to this version.
affects: 2.13.0
Errors
Common errors & fixes
tsc hangs during compilation
Multiple versions of `fp-ts` are installed in your `node_modules` tree, confusing TypeScript's module resolution.
fix
Run `npm ls fp-ts` to identify duplicate versions. Use `npm dedupe` or manually adjust your `package.json` dependencies to ensure only a single `fp-ts` version is installed and deduped.
ReferenceError: require is not defined
Attempting to use CommonJS `require()` syntax for `fp-ts` modules in an ECMAScript Module (ESM) environment (e.g., Node.js with `"type": "module"` or certain bundler configurations).
fix
Migrate your imports to ESM syntax: `import { pipe } from 'fp-ts/function';` instead of `const { pipe } = require('fp-ts/function');`.
Property 'pipe' does not exist on type 'typeof import("/node_modules/fp-ts/lib/function")'
Incorrect import path for `pipe` or other utilities, or a TypeScript configuration that doesn't correctly resolve module exports, especially if migrating from older versions or different module systems.
fix
Ensure you are using the correct import path `import { pipe } from 'fp-ts/function';`. Verify your `tsconfig.json` `moduleResolution` and `module` settings are compatible with modern Node.js or your bundler (e.g., `"moduleResolution": "bundler"` or `"node16"`).
Type 'Foo' is not assignable to type 'Bar'. Argument of type 'Foo' is not assignable to parameter of type 'Bar'.
Type errors commonly arise when TypeScript's `strict` mode is disabled, leading to `fp-ts` functions inferring looser types than expected, or when `fp-ts` ADTs are not handled exhaustively or correctly.
fix
Enable `"strict": true` in your `tsconfig.json`. Ensure all possible cases of ADTs (e.g., `None`/`Some` for `Option`, `Left`/`Right` for `Either`) are handled using `match`, `fold`, or type guards.
Upgrade
Version history
2.16.11latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
2 hits · last 30 days
node
2
Resources