jordanburke-functype

Functype

A Functional Programming Library for TypeScript

Functype is a lightweight functional programming library for TypeScript, drawing inspiration from functional programming paradigms, the Scala Standard Library, and ZIO. It provides a comprehensive set of utilities and abstractions designed to facilitate functional programming within TypeScript applications.

API Documentation

CLI Documentation

Get LLM-optimized API reference directly in your terminal:

npx functype              # Overview of all types
npx functype Option       # Detailed info for Option type
npx functype interfaces   # All interface definitions
npx functype --json       # JSON output for programmatic use

Core Principles

• Zero Dependencies: No third-party runtime dependencies — just TypeScript
• Immutability: All data structures are immutable, promoting predictable and side-effect-free code
• Type Safety: Leverages TypeScript's type system to ensure compile-time safety
• Composability: Provides abstractions for building complex programs from simple components
• Functional Paradigms: Embraces concepts like monads, functors, and type classes
• Unified Interface: All data structures implement a common hierarchy of interfaces for consistency

Key Features

• Option Type: Handle nullable values with Some and None types
• Either Type: Express computation results with potential failures using Left and Right
• List, Set, Map: Immutable collection types with functional operators
• Try Type: Safely execute operations that might throw exceptions
• Do-notation: Scala-like for-comprehensions with optimized List performance (up to 12x faster than traditional flatMap)
• Task: Handle synchronous and asynchronous operations with error handling
• Http: Typed HTTP fetch wrapper returning IO effects with HttpError ADT, auto content-type detection, and configurable clients
• Lazy: Deferred computation with memoization
• Tuple: Type-safe fixed-length arrays
• Typeable: Runtime type identification with compile-time safety
• Branded Types: Nominal typing in TypeScript's structural type system
• Error Formatting: Utilities for improved error visualization and logging
• Unified Type Classes: Consistent interfaces across all data structures

Installation

# NPM
npm install functype

# Yarn
yarn add functype

# PNPM
pnpm add functype

# Bun
bun add functype

Bundle Size Optimization

Functype is optimized for tree-shaking and offers multiple import strategies to minimize bundle size:

// Selective module imports (recommended for production)
import { Option } from "functype/option"
import { Either } from "functype/either"

// Direct constructor imports (smallest bundle)
import { some, none } from "functype/option"

For detailed optimization strategies, see the Bundle Optimization Guide.

Usage Examples

Option

{@includeCode test/docs/documentation-examples.spec.ts#readme-option-basic}

Either

{@includeCode test/docs/documentation-examples.spec.ts#readme-either-basic}

List

import { List } from "functype"

const numbers = List([1, 2, 3, 4])

// Transform
const doubled = numbers.map((x) => x * 2) // List([2, 4, 6, 8])

// Filter
const evens = numbers.filter((x) => x % 2 === 0) // List([2, 4])

// Reduce
const sum = numbers.foldLeft(0)((acc, x) => acc + x) // 10

// Add/remove elements (immutably)
const withFive = numbers.add(5) // List([1, 2, 3, 4, 5])
const without3 = numbers.remove(3) // List([1, 2, 4])

// Universal container operations
const hasEven = numbers.exists((x) => x % 2 === 0) // true
const firstEven = numbers.find((x) => x % 2 === 0) // Some(2)
const evenCount = numbers.count((x) => x % 2 === 0) // 2

Try

import { Try } from "functype"

// Safely execute code that might throw
const result = Try(() => {
  // Potentially throwing operation
  return JSON.parse('{"name": "John"}')
})

// Handle success/failure
if (result.isSuccess()) {
  console.log("Result:", result.get())
} else {
  console.error("Error:", result.error)
}

// Transform with map (only applies on Success)
const name = result.map((obj) => obj.name)

// Convert to Either
const either = result.toEither()

Lazy

import { Lazy } from "functype"

// Create lazy computations
const expensive = Lazy(() => {
  console.log("Computing...")
  return Math.random() * 1000
})