Prelude

A pragmatic exploration of functional programming patterns already present in TypeScript (JavaScript).

Project State

The first work-in-progress commit landed in 2019 (a0f7fc6) to capture a few experiments I used to share the FP concepts. A few more WIP commits followed over the years, but it never became a finished repository, mostly for lack of time. The code itself barely changed.

I've pulled patterns from here more often than I expected. Such as when building functional composition utilities in Python for working with async iterators. I've also used it when working with others on improving code composition. The examples help make "hidden patterns" visible: you already have a set of _building blocks, and if you look at their shapes — the interfaces, the contracts — and build new blocks that match, you end up with something naturally composable. That principle isn't exclusive to functional programming, the same applies to OOP, "favor composition over inheritance" points at the same idea.

Now, with tools that make modernizing a codebase trivial, I finally took the time to clean everything up: updating to Bun, aling it with the latest TypeScript, fixing typos, and getting it into a shape where it might be useful to others beyond me pulling things out of it.

I don't think this will ever grow into an actively maintained library; it's a reference that finally made it out of perpetual WIP.

Goals and Non-Goals

Following TypeScript's philosophy to "strike a balance between correctness and productivity," this project aims to:

1. Reveal Hidden Patterns: Show that functional programming concepts (functors, monads, etc.) are already present in everyday JavaScript/TypeScript, just not labeled as such and I might add regrettably not fully present
2. Make FP Approachable: Demonstrate that these seemingly esoteric category theory concepts are actually simple to implement and understand
3. Focus on Composability: Explore the "how" of composition; how to model computations in ways that naturally encapsulate effects and enable flexible combination of components
4. Keep It Simple: Provide minimal, readable implementations that prioritize clarity over theoretical purity

Aligning with TypeScript's design principles, this project does not aim to:

1. Provide a sound type system: We embrace TypeScript's pragmatic trade-offs
2. Implement complete HKT support: We work within TypeScript's limitations creatively
3. Be a production library: This is an educational exploration, not fp-ts

Philosophy

Practical TypeScript <---> Pure Category Theory
         ^
         |
    This Project

We lean heavily toward the practical side, using TypeScript's features creatively:

• Module augmentation for extending built-in types
• Overloading for ergonomic APIs
• Structural typing for flexibility

Sometimes we use different approaches for similar problems (e.g., pipe uses overloading while curry uses advanced types) - choosing whatever makes the concept clearest.

Getting Started

Requires Bun as the runtime and test runner.

# Install dependencies
bun install

# Run tests
bun test

# Build
bun run build

# Typecheck
bun run typecheck

References

TypeScript Design

• TypeScript Design Goals

Production Libraries (if you need them)

• fp-ts - Full-featured FP library
• Effect - Modern effect system

Further Reading

• Functors, Applicatives, And Monads In Pictures
• Fantasy Land
• Static Land