fp-ts Algebraic Data Types and Type Classes

This skill covers algebraic data types (ADTs) and type classes in fp-ts for robust domain modeling in TypeScript.

Core Concepts

What are Algebraic Data Types?

Algebraic Data Types (ADTs) are composite types formed by combining other types. There are two fundamental kinds:

• Product Types: Combine types with AND (tuples, records) - "A user HAS a name AND an email"

• Sum Types: Combine types with OR (discriminated unions) - "A result IS either success OR failure"

What are Type Classes?

Type classes define behavior that can be implemented for different types. In fp-ts, they're represented as interfaces with instances for specific types:

• Eq: Equality comparison

• Ord: Ordering/comparison

• Semigroup: Combining two values of the same type

• Monoid: Semigroup with an identity element

Product Types

Product types represent values that contain ALL of their component parts simultaneously.

Tuples

Tuples are fixed-length arrays with typed positions.

import { pipe } from 'fp-ts/function' import * as T from 'fp-ts/Tuple'

// Basic tuple type type Point2D = readonly [number, number] type NamedValue = readonly [string, number]

const point: Point2D = [10, 20] const item: NamedValue = ['score', 100]

// Accessing tuple elements const [x, y] = point const [label, value] = item

// Tuple operations from fp-ts const first = T.fst(point) // 10 const second = T.snd(point) // 20

// Map over the first element const doubled = T.mapFst((n: number) => n * 2)(point) // [20, 20]

// Map over the second element const incremented = T.mapSnd((n: number) => n + 1)(point) // [10, 21]

// Bimap: transform both elements const transformed = T.bimap( (n: number) => n.toString(), (n: number) => n * 2 )(point) // ['20', 20]

Records (Object Types)

Records are the most common product type in TypeScript.

// Domain model as a product type interface User { readonly id: string readonly email: string readonly name: string readonly createdAt: Date }

// All fields must be present - this is what makes it a "product" const user: User = { id: '123', email: 'john@example.com', name: 'John Doe', createdAt: new Date() }

// Nested product types interface Order { readonly id: string readonly customer: User readonly items: ReadonlyArray<OrderItem> readonly shipping: ShippingAddress readonly billing: BillingInfo }

interface OrderItem { readonly productId: string readonly quantity: number readonly unitPrice: number }

interface ShippingAddress { readonly street: string readonly city: string readonly postalCode: string readonly country: string }

interface BillingInfo { readonly method: PaymentMethod readonly cardLast4?: string }

When to Use Product Types

Use product types when:

• An entity requires ALL pieces of data to be valid

• The data naturally belongs together

• You're modeling database entities or API payloads

• Components are always present together

// Good: All fields are required for a valid config interface DatabaseConfig { readonly host: string readonly port: number readonly database: string readonly username: string readonly password: string }

// Good: Coordinate always needs both x and y interface Coordinate { readonly x: number readonly y: number }

// Good: Money needs both amount and currency interface Money { readonly amount: number readonly currency: string }

Sum Types (Discriminated Unions)

Sum types represent values that can be ONE OF several variants.

Basic Discriminated Unions

// A payment can be ONE OF these types type PaymentMethod = | { readonly _tag: 'CreditCard'; readonly cardNumber: string; readonly expiry: string } | { readonly _tag: 'PayPal'; readonly email: string } | { readonly _tag: 'BankTransfer'; readonly accountNumber: string; readonly routingNumber: string } | { readonly _tag: 'Crypto'; readonly walletAddress: string; readonly network: string }

// Creating values const creditCard: PaymentMethod = { _tag: 'CreditCard', cardNumber: '4111111111111111', expiry: '12/25' }

const paypal: PaymentMethod = { _tag: 'PayPal', email: 'user@example.com' }

Pattern Matching with fold/match

import { pipe } from 'fp-ts/function'

// Define a fold function for exhaustive pattern matching const foldPaymentMethod = <R>(handlers: { CreditCard: (cardNumber: string, expiry: string) => R PayPal: (email: string) => R BankTransfer: (accountNumber: string, routingNumber: string) => R Crypto: (walletAddress: string, network: string) => R }) => (payment: PaymentMethod): R => { switch (payment._tag) { case 'CreditCard': return handlers.CreditCard(payment.cardNumber, payment.expiry) case 'PayPal': return handlers.PayPal(payment.email) case 'BankTransfer': return handlers.BankTransfer(payment.accountNumber, payment.routingNumber) case 'Crypto': return handlers.Crypto(payment.walletAddress, payment.network) } }

// Usage const getPaymentLabel = foldPaymentMethod({ CreditCard: (num, _) => Card ending in ${num.slice(-4)}, PayPal: (email) => PayPal: ${email}, BankTransfer: (acc, _) => Bank: ${acc.slice(-4)}, Crypto: (wallet, network) => ${network}: ${wallet.slice(0, 8)}... })

const label = getPaymentLabel(creditCard) // "Card ending in 1111"

