Record Class NonEmptyList<T>

java.lang.Object
java.lang.Record
dev.fforj.NonEmptyList<T>
All Implemented Interfaces:
Iterable<T>
public record NonEmptyList<T>(T head, List<T> tail) extends Record implements Iterable<T>
An immutable sequence with a compile-time guarantee that it contains at least one element. Iterable head-first; convert to a plain List with toList().

Use cases:

  • Validation: Validated.Invalid carries NonEmptyList<E> so callers can't forget to handle the empty-error case.
  • Domain constraints: a Permission's required scopes, a tenant's owners, any "must have at least one" collection.

Backed by a defensively-copied List for tail() so callers cannot mutate the internal state.

  • Constructor Details

    • NonEmptyList

      public NonEmptyList(T head, List<T> tail)
      Creates an instance of a NonEmptyList record class.
      Parameters:
      head - the value for the head record component
      tail - the value for the tail record component

  • Method Details

    • of

      public static <T> NonEmptyList<T> of(T head)
      One element.

    • of

      @SafeVarargs public static <T> NonEmptyList<T> of(T head, T... rest)
      One element + N more.

    • fromList

      public static <T> Optional<NonEmptyList<T>> fromList(List<? extends T> list)
      Try to lift a List. Returns empty if the list itself is empty: absence, not failure; use Result.fromOptional to attach a domain error if needed.

    • size

      public int size()
      Total element count: head plus tail; always at least 1.

    • toList

      public List<T> toList()
      Convert to an immutable plain List, head first.

    • stream

      public Stream<T> stream()
      Stream all elements, head first.

    • iterator

      public Iterator<T> iterator()
      Iterate all elements, head first. The iterator does not support removal.
      Specified by:
      iterator in interface Iterable<T>

    • map

      public <U> NonEmptyList<U> map(Function<? super T, ? extends U> f)
      Transform every element; the result is non-empty by construction.

    • append

      @SafeVarargs public final NonEmptyList<T> append(T first, T... more)
      Append one or more elements.

    • concat

      public NonEmptyList<T> concat(NonEmptyList<T> other)
      Concatenate two non-empty lists.

    • toString

      public final String toString()
      Returns a string representation of this record class. The representation contains the name of the class, followed by the name and value of each of the record components.
      Specified by:
      toString in class Record
      Returns:
      a string representation of this object

    • hashCode

      public final int hashCode()
      Returns a hash code value for this object. The value is derived from the hash code of each of the record components.
      Specified by:
      hashCode in class Record
      Returns:
      a hash code value for this object

    • equals

      public final boolean equals(Object o)
      Indicates whether some other object is "equal to" this one. The objects are equal if the other object is of the same class and if all the record components are equal. All components in this record class are compared with Objects::equals(Object,Object).
      Specified by:
      equals in class Record
      Parameters:
      o - the object with which to compare
      Returns:
      true if this object is the same as the o argument; false otherwise.

    • head

      public T head()
      Returns the value of the head record component.
      Returns:
      the value of the head record component

    • tail

      public List<T> tail()
      Returns the value of the tail record component.
      Returns:
      the value of the tail record component