Skip to content
Effect Documentation

Introduction to Streams

In this guide, we’ll explore the concept of a Stream<A, E, R>. A Stream is a program description that, when executed, can emit zero or more values of type A, handle errors of type E, and operates within a context of type R.

Use Cases

Streams are particularly handy whenever you’re dealing with sequences of values over time. They can serve as replacements for observables, node streams, and AsyncIterables.

What is a Stream?

Think of a Stream as an extension of an Effect. While an Effect<A, E, R> represents a program that requires a context of type R, may encounter an error of type E, and always produces a single result of type A, a Stream<A, E, R> takes this further by allowing the emission of zero or more values of type A.

To clarify, let’s examine some examples using Effect:

1
import { 
import Effect
Effect, 
import Chunk
Chunk, 
import Option
Option } from "effect"
2


3
// An Effect that fails with a string error
4
const 
const failedEffect: Effect.Effect<never, string, never>
failedEffect = 
import Effect
Effect.
const fail: <string>(error: string) => Effect.Effect<never, string, never>
fail("fail!")
5


6
// An Effect that produces a single number
7
const 
const oneNumberValue: Effect.Effect<number, never, never>
oneNumberValue = 
import Effect
Effect.
const succeed: <number>(value: number) => Effect.Effect<number, never, never>
succeed(3)
8


9
// An Effect that produces a chunk of numbers
10
const 
const oneListValue: Effect.Effect<Chunk.NonEmptyChunk<number>, never, never>
oneListValue = 
import Effect
Effect.
const succeed: <Chunk.NonEmptyChunk<number>>(value: Chunk.NonEmptyChunk<number>) => Effect.Effect<Chunk.NonEmptyChunk<number>, never, never>
succeed(
import Chunk
Chunk.
const make: <[number, number, number]>(as_0: number, as_1: number, as_2: number) => Chunk.NonEmptyChunk<number>
Builds a `NonEmptyChunk` from an non-empty collection of elements.
make(1, 2, 3))
11


12
// An Effect that produces an optional number
13
const 
const oneOption: Effect.Effect<Option.Option<number>, never, never>
oneOption = 
import Effect
Effect.
const succeed: <Option.Option<number>>(value: Option.Option<number>) => Effect.Effect<Option.Option<number>, never, never>
succeed(
import Option
Option.
const some: <number>(value: number) => Option.Option<number>
Creates a new `Option` that wraps the given value.
some(1))

In each case, the Effect always ends with exactly one value. There is no variability; you always get one result.

Understanding Streams

Now, let’s shift our focus to Stream. A Stream represents a program description that shares similarities with Effect, it requires a context of type R, may signal errors of type E, and yields values of type A. However, the key distinction is that it can yield zero or more values.

Here are the possible scenarios for a Stream:

  • An Empty Stream: It can end up empty, representing a stream with no values.
  • A Single-Element Stream: It can represent a stream with just one value.
  • A Finite Stream of Elements: It can represent a stream with a finite number of values.
  • An Infinite Stream of Elements: It can represent a stream that continues indefinitely, essentially an infinite stream.

Let’s see these scenarios in action:

1
import { 
import Stream
Stream } from "effect"
2


3
// An empty Stream
4
const 
const emptyStream: Stream.Stream<never, never, never>
emptyStream = 
import Stream
Stream.
const empty: Stream.Stream<never, never, never>
The empty stream.
empty
5


6
// A Stream with a single number
7
const 
const oneNumberValueStream: Stream.Stream<number, never, never>
oneNumberValueStream = 
import Stream
Stream.
const succeed: <number>(value: number) => Stream.Stream<number, never, never>
Creates a single-valued pure stream.
succeed(3)
8


9
// A Stream with a range of numbers from 1 to 10
10
const 
const finiteNumberStream: Stream.Stream<number, never, never>
finiteNumberStream = 
import Stream
Stream.
const range: (min: number, max: number, chunkSize?: number) => Stream.Stream<number>
Constructs a stream from a range of integers, including both endpoints.
range(1, 10)
11


12
// An infinite Stream of numbers starting from 1 and incrementing
13
const 
const infiniteNumberStream: Stream.Stream<number, never, never>
infiniteNumberStream = 
import Stream
Stream.
const iterate: <number>(value: number, next: (value: number) => number) => Stream.Stream<number, never, never>
The infinite stream of iterative function application: a, f(a), f(f(a)),
f(f(f(a))), ...
iterate(1, (
(parameter) n: number
n) => 
(parameter) n: number
n + 1)

In summary, a Stream is a versatile tool for representing programs that may yield multiple values, making it suitable for a wide range of tasks, from processing finite lists to handling infinite sequences.