aivi.nonEmpty

Types and utilities for non-empty lists — collections that are guaranteed to have at least one element. This guarantee is enforced at the type level, making head and last always safe without returning Option.

use aivi.nonEmpty (
    NonEmptyList
    singleton
    cons
    head
    last
    length
    toList
    mapNel
    fromList
    appendNel
    fromHeadTail
    init
)

At a glance

Export	Type	Use it for
NonEmptyList A	MkNEL A (List A)	The non-empty list type itself
singleton	A -> NonEmptyList A	Create a one-item non-empty list
cons	A -> NonEmptyList A -> NonEmptyList A	Add an item at the front
head	NonEmptyList A -> A	Read the first item safely
last	NonEmptyList A -> A	Read the final item safely
length	NonEmptyList A -> Int	Count items
toList	NonEmptyList A -> List A	Drop the non-empty guarantee and get a regular list
mapNel	(A -> B) -> NonEmptyList A -> NonEmptyList B	Transform every item while preserving non-emptiness
fromList	List A -> Option (NonEmptyList A)	Upgrade a regular list when it is not empty
fromHeadTail	A -> List A -> NonEmptyList A	Build a non-empty list from a required head and a list tail
init	NonEmptyList A -> List A	Return every item except the last
appendNel	NonEmptyList A -> NonEmptyList A -> NonEmptyList A	Concatenate two non-empty lists

The detailed sections below focus on the most commonly reached-for constructors and transforms; the table above also lists the extra public helpers that are useful in real code, such as fromHeadTail and init.

---

NonEmptyList

The primary non-empty list type used throughout the standard library, including as the error carrier in aivi.validation.

type NonEmptyList A =
  MkNEL A (List A)

Construct values using singleton, cons, or fromList.

---

singleton

Creates a NonEmptyList with exactly one element.

Type: item:A -> NonEmptyList A

use aivi.nonEmpty (
    NonEmptyList
    singleton
)

type Text -> (NonEmptyList Text)
func wrapOne = label =>
    singleton label

---

cons

Prepends an element to a NonEmptyList.

Type: item:A -> nel:(NonEmptyList A) -> NonEmptyList A

use aivi.nonEmpty (
    NonEmptyList
    singleton
    cons
)

type Int -> Int -> (NonEmptyList Int)
func buildList = first second =>
    cons first (singleton second)

---

head

Returns the first element of a NonEmptyList. Always safe — no Option required.

Type: nel:(NonEmptyList A) -> A

use aivi.nonEmpty (
    NonEmptyList
    head
    singleton
)

type NonEmptyList Int -> Int
func firstOf = nel =>
    head nel

---

last

Returns the last element of a NonEmptyList. Always safe — no Option required.

Type: nel:(NonEmptyList A) -> A

use aivi.nonEmpty (
    NonEmptyList
    last
    singleton
)

type NonEmptyList Int -> Int
func finalItem = nel =>
    last nel

---

length

Returns the number of elements in the list.

Type: nel:(NonEmptyList A) -> Int

use aivi.nonEmpty (
    NonEmptyList
    length
    singleton
    cons
)

type NonEmptyList Int -> Int
func countItems = nel =>
    length nel

---

toList

Converts a NonEmptyList to a regular List.

Type: nel:(NonEmptyList A) -> List A

use aivi.nonEmpty (
    NonEmptyList
    toList
    singleton
)

type NonEmptyList Int -> (List Int)
func asRegularList = nel =>
    toList nel

---

mapNel

Applies a function to every element, producing a new NonEmptyList. The non-empty guarantee is preserved.

Type: transform:(A -> B) -> nel:(NonEmptyList A) -> NonEmptyList B

use aivi.nonEmpty (
    NonEmptyList
    mapNel
)

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

type NonEmptyList Int -> (NonEmptyList Int)
func doubleAll = nel =>
    mapNel double nel

---

fromList

Attempts to convert a regular List to a NonEmptyList. Returns None if the list is empty.

Type: items:(List A) -> Option (NonEmptyList A)

use aivi.nonEmpty (
    NonEmptyList
    fromList
)

type List Int -> (Option (NonEmptyList Int))
func safeFromList = items =>
    fromList items

Use this when constructing a NonEmptyList from data whose size is not statically known, then handle the None case for empty input.

---

appendNel

Concatenates two NonEmptyLists into one. The result is always non-empty.

Type: left:(NonEmptyList A) -> right:(NonEmptyList A) -> NonEmptyList A

use aivi.nonEmpty (
    NonEmptyList
    appendNel
    singleton
)

type NonEmptyList Text -> (NonEmptyList Text) -> (NonEmptyList Text)
func combineErrors = a b =>
    appendNel a b

appendNel is used internally by aivi.validation to merge error lists from both sides of a failed zipValidation.