fp-lib/README.md

Functional Programming Library Documentation

Table of Contents

1. Overview
2. Either Module
3. List Module
4. Option Module
5. Utility Module
6. Bun Extensions

Overview

This zero-dependency functional programming library provides type-safe implementations of common FP constructs optimized for Bun runtime. Core features include:

• Either for error handling
• Option for nullable values
• Immutable linked List
• Do-notation for monadic composition
• Bun-specific file and environment utilities

Either Module

Represents computations that can succeed (Right) or fail (Left).

Types

type Left<E> = { readonly _tag: 'Left'; readonly left: E }
type Right<A> = { readonly _tag: 'Right'; readonly right: A }
type Either<A, E> = Left<E> | Right<A>

Constructors

Function	Description	Example
left<E>(e: E)	Creates failure case	left('error')
right<A>(a: A)	Creates success case	right(42)

Operations

Function	Description	Type Signature
eitherMap	Maps over success value	<A, B, E>(f: (a: A) => B) => (fa: Either<A, E>) => Either<B, E>
eitherChain	Chains Either-returning functions	<A, B, E>(f: (a: A) => Either<B, E>) => (fa: Either<A, E>) => Either<B, E>
fold	Handles both cases	<A, E, B>(onLeft: (e: E) => B, onRight: (a: A) => B) => (fa: Either<A, E>) => B

Do Notation

const result = DoEither.start<{ x: number }, string>()
  .bind('x', right(5))
  .bind('y', right(10))
  .return(scope => scope.x + scope.y)

// Returns Either<number, string>

Method	Description
bind(key, either)	Binds named value from Either
return(f)	Transforms final scope
do(either)	Executes effect without binding
doL(f)	Executes scope-dependent effect

List Module

Immutable linked list implementation.

Types

type Nil = { readonly _tag: 'Nil' }
type Cons<A> = {
  readonly _tag: 'Cons'
  readonly head: A
  readonly tail: List<A>
}
type List<A> = Nil | Cons<A>

Constructors

Function	Description	Example
nil	Empty list	nil
cons	Creates list node	cons(1, cons(2, nil))
fromArray	Converts array to list	fromArray([1, 2, 3])

Operations

Function	Description	Type Signature
listMap	Transforms list elements	<A, B>(f: (a: A) => B) => (fa: List<A>) => List<B>
listReduce	Reduces list to value	<A, B>(f: (b: B, a: A) => B, initial: B) => (fa: List<A>) => B
toArray	Converts list to array	<A>(fa: List<A>) => Array<A>

Option Module

Represents optional values (Some or None).

Types

type None = { readonly _tag: 'None' }
type Some<A> = { readonly _tag: 'Some'; readonly value: A }
type Option<A> = None | Some<A>

Constructors

Function	Description	Example
none	Empty value	none
some	Wraps a value	some(42)
fromNullable	Converts nullable	fromNullable(null) → none

Operations

Function	Description	Type Signature
map	Transforms value	<A, B>(f: (a: A) => B) => (fa: Option<A>) => Option<B>
chain	Chains computations	<A, B>(f: (a: A) => Option<B>) => (fa: Option<A>) => Option<B>
getOrElse	Default value	<A>(defaultValue: A) => (fa: Option<A>) => A

Do Notation (Sync)

DoOption.start()
  .bind('user', getUser())
  .bind('profile', getProfile())
  .return(scope => `${scope.user.name}: ${scope.profile.bio}`)

Async Do Notation

AsyncDoOption.start()
  .bind('user', fetchUser())
  .bindL('posts', scope => fetchPosts(scope.user.id))
  .return(scope => renderPage(scope))

Async Method	Description
bind(key, promise)	Binds async Option
bindL(key, f)	Binds scope-dependent async Option
do(promise)	Executes async effect
doL(f)	Executes scope-dependent async effect

Utility Module

Function Composition

Function	Description	Example
pipe	Left-to-right composition	pipe(1, x => x+1, x => x*2) → 4
compose	Right-to-left composition	compose(x => x*2, x => x+1)(1) → 4

Error Handling

Function	Description	Example
tryCatch	Safely execute function	tryCatch(() => JSON.parse(str))

Type Utilities

Function	Description
hasTag	Creates tag predicate

Bun Extensions

Optimized utilities for Bun runtime.

File Operations

Function	Description	Type Signature
readFileSafe	Reads file safely	(path: string) => Promise<Either<string, Error>>
listToFile	Writes list to file	(list: List<string>, path: string) => Promise<Either<void, Error>>

JSON & Environment

Function	Description
safeJsonParse	Safe JSON parsing
envOption	Environment variable as Option

Server Utilities

Function	Description	Example
createServer	Creates HTTP server	createServer(handleRequest)
asyncReduce	Async list reduction	asyncReduce(list, reducer, initial)

Server Example

const handleRequest = (req: Request): Either<Response, Error> => {
  return req.url === '/'
    ? right(new Response('Hello'))
    : left(new Error('Not found'))
}

createServer(handleRequest)