pratica

The Maybe monad is used to handle nullable or unreliable data safely, preventing runtime errors caused by null or undefined. A Maybe can be one of two types:

1. Just: Contains the available data.
2. Nothing: Represents missing data.

Most operations on a Maybe will "short-circuit": if the type is Nothing, subsequent transformations like .map() or .chain() are skipped until you handle the empty state using .cata().

import { nullable, Just, Nothing } from "pratica"

const person = { name: "Jason", age: 4 }

// Successful chain
nullable(person)
  .map((p) => p.age)
  .cata({
    Just: (age) => console.log(age), // 9
    Nothing: () => console.log(`This won't run`),
  })

// Short-circuited chain
nullable(null)
  .map((p) => p.age) // Skipped
  .cata({
    Just: (age) => console.log(age),
    Nothing: () => console.log("Missing data"), // Runs
  })

The Result monad is used for handling conditional logic and error states, serving as a functional alternative to if/else or try/catch blocks. A Result is either:

1. Ok: Contains the successful value.
2. Err: Contains error information (e.g., a message or error object).

Methods like .chain() will stop execution and immediately trigger the Err handler if any step in the chain returns an Err.

import { Ok, Err } from "pratica"

const isPerson = (p) => (p.name && p.age ? Ok(p) : Err("Not a person"))
const isOlderThan2 = (p) => (p.age > 2 ? Ok(p) : Err("Not older than 2"))

Ok({ name: "Jason", age: 4 })
  .chain(isPerson)
  .chain(isOlderThan2)
  .cata({
    Ok: (p) => console.log("Success"),
    Err: (msg) => console.log(msg), // If any step fails, the first Err is passed here
  })

You can install Pratica using your preferred package manager. It is designed for functional programming with a focus on simplicity and algebraic data types.

bun i pratica
# or
yarn add pratica
# or
npm i pratica

These utilities provide safe access to array boundaries, returning a Maybe to handle empty arrays:

• head(array): Returns Just(firstElement) or Nothing if empty.
• last(array): Returns Just(lastElement) or Nothing if empty.
• tail(array): Returns Just(remainingElements) (everything except the first) or Nothing if empty.

import { head, last, tail } from "pratica"

head([5, 1, 2]) // Just(5)
head([])        // Nothing

last([5, 1, 2]) // Just(2)

tail([5, 1, 2]) // Just([1, 2])

Utilities for searching and aggregating monads:

• tryFind(predicate)(array): Returns a Maybe containing the first item that satisfies the predicate.
• collectResult(array): Takes an array of Result objects. Returns Ok(values) if all are Ok, otherwise returns the first Err encountered.
• collectMaybe(array): Takes an array of Maybe objects. Returns Just(values) if all are Just, otherwise returns Nothing.

import { tryFind, collectResult, collectMaybe, Ok, Err, Just, Nothing } from "pratica"

// tryFind
tryFind((u) => u.id === "123")([{ id: "123" }]) // Just({ id: "123" })

// collectResult
collectResult([Ok(1), Ok(2)]) // Ok([1, 2])
collectResult([Ok(1), Err("fail")]) // Err("fail")

// collectMaybe
collectMaybe([Just(1), Just(2)]) // Just([1, 2])
collectMaybe([Just(1), Nothing]) // Nothing

The parseDate utility safely attempts to parse a date string. It returns a Maybe monad:

• Just(Date): If the string is a valid date.
• Nothing: If the string is invalid or null.

Because it returns a Maybe, you can immediately chain it with .alt(), .map(), or .chain().

import { parseDate } from "pratica"

parseDate("2019-02-13T21:04:10.984Z")
  .cata({
    Just: (date) => console.log(date.toISOString()),
    Nothing: () => console.log("Invalid date"),
  })

The get utility allows you to safely retrieve a value from a deeply nested object using a path array. It returns a Maybe.

If any part of the path is missing or invalid, it returns Nothing instead of throwing a TypeError.

import { get } from "pratica"

const data = { children: [{ name: "bob" }, { children: [{ name: "lera" }] }] }

get(["children", 1, "children", 0, "name"])(data).cata({
  Just: (name) => console.log(name), // "lera"
  Nothing: () => console.log("Not found"),
})

You can convert a Maybe into a Result using .toResult().

• A Just(value) becomes Ok(value).
• A Nothing becomes Err() (with no value passed).

When using .cata() on a Result, you must provide Ok and Err handlers instead of Just and Nothing.

import { Just, Nothing } from "pratica"

Just(8)
  .toResult()
  .cata({
    Ok: (n) => console.log(n), // 8
    Err: () => console.log(`No value`),
  })