effect-io-ai

Package: effect
Module: NonEmptyIterable

NonEmptyIterable.NonEmptyIterable

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.

Example (Working with non-empty iterables)

import { Array, Chunk, NonEmptyIterable } from "effect"

// Function that requires non-empty data
function getFirst<A>(data: NonEmptyIterable.NonEmptyIterable<A>): A {
  // Safe - guaranteed to have at least one element
  const [first] = NonEmptyIterable.unprepend(data)
  return first
}

// Works with any non-empty iterable
const numbers = Array.make(
  1,
  2,
  3
) as unknown as NonEmptyIterable.NonEmptyIterable<number>
const firstNumber = getFirst(numbers) // 1

const chars = "hello" as unknown as NonEmptyIterable.NonEmptyIterable<string>
const firstChar = getFirst(chars) // "h"

const entries = new Map([["a", 1], [
  "b",
  2
]]) as unknown as NonEmptyIterable.NonEmptyIterable<[string, number]>
const firstEntry = getFirst(entries) // ["a", 1]

// Custom generator
function* countdown(): Generator<number> {
  yield 3
  yield 2
  yield 1
}
const firstCount = getFirst(
  Chunk.fromIterable(
    countdown()
  ) as unknown as NonEmptyIterable.NonEmptyIterable<number>
) // 3

Signature

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

Source

Since v2.0.0