Smart Constructors for Sum Types

// Define the union type RemoteData<E, A> = | { readonly _tag: 'NotAsked' } | { readonly _tag: 'Loading' } | { readonly _tag: 'Failure'; readonly error: E } | { readonly _tag: 'Success'; readonly data: A }

// Smart constructors const notAsked: RemoteData<never, never> = { _tag: 'NotAsked' } const loading: RemoteData<never, never> = { _tag: 'Loading' } const failure = <E>(error: E): RemoteData<E, never> => ({ _tag: 'Failure', error }) const success = <A>(data: A): RemoteData<never, A> => ({ _tag: 'Success', data })

// Type guards const isNotAsked = <E, A>(rd: RemoteData<E, A>): rd is { _tag: 'NotAsked' } => rd._tag === 'NotAsked' const isLoading = <E, A>(rd: RemoteData<E, A>): rd is { _tag: 'Loading' } => rd._tag === 'Loading' const isFailure = <E, A>(rd: RemoteData<E, A>): rd is { _tag: 'Failure'; error: E } => rd._tag === 'Failure' const isSuccess = <E, A>(rd: RemoteData<E, A>): rd is { _tag: 'Success'; data: A } => rd._tag === 'Success'

// Fold for exhaustive matching const fold = <E, A, R>(handlers: { NotAsked: () => R Loading: () => R Failure: (error: E) => R Success: (data: A) => R }) => (rd: RemoteData<E, A>): R => { switch (rd._tag) { case 'NotAsked': return handlers.NotAsked() case 'Loading': return handlers.Loading() case 'Failure': return handlers.Failure(rd.error) case 'Success': return handlers.Success(rd.data) } }

// Usage in React const UserProfile = ({ data }: { data: RemoteData<Error, User> }) => pipe( data, fold({ NotAsked: () => <button>Load Profile</button>, Loading: () => <Spinner />, Failure: (err) => <ErrorMessage error={err} />, Success: (user) => <ProfileCard user={user} /> }) )

When to Use Sum Types

Use sum types when:

• A value can be in different states

• Different variants have different data shapes

• You need exhaustive handling of all cases

• Modeling state machines or workflows

// Good: Order status is mutually exclusive type OrderStatus = | { readonly _tag: 'Pending' } | { readonly _tag: 'Confirmed'; readonly confirmedAt: Date } | { readonly _tag: 'Shipped'; readonly trackingNumber: string; readonly shippedAt: Date } | { readonly _tag: 'Delivered'; readonly deliveredAt: Date } | { readonly _tag: 'Cancelled'; readonly reason: string; readonly cancelledAt: Date }

// Good: API response states type ApiResponse<T> = | { readonly _tag: 'Idle' } | { readonly _tag: 'Loading' } | { readonly _tag: 'Error'; readonly message: string; readonly code: number } | { readonly _tag: 'Success'; readonly data: T }

// Good: Form field validation state type FieldState<T> = | { readonly _tag: 'Pristine'; readonly value: T } | { readonly _tag: 'Valid'; readonly value: T } | { readonly _tag: 'Invalid'; readonly value: T; readonly errors: ReadonlyArray<string> }

Semigroups

A Semigroup defines how to combine two values of the same type. It must satisfy the associativity law: combine(combine(a, b), c) === combine(a, combine(b, c))

Basic Semigroup Usage

import * as S from 'fp-ts/Semigroup' import * as N from 'fp-ts/number' import * as Str from 'fp-ts/string' import { pipe } from 'fp-ts/function'

// Built-in semigroups const sumResult = S.concatAll(N.SemigroupSum)(0)([1, 2, 3, 4]) // 10 const productResult = S.concatAll(N.SemigroupProduct)(1)([1, 2, 3, 4]) // 24 const stringResult = S.concatAll(Str.Semigroup)('')(['Hello', ' ', 'World']) // 'Hello World'

// Combining two values const sum = N.SemigroupSum.concat(5, 3) // 8 const product = N.SemigroupProduct.concat(5, 3) // 15

Custom Semigroup Instances

import * as S from 'fp-ts/Semigroup' import { pipe } from 'fp-ts/function'

// Semigroup for taking the first value const first = <A>(): S.Semigroup<A> => ({ concat: (x, _) => x })

// Semigroup for taking the last value const last = <A>(): S.Semigroup<A> => ({ concat: (_, y) => y })

// Semigroup for max value const max: S.Semigroup<number> = { concat: (x, y) => Math.max(x, y) }

// Semigroup for min value const min: S.Semigroup<number> = { concat: (x, y) => Math.min(x, y) }

Practical Example: Merging Configs

import * as S from 'fp-ts/Semigroup' import { pipe } from 'fp-ts/function'

interface ServerConfig { readonly host: string readonly port: number readonly timeout: number readonly retries: number readonly features: ReadonlyArray<string> }

