<Self extends Iterable<unknown>>(
elements: Self
): Self extends NonEmptyIterable.NonEmptyIterable<infer A>
? Effect.Effect<A>
: Self extends Arr.NonEmptyReadonlyArray<infer A>
? Effect.Effect<A>
: Self extends Iterable<infer A>
? Effect.Effect<A, Cause.NoSuchElementError>
: neverGets a random element from an iterable.
When to use
Use to select one value uniformly from a collection using the active Random
service.
Details
If the input type is known to be non-empty, the returned effect cannot fail.
Otherwise, empty iterables fail with Cause.NoSuchElementError.
Example (Choosing a random value)
import { Effect, Random } from "effect"
const program = Effect.gen(function*() {
const value = yield* Random.choice(["red", "green", "blue"] as const)
console.log(value)
})export const const choice: <
Self extends Iterable<unknown>
>(
elements: Self
) => Self extends NonEmptyIterable.NonEmptyIterable<
infer A
>
? Effect.Effect<A>
: Self extends Arr.NonEmptyReadonlyArray<
infer A
>
? Effect.Effect<A>
: Self extends Iterable<infer A>
? Effect.Effect<A, Cause.NoSuchElementError>
: never
Gets a random element from an iterable.
When to use
Use to select one value uniformly from a collection using the active Random
service.
Details
If the input type is known to be non-empty, the returned effect cannot fail.
Otherwise, empty iterables fail with Cause.NoSuchElementError.
Example (Choosing a random value)
import { Effect, Random } from "effect"
const program = Effect.gen(function*() {
const value = yield* Random.choice(["red", "green", "blue"] as const)
console.log(value)
})
choice: <function (type parameter) Self in <Self extends Iterable<unknown>>(elements: Self): Self extends NonEmptyIterable.NonEmptyIterable<infer A> ? Effect.Effect<A> : Self extends Arr.NonEmptyReadonlyArray<infer A> ? Effect.Effect<A> : Self extends Iterable<infer A> ? Effect.Effect<A, Cause.NoSuchElementError> : neverSelf extends interface Iterable<T, TReturn = any, TNext = any>Iterable<unknown>>(
elements: Self extends Iterable<unknown>elements: function (type parameter) Self in <Self extends Iterable<unknown>>(elements: Self): Self extends NonEmptyIterable.NonEmptyIterable<infer A> ? Effect.Effect<A> : Self extends Arr.NonEmptyReadonlyArray<infer A> ? Effect.Effect<A> : Self extends Iterable<infer A> ? Effect.Effect<A, Cause.NoSuchElementError> : neverSelf
) => function (type parameter) Self in <Self extends Iterable<unknown>>(elements: Self): Self extends NonEmptyIterable.NonEmptyIterable<infer A> ? Effect.Effect<A> : Self extends Arr.NonEmptyReadonlyArray<infer A> ? Effect.Effect<A> : Self extends Iterable<infer A> ? Effect.Effect<A, Cause.NoSuchElementError> : neverSelf extends import NonEmptyIterableNonEmptyIterable.interface NonEmptyIterable<out A>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
NonEmptyIterable<infer function (type parameter) AA> ? import EffectEffect.interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<function (type parameter) AA>
: function (type parameter) Self in <Self extends Iterable<unknown>>(elements: Self): Self extends NonEmptyIterable.NonEmptyIterable<infer A> ? Effect.Effect<A> : Self extends Arr.NonEmptyReadonlyArray<infer A> ? Effect.Effect<A> : Self extends Iterable<infer A> ? Effect.Effect<A, Cause.NoSuchElementError> : neverSelf extends import ArrArr.type NonEmptyReadonlyArray<A> = readonly [
A,
...A[]
]
A readonly array guaranteed to have at least one element.
When to use
Use when non-emptiness must be tracked at the type level while preventing mutation.
Many Array module functions accept or return this type.
Example (Typing a non-empty array)
import type { Array } from "effect"
const nonEmpty: Array.NonEmptyReadonlyArray<number> = [1, 2, 3]
const head: number = nonEmpty[0] // guaranteed to exist
NonEmptyReadonlyArray<infer function (type parameter) AA> ? import EffectEffect.interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<function (type parameter) AA>
: function (type parameter) Self in <Self extends Iterable<unknown>>(elements: Self): Self extends NonEmptyIterable.NonEmptyIterable<infer A> ? Effect.Effect<A> : Self extends Arr.NonEmptyReadonlyArray<infer A> ? Effect.Effect<A> : Self extends Iterable<infer A> ? Effect.Effect<A, Cause.NoSuchElementError> : neverSelf extends interface Iterable<T, TReturn = any, TNext = any>Iterable<infer function (type parameter) AA> ? import EffectEffect.interface Effect<out A, out E = never, out R = never>The Effect interface defines a value that lazily describes a workflow or
job. The workflow requires some context R, and may fail with an error of
type E, or succeed with a value of type A.
When to use
Use when you need to represent a lazy, composable workflow that can require
services, fail with a typed error, or succeed with a typed value.
Details
Effect values model resourceful interaction with the outside world,
including synchronous, asynchronous, concurrent, and parallel interaction.
They use a fiber-based concurrency model, with built-in support for
scheduling, fine-grained interruption, structured concurrency, and high
scalability.
To run an Effect value, you need a Runtime, which is a type that is
capable of executing Effect values.
Effect<function (type parameter) AA, import CauseCause.NoSuchElementError>
: never = ((elements: Iterable<unknown>elements: interface Iterable<T, TReturn = any, TNext = any>Iterable<unknown>) => {
const const buffer: unknown[]buffer = var Array: ArrayConstructorArray.ArrayConstructor.from<unknown>(iterable: Iterable<unknown> | ArrayLike<unknown>): unknown[] (+3 overloads)Creates an array from an iterable object.
from(elements: Iterable<unknown>elements)
return const buffer: unknown[]buffer.Array<T>.length: numberGets or sets the length of the array. This is a number one higher than the highest index in the array.
length === 0
? import EffectEffect.const fail: <E>(
error: E
) => Effect<never, E>
Creates an Effect that represents a recoverable error.
When to use
Use to explicitly signal a recoverable error in an Effect.
Details
The error keeps propagating unless it is handled. You can handle tagged
errors with functions like
catchTag
or
catchTags
.
Example (Creating a failed effect)
import { Data, Effect } from "effect"
class OperationFailedError extends Data.TaggedError("OperationFailedError")<{}> {}
// ┌─── Effect<never, OperationFailedError, never>
// ▼
const failure = Effect.fail(
new OperationFailedError()
)
fail(new import CauseCause.const NoSuchElementError: new (
message?: string
) => NoSuchElementError
Constructs a NoSuchElementError with an optional message.
When to use
Use to create the error value for APIs that intentionally fail when an
expected element is absent.
Example (Creating a NoSuchElementError)
import { Cause } from "effect"
const error = new Cause.NoSuchElementError("Element not found")
console.log(error.message) // "Element not found"
NoSuchElementError("Cannot select a random element from an empty array"))
: const randomWith: <A>(
f: (random: (typeof Random)["Service"]) => A
) => Effect.Effect<A>
r: {
nextIntUnsafe(): number
nextDoubleUnsafe(): number
}
const buffer: unknown[]buffer[var Math: MathAn intrinsic object that provides basic mathematics functionality and constants.
Math.Math.min(...values: number[]): numberReturns the smaller of a set of supplied numeric expressions.
min(const buffer: unknown[]buffer.Array<T>.length: numberGets or sets the length of the array. This is a number one higher than the highest index in the array.
length - 1, var Math: MathAn intrinsic object that provides basic mathematics functionality and constants.
Math.Math.floor(x: number): numberReturns the greatest integer less than or equal to its numeric argument.
floor(r: {
nextIntUnsafe(): number
nextDoubleUnsafe(): number
}
function nextDoubleUnsafe(): numbernextDoubleUnsafe() * const buffer: unknown[]buffer.Array<T>.length: numberGets or sets the length of the array. This is a number one higher than the highest index in the array.
length))]!)
}) as any