aivi.option

Utilities for working with Option A — a value that may or may not be present. All functions are pure and can be freely composed with pipes.

use aivi.option (
    isSome
    isNone
    getOrElse
    fold
    mapOr
    isSomeAnd
    orElse
    flatMap
    flatten
    toList
    toResult
    map
    filter
    zip
    fromBool
)

At a glance

Function	Type	Use it for
isSome	Option A -> Bool	Check whether a value is present
isNone	Option A -> Bool	Check whether a value is missing
getOrElse	A -> Option A -> A	Unwrap with a fallback value
fold	B -> (A -> B) -> Option A -> B	Collapse an option to one output type
mapOr	B -> (A -> B) -> Option A -> B	Transform when present, fallback when absent
isSomeAnd	(A -> Bool) -> Option A -> Bool	Run a predicate only on Some
orElse	Option A -> Option A -> Option A	Fall back to another option
flatMap	(A -> Option B) -> Option A -> Option B	Chain Option-returning steps
flatten	Option (Option A) -> Option A	Remove one layer of nesting
toList	Option A -> List A	Turn Some into a one-item list
toResult	E -> Option A -> Result E A	Turn absence into an explicit error
map	(A -> B) -> Option A -> Option B	Transform the payload inside Some
filter	(A -> Bool) -> Option A -> Option A	Keep a Some only if it matches
zip	Option A -> Option B -> Option (A, B)	Combine two options when both are present
fromBool	A -> Bool -> Option A	Gate a value behind a boolean condition

---

isSome

Returns True if the option holds a value.

Type: opt:(Option A) -> Bool

use aivi.option (isSome)

type Option Int -> Bool
func hasValue = opt =>
    isSome opt

---

isNone

Returns True if the option is empty.

Type: opt:(Option A) -> Bool

use aivi.option (isNone)

type Option Text -> Bool
func isMissing = opt =>
    isNone opt

---

getOrElse

Extracts the value from Some, or returns the fallback if None.

Type: fallback:A -> opt:(Option A) -> A

use aivi.option (getOrElse)

type Option Text -> Text
func displayName = opt =>
    getOrElse "Anonymous" opt

---

fold

Chooses between a fallback value and a Some handler.

Type: fallback:B -> onSome:(A -> B) -> opt:(Option A) -> B

use aivi.option (fold)

type Text -> Text
func excited = name =>
    append name "!"

value label : Text = fold "guest" excited (Some "Ada")

---

mapOr

Maps a Some value or returns a fallback directly when the option is None.

Type: fallback:B -> transform:(A -> B) -> opt:(Option A) -> B

use aivi.option (mapOr)

type Int -> Int
func double = n =>
    n * 2

value total : Int = mapOr 0 double (Some 21)

---

isSomeAnd

Returns True only when the option is Some and the payload satisfies the predicate.

Type: predicate:(A -> Bool) -> opt:(Option A) -> Bool

use aivi.option (isSomeAnd)

type Int -> Bool
func isSmall = n =>
    n < 10

value ok : Bool = isSomeAnd isSmall (Some 3)
value missing : Bool = isSomeAnd isSmall None

---

orElse

Returns the option unchanged if it is Some, otherwise returns the fallback option.

Type: fallback:(Option A) -> opt:(Option A) -> Option A

use aivi.option (orElse)

type Option Text -> (Option Text) -> (Option Text)
func firstAvailable = primary secondary => primary
  |> orElse secondary

---

flatMap

Chains an Option-returning function over a Some value. Returns None when the input is None or when the function returns None.

Type: next:(A -> Option B) -> opt:(Option A) -> Option B

use aivi.option (flatMap)

type Int -> (Option Int)
func parsePositive = n => n > 0
 T|> Some n
 F|> None

type Option Int -> (Option Int)
func parseAndFilter = opt => opt
  |> flatMap parsePositive

---

flatten

Removes one layer of nesting from an Option (Option A).

Type: opt:(Option (Option A)) -> Option A

use aivi.option (flatten)

type Option (Option Int) -> (Option Int)
func unwrapNested = opt =>
    flatten opt

---

toList

Converts Some value to a one-element list, or None to an empty list.

Type: opt:(Option A) -> List A

use aivi.option (toList)

type Option Int -> (List Int)
func optionItems = opt =>
    toList opt

---

toResult

Converts an Option to a Result. Some value becomes Ok value; None becomes Err error.

Type: error:E -> opt:(Option A) -> Result E A

use aivi.option (toResult)

type Option Text -> (Result Text Text)
func requireName = opt =>
    toResult "Name is required" opt

---

map

Transforms the value inside Some using a function, leaving None untouched.

Type: transform:(A -> B) -> opt:(Option A) -> Option B

use aivi.option (map)

type Int -> Int
func double = n =>
    n * 2

type Option Int -> (Option Int)
func doubleOpt = opt => opt
  |> map double

---

filter

Keeps the Some value only if it satisfies the predicate; otherwise returns None.

Type: predicate:(A -> Bool) -> opt:(Option A) -> Option A

use aivi.option (filter)

type Int -> Bool
func isPositive = n =>
    n > 0

type Option Int -> (Option Int)
func keepPositive = opt => opt
  |> filter isPositive

---

zip

Pairs two options together. Produces Some (a, b) only when both inputs are Some.

Type: left:(Option A) -> right:(Option B) -> Option (A, B)

use aivi.option (zip)

type Option Int -> (Option Text) -> (Option (Int, Text))
func pairIfBoth = count label =>
    zip count label

---

fromBool

Wraps item in Some when b is True, or returns None when b is False.

Type: item:A -> b:Bool -> Option A

use aivi.option (fromBool)

type Bool -> Text -> (Option Text)
func whenEnabled = enabled label =>
    fromBool label enabled