// Semigroup that merges configs (later values override) const ServerConfigSemigroup: S.Semigroup<ServerConfig> = S.struct({ host: S.last<string>(), // Last value wins port: S.last<number>(), // Last value wins timeout: S.max(N.Ord), // Take maximum timeout retries: S.max(N.Ord), // Take maximum retries features: { // Concatenate arrays concat: (x, y) => [...new Set([...x, ...y])] } })

// Default config const defaultConfig: ServerConfig = { host: 'localhost', port: 3000, timeout: 5000, retries: 3, features: ['logging'] }

// Environment-specific overrides const prodOverrides: ServerConfig = { host: 'api.example.com', port: 443, timeout: 10000, retries: 5, features: ['monitoring', 'caching'] }

// Merge configs const finalConfig = ServerConfigSemigroup.concat(defaultConfig, prodOverrides) // { // host: 'api.example.com', // port: 443, // timeout: 10000, // retries: 5, // features: ['logging', 'monitoring', 'caching'] // }

// Merge multiple configs const configs = [defaultConfig, devOverrides, envOverrides, cliOverrides] const mergedConfig = S.concatAll(ServerConfigSemigroup)(defaultConfig)(configs)

Semigroup for Optional Values

import * as S from 'fp-ts/Semigroup' import * as O from 'fp-ts/Option'

// Semigroup for Option that prefers Some values const getOptionSemigroup = <A>(S: S.Semigroup<A>): S.Semigroup<O.Option<A>> => O.getMonoid(S)

// Or use the built-in import { getApplySemigroup } from 'fp-ts/Apply' import { Applicative } from 'fp-ts/Option'

const optionStringSemigroup = getApplySemigroup(Applicative)(Str.Semigroup)

// Example: merging optional configs interface PartialConfig { readonly host?: string readonly port?: number }

const mergePartialConfigs = (a: PartialConfig, b: PartialConfig): PartialConfig => ({ host: b.host ?? a.host, port: b.port ?? a.port })

Monoids

A Monoid is a Semigroup with an identity element (empty). The empty element satisfies: concat(empty, a) === a and concat(a, empty) === a

Basic Monoid Usage

import * as M from 'fp-ts/Monoid' import * as N from 'fp-ts/number' import * as Str from 'fp-ts/string' import * as A from 'fp-ts/Array' import { pipe } from 'fp-ts/function'

// Built-in monoids const sum = M.concatAll(N.MonoidSum)([1, 2, 3, 4, 5]) // 15 const product = M.concatAll(N.MonoidProduct)([1, 2, 3, 4, 5]) // 120 const concatenated = M.concatAll(Str.Monoid)(['a', 'b', 'c']) // 'abc'

// Empty values N.MonoidSum.empty // 0 N.MonoidProduct.empty // 1 Str.Monoid.empty // '' A.getMonoid<number>().empty // []

Custom Monoid Instances

import * as M from 'fp-ts/Monoid' import { pipe } from 'fp-ts/function'

// Monoid for boolean AND const MonoidAll: M.Monoid<boolean> = { concat: (x, y) => x && y, empty: true }

// Monoid for boolean OR const MonoidAny: M.Monoid<boolean> = { concat: (x, y) => x || y, empty: false }

// Usage: check if all validations pass const allValid = M.concatAll(MonoidAll)([true, true, false, true]) // false const anyValid = M.concatAll(MonoidAny)([false, false, true, false]) // true

Practical Example: Combining Results

import * as M from 'fp-ts/Monoid' import * as A from 'fp-ts/Array' import { pipe } from 'fp-ts/function'

// Aggregation result type interface AggregationResult { readonly totalCount: number readonly successCount: number readonly errorCount: number readonly errors: ReadonlyArray<string> readonly processingTimeMs: number }

// Monoid for combining aggregation results const AggregationResultMonoid: M.Monoid<AggregationResult> = { concat: (a, b) => ({ totalCount: a.totalCount + b.totalCount, successCount: a.successCount + b.successCount, errorCount: a.errorCount + b.errorCount, errors: [...a.errors, ...b.errors], processingTimeMs: a.processingTimeMs + b.processingTimeMs }), empty: { totalCount: 0, successCount: 0, errorCount: 0, errors: [], processingTimeMs: 0 } }

// Process items and combine results const processItem = (item: Item): AggregationResult => { const start = Date.now() try { doProcessing(item) return { totalCount: 1, successCount: 1, errorCount: 0, errors: [], processingTimeMs: Date.now() - start } } catch (e) { return { totalCount: 1, successCount: 0, errorCount: 1, errors: [e instanceof Error ? e.message : 'Unknown error'], processingTimeMs: Date.now() - start } } }

// Combine all results const processAll = (items: ReadonlyArray<Item>): AggregationResult => pipe( items, A.map(processItem), M.concatAll(AggregationResultMonoid) )

Monoid for Statistics

import * as M from 'fp-ts/Monoid'

interface Statistics { readonly count: number readonly sum: number readonly min: number readonly max: number }

