NonEmptyList<T>

// of(head, tail) — explicit head + tail; all elements null-guarded
NonEmptyList<String> nel = NonEmptyList.of("a", List.of("b", "c"));
// ["a", "b", "c"]

// singleton — exactly one element
NonEmptyList<String> single = NonEmptyList.singleton("only");
// ["only"]

// fromList — safe conversion from a plain List; empty list returns None
Option<NonEmptyList<String>> fromList = NonEmptyList.fromList(someList);

// collector — accumulate a Stream into Option<NonEmptyList<T>>
Option<NonEmptyList<String>> fromStream =
    Stream.of("x", "y", "z").collect(NonEmptyList.collector());
// Some(["x", "y", "z"])

Option<NonEmptyList<String>> empty =
    Stream.<String>empty().collect(NonEmptyList.collector());
// None

NonEmptyList<String> nel = NonEmptyList.of("a", List.of("b", "c"));

String       head   = nel.head();     // "a"  — always present, never null
List<String> tail   = nel.tail();     // ["b", "c"] — unmodifiable, may be empty
List<String> all    = nel.toList();   // ["a", "b", "c"] — all elements
int          size   = nel.size();     // 3 — always >= 1

// SequencedCollection API (Java 21)
String first = nel.getFirst();        // "a" — alias for head()
String last  = nel.getLast();         // "c" — always safe, no emptiness check needed

// Singleton: tail is empty
NonEmptyList<String> one = NonEmptyList.singleton("only");
one.head();      // "only"
one.getFirst();  // "only"
one.getLast();   // "only"  — same element, no IndexOutOfBoundsException risk
one.tail();      // []  (empty unmodifiable list)
one.size();      // 1

NonEmptyList<String> nel = NonEmptyList.of("a", List.of("b", "c"));

// map — apply a function to every element; returns a new NonEmptyList
NonEmptyList<String> upper = nel.map(String::toUpperCase);
// ["A", "B", "C"]

// append — add an element at the end
NonEmptyList<String> appended = nel.append("d");
// ["a", "b", "c", "d"]

// prepend — add an element at the front
NonEmptyList<String> prepended = nel.prepend("z");
// ["z", "a", "b", "c"]

// concat — combine two NonEmptyLists
NonEmptyList<String> other  = NonEmptyList.of("x", List.of("y"));
NonEmptyList<String> merged = nel.concat(other);
// ["a", "b", "c", "x", "y"]

NonEmptyList<Integer> nel = NonEmptyList.of(1, List.of(2, 3, 4, 5));

// getFirst() / getLast() — always safe, no emptiness check needed
int first = nel.getFirst();  // 1
int last  = nel.getLast();   // 5

// reversed() — returns a new NonEmptyList in reverse order
NonEmptyList<Integer> rev = nel.reversed();
// rev.toList() → [5, 4, 3, 2, 1]
// original unchanged → nel.toList() → [1, 2, 3, 4, 5]

// Works as a java.util.SequencedCollection
SequencedCollection<Integer> sc = nel;
sc.getFirst();  // 1
sc.getLast();   // 5

// Mutating methods always throw — NonEmptyList is immutable
try { nel.addFirst(0);   } catch (UnsupportedOperationException e) { /* expected */ }
try { nel.addLast(6);    } catch (UnsupportedOperationException e) { /* expected */ }
try { nel.removeFirst(); } catch (UnsupportedOperationException e) { /* expected */ }
try { nel.removeLast();  } catch (UnsupportedOperationException e) { /* expected */ }

// Real-world: show the most recent and oldest event in a guaranteed-non-empty audit log
NonEmptyList<AuditEvent> log = auditService.getEvents(userId); // guaranteed non-empty
AuditEvent newest = log.getFirst();
AuditEvent oldest = log.getLast();

// Non-empty stream → Some(NonEmptyList)
Option<NonEmptyList<String>> tags =
    Stream.of("java", "fp", "dmx-fun")
          .filter(t -> t.length() > 2)
          .collect(NonEmptyList.toNonEmptyList());
// Some(["java", "dmx-fun"])   // "fp".length() == 2, filtered out by > 2

// Empty stream → None
Option<NonEmptyList<String>> noTags =
    Stream.<String>empty()
          .collect(NonEmptyList.toNonEmptyList());
