Skip to content

NonEmptyIterable

The NonEmptyIterable module provides a type-level representation of any JavaScript Iterable that is known to contain at least one element. A NonEmptyIterable<A> can be consumed anywhere an Iterable<A> is expected, while also carrying the guarantee that reading the first element is safe.

3 exports Added in v2.0.0 Source

Getters

unprepend

Added in v2.0.0 Source

Extracts the first element and remaining elements from a non-empty iterable safely.

When to use

Use to split a non-empty iterable into its first element and an iterator for the remaining elements.

Details

This function provides a safe way to deconstruct a NonEmptyIterable into its head (first element) and tail (remaining elements as an iterator). Since the iterable is guaranteed to be non-empty, the first element is always available.

Signature

declare function unprepend<A>(
  self: NonEmptyIterable<A>,
): [firstElement: A, remainingElements: Iterator<A, any, any>];

Models

NonEmptyIterable interface

Added in v2.0.0 Source

Represents an iterable that is guaranteed to contain at least one element.

When to use

Use to require an iterable input that must provide at least one element.

Details

NonEmptyIterable<A> extends the standard Iterable<A> interface with a type-level guarantee of non-emptiness. This allows for safe operations that would otherwise require runtime checks or could throw exceptions.

The type is branded with a unique symbol to ensure type safety while maintaining full compatibility with JavaScript's iteration protocol.

Signature

interface NonEmptyIterable<out A> extends Iterable<A> {
  readonly [nonEmpty]: A;
}

Symbols

nonEmpty

Added in v2.0.0 Source

Defines the type-level symbol used to brand the NonEmptyIterable type.

When to use

Use as the property key for the type-level brand that marks an Iterable as non-empty.

Details

NonEmptyIterable<A> includes readonly [nonEmpty]: A, which makes it distinct from a plain Iterable<A> at compile time while preserving the normal iteration shape.

See

Signature

declare const nonEmpty: unique symbol;