const StatisticsMonoid: M.Monoid<Statistics> = { concat: (a, b) => ({ count: a.count + b.count, sum: a.sum + b.sum, min: Math.min(a.min, b.min), max: Math.max(a.max, b.max) }), empty: { count: 0, sum: 0, min: Infinity, max: -Infinity } }

// Create statistics from a single value const fromNumber = (n: number): Statistics => ({ count: 1, sum: n, min: n, max: n })

// Calculate statistics for an array const calculateStats = (numbers: ReadonlyArray<number>): Statistics => pipe( numbers, A.map(fromNumber), M.concatAll(StatisticsMonoid) )

const stats = calculateStats([5, 2, 8, 1, 9]) // { count: 5, sum: 25, min: 1, max: 9 }

// Can also compute average const average = (s: Statistics): number => s.count === 0 ? 0 : s.sum / s.count

Eq Type Class

Eq defines equality comparison for types.

Basic Eq Usage

import * as Eq from 'fp-ts/Eq' import * as N from 'fp-ts/number' import * as Str from 'fp-ts/string' import * as A from 'fp-ts/Array' import { pipe } from 'fp-ts/function'

// Built-in Eq instances N.Eq.equals(1, 1) // true Str.Eq.equals('hello', 'hello') // true

// Eq for arrays const numberArrayEq = A.getEq(N.Eq) numberArrayEq.equals([1, 2, 3], [1, 2, 3]) // true numberArrayEq.equals([1, 2, 3], [1, 2]) // false

Custom Eq Instances

import * as Eq from 'fp-ts/Eq' import { pipe } from 'fp-ts/function'

interface User { readonly id: string readonly email: string readonly name: string }

// Eq by ID only const UserEqById: Eq.Eq<User> = Eq.contramap((user: User) => user.id)(Str.Eq)

// Eq by all fields const UserEqFull: Eq.Eq<User> = Eq.struct({ id: Str.Eq, email: Str.Eq, name: Str.Eq })

// Usage const user1: User = { id: '1', email: 'a@b.com', name: 'Alice' } const user2: User = { id: '1', email: 'different@b.com', name: 'Alice Updated' }

UserEqById.equals(user1, user2) // true (same ID) UserEqFull.equals(user1, user2) // false (different email)

Practical Example: Deduplication

import * as Eq from 'fp-ts/Eq' import * as A from 'fp-ts/Array' import { pipe } from 'fp-ts/function'

interface Product { readonly sku: string readonly name: string readonly price: number }

const ProductEqBySku: Eq.Eq<Product> = pipe( Str.Eq, Eq.contramap((p: Product) => p.sku) )

// Remove duplicates by SKU const uniqueProducts = A.uniq(ProductEqBySku)