// None

// Combine with other stream operations
Option<NonEmptyList<Integer>> evens =
    IntStream.rangeClosed(1, 10)
             .boxed()
             .filter(n -> n % 2 == 0)
             .collect(NonEmptyList.toNonEmptyList());
// Some([2, 4, 6, 8, 10])

// fromOptional: Optional<T> → Option<NonEmptyList<T>>
// Present → Some(singleton); empty → None
Option<NonEmptyList<String>> fromPresent = NonEmptyList.fromOptional(Optional.of("hello"));
// Some(["hello"])

Option<NonEmptyList<String>> fromEmpty = NonEmptyList.fromOptional(Optional.empty());
// None

// sequence: NonEmptyList<Option<T>> → Option<NonEmptyList<T>>
// Returns Some if every element is Some; None as soon as any element is None.
NonEmptyList<Option<Integer>> opts =
    NonEmptyList.of(Option.some(1), List.of(Option.some(2), Option.some(3)));

Option<NonEmptyList<Integer>> result = NonEmptyList.sequence(opts);
// Some([1, 2, 3])

NonEmptyList<Option<Integer>> withNone =
    NonEmptyList.of(Option.some(1), List.of(Option.none(), Option.some(3)));

Option<NonEmptyList<Integer>> missing = NonEmptyList.sequence(withNone);
// None

// collector: Stream<T> → Option<NonEmptyList<T>>
Option<NonEmptyList<String>> fromStream =
    Stream.of("hello", "world").collect(NonEmptyList.collector());
// Some(["hello", "world"])

// sequenceTry: NonEmptyList<Try<T>> → Try<NonEmptyList<T>>
// Success if every element succeeds; Failure from the first failing element.
NonEmptyList<Try<Integer>> tries = NonEmptyList.of(
    Try.success(1), List.of(Try.success(2), Try.success(3)));

Try<NonEmptyList<Integer>> allOk = NonEmptyList.sequenceTry(tries);
// Success([1, 2, 3])

NonEmptyList<Try<Integer>> withFailure = NonEmptyList.of(
    Try.success(1), List.of(Try.failure(new RuntimeException("boom")), Try.success(3)));

Try<NonEmptyList<Integer>> failed = NonEmptyList.sequenceTry(withFailure);
// Failure(RuntimeException("boom"))

// sequenceEither: NonEmptyList<Either<E, T>> → Either<E, NonEmptyList<T>>
// right if every element is right; left from the first left element.
NonEmptyList<Either<String, Integer>> eithers = NonEmptyList.of(
    Either.right(1), List.of(Either.right(2), Either.right(3)));

Either<String, NonEmptyList<Integer>> allRight = NonEmptyList.sequenceEither(eithers);
// right([1, 2, 3])

NonEmptyList<Either<String, Integer>> withLeft = NonEmptyList.of(
    Either.right(1), List.of(Either.left("invalid"), Either.right(3)));

Either<String, NonEmptyList<Integer>> firstLeft = NonEmptyList.sequenceEither(withLeft);
// left("invalid")

// sequenceResult: NonEmptyList<Result<T, E>> → Result<NonEmptyList<T>, E>
// ok if every element is ok; err from the first error element.
NonEmptyList<Result<Integer, String>> results = NonEmptyList.of(
    Result.ok(1), List.of(Result.ok(2), Result.ok(3)));

Result<NonEmptyList<Integer>, String> allOkResult = NonEmptyList.sequenceResult(results);
// ok([1, 2, 3])

NonEmptyList<Result<Integer, String>> withErr = NonEmptyList.of(
    Result.ok(1), List.of(Result.err("not found"), Result.ok(3)));

Result<NonEmptyList<Integer>, String> firstErr = NonEmptyList.sequenceResult(withErr);
// err("not found")

// invalidNel — wrap a single error in a singleton NonEmptyList
Validated<NonEmptyList<String>, Email>    emailV    = Validated.invalidNel("email is required");
Validated<NonEmptyList<String>, Password> passwordV = Validated.invalidNel("password too short");

// combine — use NonEmptyList::concat as the error merger to accumulate all errors
Validated<NonEmptyList<String>, Form> form =
    emailV.combine(passwordV, NonEmptyList::concat, Form::new);
