gcanti/fp-ts
github.com/gcanti/fp-ts ↗ · 429 files · 3.9 MB
Functional programming in TypeScript 📢 Important Announcement: fp-ts is Joining the Effect-TS Ecosystem!
Overview
fp-ts 2.16.11 is a TypeScript library for developers composing typed functional programs through Option, Either, lazy effects, collections, and algebraic interfaces. Its distinctive architecture uses higher-kinded type dictionaries and explicit instance objects to share combinators across different computational contexts. This brief examines commit c0a6472121c67a2b083e62fcff13e7d022e39d8f through bounded source inspection, including consumer pipelines, asynchronous execution, mutable references, and package assembly; nothing was executed.
System map
The inspected system is a library whose consumers import functions and instance dictionaries. Its runtime representations use tagged objects, ordinary collections, and functions; higher-kinded types connect these representations at compile time. Package assembly produces two JavaScript module formats and declarations, with special handling for HKT identity. Repository tooling provides linting, runtime tests, type assertions, documentation generation, and publication.
- package.json identifies version 2.16.11 and exposes lib/index.js, es6/index.js, and lib/index.d.ts; it declares sideEffects:false, while the getting-started guide explicitly describes a library without runtime dependencies.
- src/index.ts is a namespace barrel importing modules such as Option, Either, IO, TaskEither, and ReaderTaskEither; its exported names include lowercase namespaces and aliases for reserved words.
- HKT.ts defines HKT through HKT4, open URItoKind dictionaries, URI key unions, and Kind projections; Option and Either register their concrete types through module augmentation.
- Runtime boundaries are explicit: IO<A> is () => A, Task<A> is () => Promise<A>, and TaskEither<E,A> extends Task<Either<E,A>>.
- ReaderTaskEither receives a caller-supplied environment and returns a TaskEither; State receives state and returns [value,state], while IORef stores a private mutable value in an object.
- npm run build compiles CommonJS and ES modules before executing scripts/build.ts; that script copies package metadata and documentation, generates module manifests, then fixes HKT paths.
- The configured npm test chain runs ESLint, Prettier, dtslint, Vitest, and docs-ts; GitHub Actions installs dependencies, builds, and runs that chain on Ubuntu with Node 20.12.2.
- Documentation uses docs-ts with src/internal.ts excluded and a Just the Docs site configuration; release executes npm publish from dist, while the root prepublishOnly script deliberately fails.
Feature catalog
The user-facing surface consists of TypeScript APIs for representing values, composing computations, and selecting algebraic behavior. The inspected modules cover optionality, typed failures, asynchronous effects, functional collections, explicit environments, state, and accumulated output. Generic algorithms let callers choose execution and combination policies through instances. This catalog groups the examined capabilities and does not claim exhaustive coverage of every exported symbol.
- Option exposes None/Some, nullable conversion, exception-to-None conversion, map/flatMap, pattern matching, and lazy fallback extraction through getOrElse.
- Either models Left<E>/Right<A>, maps successful values, sequences computations with error unions, and converts synchronous exceptions using a caller-provided onThrow function.
- Task and TaskEither support lazy asynchronous computation, parallel or sequential application, indexed traversal, Promise adapters, and acquire/use/release composition.
- Array and ReadonlyArray provide mapping, flattening, optional lookup/update, sorting by Ord, filterMap, and traversal parameterized by an Applicative.
- ReadonlyMap supports equality-based key lookup and copy-on-change upsert; ReadonlySet builds deduplicated sets and performs union/intersection using a supplied Eq rather than relying only on native identity.
- Eq provides custom equality and structural/tuple composition; Ord adds comparison and tuple ordering; Apply.sequenceT and sequenceS collect heterogeneous effects into tuples or records.
- ReaderTaskEither combines dependencies with typed asynchronous failures, State exposes get/put/modify and result/state projections, and Writer exposes tell/listen plus Monoid-driven accumulation.
- Additional examined APIs include Tree.make/getEq, These's simultaneous Both case, Json.parse/stringify, and lazy console and Math.random wrappers.
Data flow
Values enter through constructors, conversion functions, or caller-supplied effect functions. Tagged branches determine whether transformations continue, while instance arguments determine how generic algorithms combine results. Effects execute at explicit function invocation boundaries, and environments or state remain caller-provided values. Persistent file output appears in package tooling; the inspected library state mechanisms operate through tuples or process-local references.
- Option constructors produce {_tag:'Some',value} or the shared None object; Either constructors produce {_tag:'Left',left} or {_tag:'Right',right}, and branch checks inspect _tag.
- pipe applies transformations to an initial value in order; flow builds a composed function and passes the original arguments and this context to its first function.
- Json.parse sends a string through JSON.parse inside Either.tryCatch; successful data becomes Right<Json>, and the original thrown value becomes Left<unknown> through identity.
- IO.flatMap creates a thunk that invokes ma(), feeds its value to f, then invokes the returned IO; Task.flatMap performs the corresponding sequence through Promise.then.
- TaskEither.flatMap delegates to EitherT.flatMap(Task.Monad): the underlying effect resolves first, Left is lifted unchanged, and only Right is passed to the continuation.
- ReaderTaskEither's continuation types intersect required environments and union errors; its underlying ReaderTask/ReaderT sequencing supplies the same environment to both computation stages.
- State.flatMap threads the returned state into the next function without a hidden store; IORef.write/modify instead update the reference's private field when their IO thunks execute.
- Package output flows from package.json through FileSystem.readFile, Json.parse, removal of development metadata, and FileSystem.writeFile; filesystem callback errors become Left through taskify and reach run's error logger/exit code.
Behavior traces
Eight source walks describe consumer and maintainer behavior without executing it. The primary consumer paths cover optional-value extraction, JSON decoding, asynchronous failures, concurrent and sequential traversal, cleanup, and mutable references. The package path follows compilation through generated artifact assembly. Each trace identifies execution order and the branch that changes subsequent work.
- Getting-started flow: inverse(2) constructs Some(0.5), pipe invokes Option.map to construct Some(50), then getOrElse extracts 50; inverse(0) produces None, skips map's callback, and evaluates the fallback.
- JSON flow: Json.parse → Either.tryCatch → JSON.parse → right on success or left(identity(error)) on throw; a subsequent Either.map runs only for Right.
- Promise flow: tryCatchK captures arguments and constructs tryCatch; invoking the returned TaskEither calls f, awaits its Promise, and converts rejection or synchronous throw to Left; flatMap then preserves Left or invokes the Right continuation.
- Parallel traversal: TaskEither.traverseReadonlyArrayWithIndex chooses ApT for empty input; otherwise Task traversal starts every indexed thunk through Promise.all, then Either traversal collects Rights or selects the first Left in input order.
- Sequential traversal: the Seq helper invokes f(0,head) first, chains each remaining element through a Promise reduction, appends successful values, and skips later f invocations once the accumulated result is Left.
- Resource flow: bracket delegates to bracketW; failed acquisition skips use/release, successful acquisition executes use, then release receives its resolved Either; release Left overrides the use result, while successful release restores that result.
- Reference flow: newIORef(1) returns an allocation thunk; IO.flatMap invokes it, ref.write(2) returns a mutation thunk, the next IO.flatMap executes that write, and ref.read observes the updated private value.
- Build flow: npm's prebuild cleans dist, two tsc configurations emit JavaScript/declarations, then main runs copyPackageJson → copyFiles → makeModules → fixHKT('es6') → fixHKT('lib'); run invokes the assembled effect and sets the process exit code.
Testing signals
Tests and CI were inspected, not executed; no passing result, coverage percentage, or benchmark result is established by this investigation. Runtime examples use Vitest globals and Node assertions, while dtslint separately checks inferred public types. The inspected cases exercise conversion boundaries, cleanup branches, traversal execution, references, serialization, and barrel exports. Coverage remains bounded, and several source-level limitations require distinguishing test intent from actual assertions.
- Vitest discovers test files under test/, excludes util.ts as a test entry, enables globals, and uses Istanbul for coverage; test/util.ts wraps Node assert.deepStrictEqual and assert.strictEqual.
- Inspected CI runs npm install → npm run build --if-present → npm test on Node 20.12.2; npm test includes lint, formatting, dtslint, runtime tests, and docs, but the shown workflow does not invoke the separate coverage script.
- dtslint/TaskEither.ts uses $ExpectType assertions for fallback unions and error transformations; dtslint has its own config extending the root config and disabling noUnusedLocals.
- TaskEither tests cover taskify's null/undefined error callbacks, callback errors, and repeated invocation; tryCatchK tests separately cover resolved Promises, rejected Promises, and synchronous throws.
- bracket tests enumerate acquisition, use, and release Left branches and release precedence; the case named 'body throws' actually supplies useFailure returning Left, so it does not demonstrate cleanup after a rejected Promise.
- TaskEither traversal tests assert that parallel execution still runs a later Right after an earlier Left, while sequential execution skips it; shared timing helpers also assert ApplicativePar versus ApplicativeSeq ordering.
- IORef tests cover read/write/modify and bound-method piping; Json tests cover valid/invalid parsing, circular serialization, and undefined; the index test checks that source modules other than internal/index appear in the barrel.
- Array and ReadonlyArray include fast-check chunksOf properties, but their generated predicates discard isDeepStrictEqual's result; the examined performance file constructs a Benchmark.Suite, and its historical comments were not treated as verified measurements.
Risk map
These are source observations and explicitly labeled hypotheses, not confirmed vulnerabilities or reproduced failures. Sensitive boundaries in the inspected files include foreign callbacks, Promise rejection, filesystem operations, and npm publication. Searches across the examined public source and tooling were bounded; they do not establish whole-repository absence of authentication, secrets handling, networking, or other security behavior. Compatibility and test reliability deserve attention alongside runtime failure handling.
- bracket's cleanup guarantee explicitly concerns Left results; bracketW uses Promise sequencing without finally/catch around use, so an arbitrary rejected use Promise does not follow the release continuation shown here.
- taskify resolves callback errors to Left but calls the foreign function inside a Promise executor without a catch-to-Left adapter; it also applies the function with a null receiver, making thrown errors and receiver-dependent APIs distinct integration cases.
- Default TaskEither traversal launches all input effects through Promise.all before examining Either outcomes; returning Left therefore does not cancel or prevent other effects, as the side-effect log test demonstrates.
- The build FileSystem adapter accepts arbitrary path strings and delegates directly to Node fs operations without root validation; inspected build call sites use package-relative inputs and dist outputs, so containment depends on their path construction and working directory.
- npm run release has a prerelease build hook and ultimately invokes child_process.exec('npm publish',{cwd:'dist'}); root prepublishOnly rejects publication, but the release path deliberately bypasses that root location.
- Both examined chunksOf property predicates compute isDeepStrictEqual(as,bs) without returning or asserting it; their explicit example assertion remains, but generated unequal results are not surfaced by that comparison statement.
- Packaging/compatibility hypothesis: HKT.js and HKT.d.ts are moved during build, with both output formats targeting one shared declaration; changes here could disrupt URI module augmentation, and README warns that multiple installed fp-ts versions can cause compilation hangs. (inferred)
- Version-sensitive observations: package.json reports 2.16.11 while the lockfile root reports 2.16.7, and Json.parse's invalid-input test compares against a specific SyntaxError message; neither mismatch was executed or shown to fail.
Extension points
Extension primarily happens through TypeScript interfaces and explicit instance arguments. New data types register with HKT dictionaries, then provide operations satisfying the relevant type classes. Existing factories accept caller-defined equality, ordering, error combination, and output accumulation policies. Maintainer tooling also exposes an injectable filesystem boundary and automatically derives packaged module entries from compiler output.
- A new data type can add a URI key through URItoKind module augmentation and supply Functor1-style instances; the HKT guide demonstrates this with Identity and explains the lookup mechanism.
- Type classes support multiple constructor arities and constrained variants; Functor2 keeps E generic, whereas Functor2C fixes E and includes an _E witness.
- getApplicativeTaskValidation accepts a Task Apply instance and Semigroup<E>, allowing callers to choose execution policy and error concatenation instead of default first-error application.
- Eq.fromEquals, Eq.struct, Eq.tuple, and Ord.fromCompare let consumers define domain comparison policies; ReadonlyMap.upsertAt then uses supplied key equality to preserve an existing equivalent key.
- ReadonlyArray.traverseWithIndex accepts an Applicative and combines results through of/map/ap; sequenceT and sequenceS similarly receive Apply instances, so their execution semantics come from the supplied dictionary.
- FromEither interfaces expose a lifting operation across HKT arities; chainOptionK combines that capability with Chain and an onNone callback to derive effect-specific Option sequencing.
- Writer.getMonad receives a Monoid<W> and assembles Applicative/Chain behavior; getChain combines output from both stages using the caller's Semigroup.concat.
- Build computations receive a FileSystem environment that can be replaced structurally; module packaging derives names from dist/lib/*.js, excludes index, and writes per-module main/module/typings manifests.
Contributor handoff
Begin with the affected public module, its shared helpers, runtime tests, and type assertions. Preserve inferred types, laziness, branch behavior, and compatibility aliases when making small changes. Tests and CI were inspected, not executed; any later validation must report actual commands and outcomes separately. This inventory is bounded and should guide targeted investigation rather than substitute for complete coverage.
- Read package.json, tsconfig.json, and vite.config.ts first: they distinguish source compilation, global test typing, runtime discovery, and the multi-stage npm test command.
- Consumer code is expected to enable strict TypeScript and import individual fp-ts/<module> paths; the README also requires a single installed fp-ts version.
- Follow established syntax and checks: no semicolons, single quotes, width 120, no trailing commas; ESLint requires sorted imports, rejects import cycles, and forbids spread arguments to Array.push.
- For combinator edits, distinguish data-last public functions from instance adapters and dual overloads; preserve W widening, K lifting, E effectful matching, and constrained C instance conventions.
- A new public source module needs barrel exposure: test/index.ts derives expected export names from source files, and scripts/build.ts derives module manifests from emitted JavaScript, with HKT handled specially.
- Keep @since/@category documentation and compatibility exports deliberate: TaskEither's deprecated taskEither/taskEitherSeq dictionaries remain exported, with guidance to prefer smaller instances; docs-ts excludes internal.ts.
- Tests and CI were inspected, not executed. For later authorized validation, the existing Vitest script can target the affected test file, dtslint checks signature inference, and npm test runs the full configured chain; coverage is a separate command.
- Execution traps include prebuild deleting dist, postbuild rewriting generated declarations, npm test generating docs, and release publishing to npm; read-only onboarding must inspect these definitions without invoking them.
Languages
| Language | Files | Share of source |
|---|---|---|
| TypeScript | 271 | 100% |
| Markdown | 140 | docs/config |
| JSON | 9 | docs/config |
| YAML | 3 | docs/config |
| HTML | 1 | docs/config |
| Sass | 1 | 0% |
Start reading here
Probable source entrypoint: src/ — inferred from the directory tree and manifest, not the upstream docs.
Source roots
src/ (123 files)
Source layout — src/
| Path | Files |
|---|---|
src/Alt.ts | 1 |
src/Alternative.ts | 1 |
src/Apply.ts | 1 |
src/Array.ts | 1 |
src/Bifunctor.ts | 1 |
src/BooleanAlgebra.ts | 1 |
src/BoundedMeetSemilattice.ts | 1 |
src/Category.ts | 1 |
src/ChainRec.ts | 1 |
src/Compactable.ts | 1 |
src/Const.ts | 1 |
src/Date.ts | 1 |
src/EitherT.ts | 1 |
src/FilterableWithIndex.ts | 1 |
Repository structure
| Top-level path | Files |
|---|---|
docs/ | 135 |
src/ | 123 |
test/ | 81 |
dtslint/ | 44 |
perf/ | 15 |
scripts/ | 6 |
.github/ | 6 |
examples/ | 3 |
Docs found: README.mddocs/ecosystem.mddocs/guides/HKT.mddocs/guides/code-conventions.mddocs/guides/do-notation.mddocs/guides/getting-started.mddocs/guides/index.mddocs/guides/purescript.mddocs/guides/upgrade-to-v2.mddocs/index.md
Package
package.json — fp-ts v2.16.11, 24 declared dependencies.
@effect/dtslint@effect/language-service@types/benchmark@types/chai@types/glob@types/node@typescript-eslint/eslint-plugin@typescript-eslint/parser@vitest/coverage-istanbulbenchmarkdocs-tseslint
CI & config entrypoints
README.md— Repository readmesrc/index.ts— TS entrypoint.github/workflows/main.yml— GitHub Actions workflowvite.config.ts— Vite configpackage.json— npm scripts: build, clean, coverage, docs, dpdm, dtslint, fix-prettier, lint
Structural health signals
Average score 7.1/10 across 96 analyzed source files; 18 hotspots surfaced.
test/ReadonlyArray.ts— 1455 lines, score 5 (Large file, Deep nesting)test/Array.ts— 1218 lines, score 5 (Large file, Deep nesting)test/ReadonlyMap.ts— 1221 lines, score 5.5 (Large file, Deep nesting)
These are deterministic review leads — size, churn, and structural signals — not proof of a bug in this project.
Recent history
c0a6472121c62026-04-20 — Fix learning resources link8e1f04d9116b2026-04-20 — docs: add Getting Started guide with installation instructions (#1968)09045f5819af2025-08-18 — version 2.16.11 (#1964)530394a7a5c12025-08-18 — 1962 fix option get ord compare when comparing equality of options (#1963)e91bde112e0a2025-04-18 — version 2.16.10 (#1959)