const products: Product[] = [ { sku: 'A001', name: 'Widget', price: 10 }, { sku: 'A002', name: 'Gadget', price: 20 }, { sku: 'A001', name: 'Widget Updated', price: 15 }, // Duplicate SKU ]

const unique = uniqueProducts(products) // [{ sku: 'A001', name: 'Widget', price: 10 }, { sku: 'A002', name: 'Gadget', price: 20 }]

// Check if array contains element const hasProduct = A.elem(ProductEqBySku) hasProduct({ sku: 'A001', name: '', price: 0 })(products) // true

Case-Insensitive String Eq

import * as Eq from 'fp-ts/Eq'

const EqCaseInsensitive: Eq.Eq<string> = { equals: (x, y) => x.toLowerCase() === y.toLowerCase() }

EqCaseInsensitive.equals('Hello', 'hello') // true EqCaseInsensitive.equals('WORLD', 'world') // true

// Use with user emails const UserEqByEmail: Eq.Eq<User> = pipe( EqCaseInsensitive, Eq.contramap((u: User) => u.email) )

Ord Type Class

Ord extends Eq with ordering/comparison capabilities.

Basic Ord Usage

import * as Ord from 'fp-ts/Ord' import * as N from 'fp-ts/number' import * as Str from 'fp-ts/string' import * as A from 'fp-ts/Array' import { pipe } from 'fp-ts/function'

// Built-in Ord instances Ord.lt(N.Ord)(1, 2) // true (1 < 2) Ord.gt(N.Ord)(5, 3) // true (5 > 3) Ord.leq(N.Ord)(2, 2) // true (2 <= 2) Ord.geq(N.Ord)(3, 2) // true (3 >= 2)

// Sorting const numbers = [3, 1, 4, 1, 5, 9, 2, 6] const sorted = A.sort(N.Ord)(numbers) // [1, 1, 2, 3, 4, 5, 6, 9]

// Reverse order const descending = A.sort(Ord.reverse(N.Ord))(numbers) // [9, 6, 5, 4, 3, 2, 1, 1]

// Min and max const minimum = Ord.min(N.Ord)(5, 3) // 3 const maximum = Ord.max(N.Ord)(5, 3) // 5

Custom Ord Instances

import * as Ord from 'fp-ts/Ord' import * as A from 'fp-ts/Array' import { pipe } from 'fp-ts/function'

interface Product { readonly name: string readonly price: number readonly rating: number readonly createdAt: Date }

// Ord by price const OrdByPrice: Ord.Ord<Product> = pipe( N.Ord, Ord.contramap((p: Product) => p.price) )

// Ord by rating (descending - highest first) const OrdByRatingDesc: Ord.Ord<Product> = pipe( N.Ord, Ord.contramap((p: Product) => p.rating), Ord.reverse )

// Ord by date (newest first) const OrdByDateDesc: Ord.Ord<Product> = pipe( N.Ord, Ord.contramap((p: Product) => p.createdAt.getTime()), Ord.reverse )

// Sort products by price const sortByPrice = A.sort(OrdByPrice)

// Sort by rating (highest first) const sortByRating = A.sort(OrdByRatingDesc)

Compound Ordering

import * as Ord from 'fp-ts/Ord' import * as A from 'fp-ts/Array' import { pipe } from 'fp-ts/function' import * as M from 'fp-ts/Monoid'

interface Employee { readonly department: string readonly name: string readonly salary: number readonly startDate: Date }

// Primary: department (alphabetical) // Secondary: salary (descending) // Tertiary: name (alphabetical)

const OrdByDepartment: Ord.Ord<Employee> = pipe( Str.Ord, Ord.contramap((e: Employee) => e.department) )

const OrdBySalaryDesc: Ord.Ord<Employee> = pipe( N.Ord, Ord.contramap((e: Employee) => e.salary), Ord.reverse )

const OrdByName: Ord.Ord<Employee> = pipe( Str.Ord, Ord.contramap((e: Employee) => e.name) )

// Combine orderings with monoid const EmployeeOrd: Ord.Ord<Employee> = M.concatAll(Ord.getMonoid<Employee>())([ OrdByDepartment, OrdBySalaryDesc, OrdByName ])

const employees: Employee[] = [ { department: 'Engineering', name: 'Alice', salary: 100000, startDate: new Date() }, { department: 'Engineering', name: 'Bob', salary: 120000, startDate: new Date() }, { department: 'Sales', name: 'Charlie', salary: 90000, startDate: new Date() }, { department: 'Engineering', name: 'Diana', salary: 120000, startDate: new Date() }, ]

const sorted = A.sort(EmployeeOrd)(employees) // Engineering: Bob (120k), Diana (120k - alphabetical), Alice (100k) // Sales: Charlie (90k)

Practical Example: Sorting and Filtering

import * as Ord from 'fp-ts/Ord' import * as A from 'fp-ts/Array' import * as O from 'fp-ts/Option' import { pipe } from 'fp-ts/function'

interface Task { readonly id: string readonly title: string readonly priority: 'low' | 'medium' | 'high' | 'critical' readonly dueDate: O.Option<Date> readonly completed: boolean }

// Priority ordering (critical > high > medium > low) const priorityOrder: Record<Task['priority'], number> = { critical: 4, high: 3, medium: 2, low: 1 }

const OrdByPriority: Ord.Ord<Task> = pipe( N.Ord, Ord.contramap((t: Task) => priorityOrder[t.priority]), Ord.reverse // Highest priority first )

// Due date ordering (soonest first, no date last) const OrdByDueDate: Ord.Ord<Task> = pipe( O.getOrd(N.Ord), Ord.contramap((t: Task) => pipe(t.dueDate, O.map(d => d.getTime()))) )

// Combined: incomplete first, then by priority, then by due date const TaskOrd: Ord.Ord<Task> = M.concatAll(Ord.getMonoid<Task>())([ pipe( Ord.trivial, // Boolean doesn't have natural ordering Ord.contramap((t: Task) => t.completed ? 1 : 0) // Incomplete (0) before complete (1) ), OrdByPriority, OrdByDueDate ])

// Get top N tasks const getTopTasks = (n: number) => (tasks: Task[]): Task[] => pipe( tasks, A.filter(t => !t.completed), A.sort(TaskOrd), A.takeLeft(n) )

Using fp-ts Type Class Instances

Getting Instances from Modules

import * as O from 'fp-ts/Option' import * as E from 'fp-ts/Either' import * as A from 'fp-ts/Array' import * as R from 'fp-ts/Record' import * as NEA from 'fp-ts/NonEmptyArray'

// Each module exports type class instances

// Option instances O.Eq // Eq<Option<A>> given Eq<A> O.Ord // Ord<Option<A>> given Ord<A> O.Semigroup // Semigroup using Apply O.Monoid // Monoid with None as empty

// Array instances A.getEq // (Eq<A>) => Eq<Array<A>> A.getOrd // (Ord<A>) => Ord<Array<A>> A.getMonoid // <A>() => Monoid<Array<A>> A.getSemigroup // <A>() => Semigroup<NonEmptyArray<A>>

// Record instances R.getEq // Eq for records R.getMonoid // Monoid for records

Combining Type Classes

import * as Eq from 'fp-ts/Eq' import * as Ord from 'fp-ts/Ord' import * as S from 'fp-ts/Semigroup' import * as M from 'fp-ts/Monoid' import * as O from 'fp-ts/Option' import { pipe } from 'fp-ts/function'

interface CartItem { readonly productId: string readonly quantity: number readonly price: number }

// Eq for cart items (by product ID) const CartItemEq: Eq.Eq<CartItem> = pipe( Str.Eq, Eq.contramap((item: CartItem) => item.productId) )

// Semigroup that merges quantities for same product const CartItemSemigroup: S.Semigroup<CartItem> = { concat: (a, b) => ({ productId: a.productId, quantity: a.quantity + b.quantity, price: a.price // Keep original price }) }

// Merge cart items, combining quantities for duplicates const mergeCartItems = (items: CartItem[]): CartItem[] => { const grouped = items.reduce((acc, item) => { const existing = acc.get(item.productId) if (existing) { acc.set(item.productId, CartItemSemigroup.concat(existing, item)) } else { acc.set(item.productId, item) } return acc }, new Map<string, CartItem>())

return Array.from(grouped.values()) }

// Calculate cart total using Monoid interface CartTotal { readonly itemCount: number readonly subtotal: number }

const CartTotalMonoid: M.Monoid<CartTotal> = { concat: (a, b) => ({ itemCount: a.itemCount + b.itemCount, subtotal: a.subtotal + b.subtotal }), empty: { itemCount: 0, subtotal: 0 } }

const calculateTotal = (items: CartItem[]): CartTotal => pipe( items, A.map(item => ({ itemCount: item.quantity, subtotal: item.quantity * item.price })), M.concatAll(CartTotalMonoid) )

Building Domain-Specific Type Classes

import * as Eq from 'fp-ts/Eq' import * as Ord from 'fp-ts/Ord' import * as S from 'fp-ts/Semigroup' import * as M from 'fp-ts/Monoid' import { pipe } from 'fp-ts/function'

// Domain: Money handling

interface Money { readonly amount: number readonly currency: string }

// Only allow operations on same currency const MoneyEq: Eq.Eq<Money> = Eq.struct({ amount: N.Eq, currency: Str.Eq })

// Compare money amounts (same currency only) const MoneyOrd: Ord.Ord<Money> = pipe( N.Ord, Ord.contramap((m: Money) => m.amount) )

// Add money (throws if different currencies) const MoneySemigroup = (currency: string): S.Semigroup<Money> => ({ concat: (a, b) => { if (a.currency !== currency || b.currency !== currency) { throw new Error('Cannot combine different currencies') } return { amount: a.amount + b.amount, currency } } })

// Safe money addition using Option const addMoney = (a: Money, b: Money): O.Option<Money> => a.currency === b.currency ? O.some({ amount: a.amount + b.amount, currency: a.currency }) : O.none

// Monoid for specific currency const MoneyMonoid = (currency: string): M.Monoid<Money> => ({ ...MoneySemigroup(currency), empty: { amount: 0, currency } })

// Sum all USD amounts const totalUSD = (amounts: Money[]): Money => pipe( amounts, A.filter(m => m.currency === 'USD'), M.concatAll(MoneyMonoid('USD')) )

Practical Domain Modeling Examples

Example 1: E-commerce Order System

import * as E from 'fp-ts/Either' import * as O from 'fp-ts/Option' import * as A from 'fp-ts/Array' import * as M from 'fp-ts/Monoid' import { pipe } from 'fp-ts/function'

// Sum type for order status type OrderStatus = | { readonly _tag: 'Draft' } | { readonly _tag: 'Pending'; readonly submittedAt: Date } | { readonly _tag: 'Paid'; readonly paidAt: Date; readonly transactionId: string } | { readonly _tag: 'Shipped'; readonly shippedAt: Date; readonly trackingNumber: string } | { readonly _tag: 'Delivered'; readonly deliveredAt: Date } | { readonly _tag: 'Cancelled'; readonly cancelledAt: Date; readonly reason: string } | { readonly _tag: 'Refunded'; readonly refundedAt: Date; readonly refundAmount: number }

// Smart constructors const OrderStatus = { draft: (): OrderStatus => ({ _tag: 'Draft' }), pending: (submittedAt: Date): OrderStatus => ({ _tag: 'Pending', submittedAt }), paid: (paidAt: Date, transactionId: string): OrderStatus => ({ _tag: 'Paid', paidAt, transactionId }), shipped: (shippedAt: Date, trackingNumber: string): OrderStatus => ({ _tag: 'Shipped', shippedAt, trackingNumber }), delivered: (deliveredAt: Date): OrderStatus => ({ _tag: 'Delivered', deliveredAt }), cancelled: (cancelledAt: Date, reason: string): OrderStatus => ({ _tag: 'Cancelled', cancelledAt, reason }), refunded: (refundedAt: Date, refundAmount: number): OrderStatus => ({ _tag: 'Refunded', refundedAt, refundAmount }) }

// Pattern matching const foldOrderStatus = <R>(handlers: { Draft: () => R Pending: (submittedAt: Date) => R Paid: (paidAt: Date, transactionId: string) => R Shipped: (shippedAt: Date, trackingNumber: string) => R Delivered: (deliveredAt: Date) => R Cancelled: (cancelledAt: Date, reason: string) => R Refunded: (refundedAt: Date, refundAmount: number) => R }) => (status: OrderStatus): R => { switch (status._tag) { case 'Draft': return handlers.Draft() case 'Pending': return handlers.Pending(status.submittedAt) case 'Paid': return handlers.Paid(status.paidAt, status.transactionId) case 'Shipped': return handlers.Shipped(status.shippedAt, status.trackingNumber) case 'Delivered': return handlers.Delivered(status.deliveredAt) case 'Cancelled': return handlers.Cancelled(status.cancelledAt, status.reason) case 'Refunded': return handlers.Refunded(status.refundedAt, status.refundAmount) } }

// Product type for order interface Order { readonly id: string readonly customerId: string readonly items: ReadonlyArray<OrderItem> readonly status: OrderStatus readonly shippingAddress: Address readonly billingAddress: Address readonly createdAt: Date readonly updatedAt: Date }

interface OrderItem { readonly productId: string readonly productName: string readonly quantity: number readonly unitPrice: number readonly discount: number }

interface Address { readonly line1: string readonly line2: O.Option<string> readonly city: string readonly state: string readonly postalCode: string readonly country: string }

// Monoid for order totals interface OrderTotals { readonly subtotal: number readonly discount: number readonly tax: number readonly shipping: number readonly total: number }

const OrderTotalsMonoid: M.Monoid<OrderTotals> = M.struct({ subtotal: N.MonoidSum, discount: N.MonoidSum, tax: N.MonoidSum, shipping: N.MonoidSum, total: N.MonoidSum })

const calculateItemTotal = (item: OrderItem): OrderTotals => { const subtotal = item.quantity * item.unitPrice const discount = item.discount return { subtotal, discount, tax: 0, // Calculated separately shipping: 0, total: subtotal - discount } }

const calculateOrderTotals = (order: Order, taxRate: number, shippingCost: number): OrderTotals => { const itemTotals = pipe( order.items, A.map(calculateItemTotal), M.concatAll(OrderTotalsMonoid) )

const tax = (itemTotals.subtotal - itemTotals.discount) * taxRate const total = itemTotals.subtotal - itemTotals.discount + tax + shippingCost

return { ...itemTotals, tax, shipping: shippingCost, total } }

// State transitions with validation const canTransition = (from: OrderStatus, to: OrderStatus['_tag']): boolean => foldOrderStatus({ Draft: () => to === 'Pending' || to === 'Cancelled', Pending: () => to === 'Paid' || to === 'Cancelled', Paid: () => to === 'Shipped' || to === 'Refunded', Shipped: () => to === 'Delivered' || to === 'Refunded', Delivered: () => to === 'Refunded', Cancelled: () => false, Refunded: () => false })(from)

Example 2: Configuration Management

import * as S from 'fp-ts/Semigroup' import * as O from 'fp-ts/Option' import * as A from 'fp-ts/Array' import { pipe } from 'fp-ts/function'

// Sum type for log level type LogLevel = 'debug' | 'info' | 'warn' | 'error'

const LogLevelOrd: Ord.Ord<LogLevel> = pipe( N.Ord, Ord.contramap((level: LogLevel) => { const order: Record<LogLevel, number> = { debug: 0, info: 1, warn: 2, error: 3 } return order[level] }) )

// Product type for app config interface AppConfig { readonly server: ServerConfig readonly database: DatabaseConfig readonly logging: LoggingConfig readonly features: FeatureFlags }

interface ServerConfig { readonly host: string readonly port: number readonly timeout: number readonly maxConnections: number }

interface DatabaseConfig { readonly host: string readonly port: number readonly database: string readonly poolSize: number readonly ssl: boolean }

interface LoggingConfig { readonly level: LogLevel readonly format: 'json' | 'text' readonly outputs: ReadonlyArray<string> }

interface FeatureFlags { readonly [key: string]: boolean }

// Semigroups for merging configs (later values override) const ServerConfigSemigroup: S.Semigroup<ServerConfig> = S.struct({ host: S.last<string>(), port: S.last<number>(), timeout: S.max(N.Ord), // Take higher timeout maxConnections: S.max(N.Ord) // Take higher max connections })

const DatabaseConfigSemigroup: S.Semigroup<DatabaseConfig> = S.struct({ host: S.last<string>(), port: S.last<number>(), database: S.last<string>(), poolSize: S.max(N.Ord), ssl: { concat: (a, b) => a || b } // SSL if either enables it })

const LoggingConfigSemigroup: S.Semigroup<LoggingConfig> = { concat: (a, b) => ({ level: Ord.min(LogLevelOrd)(a.level, b.level), // Most verbose level format: b.format, // Last format wins outputs: [...new Set([...a.outputs, ...b.outputs])] // Union of outputs }) }

const FeatureFlagsSemigroup: S.Semigroup<FeatureFlags> = { concat: (a, b) => ({ ...a, ...b }) // Later flags override }

const AppConfigSemigroup: S.Semigroup<AppConfig> = S.struct({ server: ServerConfigSemigroup, database: DatabaseConfigSemigroup, logging: LoggingConfigSemigroup, features: FeatureFlagsSemigroup })

// Load and merge configs from multiple sources const loadConfig = (sources: AppConfig[]): AppConfig => pipe( sources, A.reduce(defaultConfig, AppConfigSemigroup.concat) )

// Example usage const defaultConfig: AppConfig = { server: { host: 'localhost', port: 3000, timeout: 5000, maxConnections: 100 }, database: { host: 'localhost', port: 5432, database: 'app', poolSize: 10, ssl: false }, logging: { level: 'info', format: 'text', outputs: ['console'] }, features: {} }

const envConfig: AppConfig = { server: { host: 'api.prod.com', port: 443, timeout: 10000, maxConnections: 1000 }, database: { host: 'db.prod.com', port: 5432, database: 'app_prod', poolSize: 50, ssl: true }, logging: { level: 'warn', format: 'json', outputs: ['console', 'file', 'cloudwatch'] }, features: { newCheckout: true, betaFeature: false } }

const finalConfig = loadConfig([defaultConfig, envConfig])

Best Practices

1. Use Discriminant Property Consistently

// Good: consistent _tag for all variants type Result<E, A> = | { readonly _tag: 'Failure'; readonly error: E } | { readonly _tag: 'Success'; readonly value: A }

// Bad: inconsistent discriminant type BadResult<E, A> = | { readonly type: 'error'; readonly error: E } | { readonly kind: 'success'; readonly value: A }

2. Make Illegal States Unrepresentable

// Bad: allows invalid combinations interface BadOrder { readonly status: 'shipped' | 'pending' readonly trackingNumber: string | null // Only valid for shipped }

// Good: sum type ensures valid combinations type GoodOrder = | { readonly _tag: 'Pending' } | { readonly _tag: 'Shipped'; readonly trackingNumber: string }

3. Use Smart Constructors

// Expose constructors, not raw objects const Order = { pending: (): Order => ({ _tag: 'Pending' }), shipped: (trackingNumber: string): Order => ({ _tag: 'Shipped', trackingNumber }) }

// Don't export the type definition directly for construction // Export only through smart constructors

4. Prefer Structural Type Classes

import * as Eq from 'fp-ts/Eq' import * as S from 'fp-ts/Semigroup'

// Good: use struct to build from smaller pieces const UserEq: Eq.Eq<User> = Eq.struct({ id: Str.Eq, email: Str.Eq, name: Str.Eq })

// Good: compose type class instances const ConfigSemigroup: S.Semigroup<Config> = S.struct({ server: ServerConfigSemigroup, database: DatabaseConfigSemigroup })

5. Keep Fold/Match Exhaustive

// TypeScript will error if you miss a case const handleStatus = (status: OrderStatus): string => pipe( status, foldOrderStatus({ Draft: () => 'Draft', Pending: () => 'Pending', Paid: () => 'Paid', Shipped: () => 'Shipped', Delivered: () => 'Delivered', Cancelled: () => 'Cancelled', Refunded: () => 'Refunded' // Missing a case would cause compile error }) )

Anti-Patterns to Avoid

Don't Use Enums for Sum Types

// Bad: enums don't carry associated data enum OrderStatus { Pending, Shipped, Delivered } // Where does tracking number go for Shipped?

// Good: discriminated unions carry data type OrderStatus = | { readonly _tag: 'Pending' } | { readonly _tag: 'Shipped'; readonly trackingNumber: string } | { readonly _tag: 'Delivered'; readonly deliveredAt: Date }

Don't Mix Type Classes Incorrectly

// Bad: using Ord when you only need Eq const findUser = (users: User[], target: User) => users.find(u => Ord.equals(UserOrd)(u, target)) // Ord.equals doesn't exist

// Good: use the right type class const findUser = (users: User[], target: User) => users.find(u => UserEq.equals(u, target))

Don't Forget Identity Laws for Monoids

// Bad: this isn't a valid Monoid const BadMonoid: M.Monoid<number> = { concat: (a, b) => a + b + 1, // Adding 1 breaks identity law empty: 0 } // concat(0, 5) = 6, not 5!

// Good: respects identity laws const GoodMonoid: M.Monoid<number> = { concat: (a, b) => a + b, empty: 0 } // concat(0, 5) = 5 ✓