// Invalid(["email is required", "password too short"])

// sequenceNel — sequence a list of Validated<NEL<E>, A> with concat built in
List<Validated<NonEmptyList<String>, Integer>> list = List.of(
    Validated.valid(1),
    Validated.invalidNel("too small"),
    Validated.invalidNel("out of range")
);

Validated<NonEmptyList<String>, List<Integer>> allErrors =
    Validated.sequenceNel(list);
// Invalid(["too small", "out of range"])

// traverseNel — validate each element of a collection and accumulate errors
List<String> inputs = List.of("42", "bad", "-1");

Validated<NonEmptyList<String>, List<Integer>> result =
    Validated.traverseNel(inputs, s -> {
        try {
            int n = Integer.parseInt(s);
            return n > 0 ? Validated.valid(n) : Validated.invalidNel("must be positive: " + s);
        } catch (NumberFormatException e) {
            return Validated.invalidNel("not a number: " + s);
        }
    });
// Invalid(["not a number: bad", "must be positive: -1"])

NonEmptyList<String> nel = NonEmptyList.of("banana", List.of("apple", "cherry", "apricot"));

// toStream() — sequential Stream without materializing an intermediate list
List<String> aFruits = nel.toStream()
    .filter(s -> s.startsWith("a"))
    .sorted()
    .collect(Collectors.toList());
// ["apple", "apricot"]

// Use in for-each (Iterable)
for (String fruit : nel) {
    System.out.println(fruit);
}

// Convert to Set
Set<String> set = nel.toStream().collect(Collectors.toSet());

NonEmptyList<String> nel = NonEmptyList.of("admin", List.of("editor", "admin", "viewer"));

// toNonEmptySet() — deduplicate while preserving head; insertion order retained
NonEmptySet<String> nes = nel.toNonEmptySet();
// NonEmptySet["admin", "editor", "viewer"]  (duplicate "admin" dropped)
nes.head();   // "admin"
nes.size();   // 3  (not 4)

// Singleton list — yields singleton set
NonEmptySet<String> single = NonEmptyList.singleton("admin").toNonEmptySet();
single.size();   // 1

// Round-trip: NonEmptySet → NonEmptyList → NonEmptySet (idempotent)
NonEmptySet<String> roles = NonEmptySet.of("admin", Set.of("editor"));
NonEmptySet<String> roundTrip = roles.toNonEmptyList().toNonEmptySet();
assertThat(roundTrip).isEqualTo(roles);

// Equality is structural — consistent with List.equals
NonEmptyList<String> a = NonEmptyList.of("x", List.of("y", "z"));
NonEmptyList<String> b = NonEmptyList.of("x", List.of("y", "z"));

boolean same = a.equals(b); // true
int     hash = a.hashCode(); // consistent with equals

// toString delegates to List.toString
String repr = a.toString(); // "[x, y, z]"

// Validate all fields and accumulate every error — no short-circuiting.
// invalidNel wraps a single error; NonEmptyList::concat merges two NELs.

public Validated<NonEmptyList<String>, RegistrationForm> validate(RawInput input) {

    Validated<NonEmptyList<String>, Email> emailV =
        Email.parse(input.email())
             .map(Validated::<NonEmptyList<String>, Email>valid)
             .getOrElseGet(() -> Validated.invalidNel("email is invalid"));

    Validated<NonEmptyList<String>, String> nameV =
        input.name().isBlank()
            ? Validated.invalidNel("name must not be blank")
            : Validated.valid(input.name().trim());

    Validated<NonEmptyList<String>, Password> passwordV =
        input.password().length() >= 8
            ? Validated.valid(Password.of(input.password()))
            : Validated.invalidNel("password must be at least 8 characters");

    return emailV
        .combine(nameV,     NonEmptyList::concat, (e, n)    -> new Partial(e, n))
        .combine(passwordV, NonEmptyList::concat, (p, pass) -> new RegistrationForm(p.email(), p.name(), pass));
}

// Caller receives all errors at once, never just the first one:
switch (validate(input)) {
    case Validated.Valid<?, RegistrationForm>(var form)     -> register(form);
    case Validated.Invalid<NonEmptyList<String>, ?>(var errs) ->
        errs.toList().forEach(System.err::println);
}