Stream

Config & IO

Composable lazy enumerables for the BEAM target.

Like Elixir's Stream, these functions build a recipe. Nothing runs until you consume with foldl, toList, run, attempt, or attemptFoldl. Chain map / filter / take without allocating intermediate lists.

For large inputs (especially File.stream), prefer foldl, tryFoldl, stoppableFoldl, or attemptFoldl so only one element (or chunk) is live at a time. toList, attempt, and cycle materialize; avoid them on huge streams.

HTTP request body streams (Server.bodyStream, Multipart.fileStream) must be consumed synchronously inside handle with tryFoldl / stoppableFoldl — not attemptFoldl (tasks run after the response is sent).

From update, fold a file in a task:

File.stream path
    |> Stream.map parseRow
    |> Stream.filter isValid
    |> Stream.attemptFoldl (\_ n -> n + 1) 0
    |> Task.attempt GotCount

Types

Stream

type Stream a = Stream

A suspended sequence of a values.

Examples

Stream.fromList [ 1, 2, 3 ]

Error

type Error = ReadFailed String

Why consuming a resource-backed stream failed.

Examples

Err (Stream.ReadFailed "enoent")

Values

errorToString

errorToString : Error -> String

Human-readable form of an Error for logs.

Examples

Stream.errorToString err

empty

empty : Stream a

A stream with no elements.

Examples

Stream.empty

fromList

fromList : List a -> Stream a

Lift an eager list into a stream.

Examples

Stream.fromList [ 1, 2, 3 ]

unfold

unfold : (s -> Maybe (a, s)) -> s -> Stream a

Build a stream from a seed. Nothing ends the stream.

Examples

Stream.unfold (\n -> if n > 3 then Nothing else Just (n, n + 1)) 1

iterate

iterate : (a -> a) -> a -> Stream a

Infinite stream: x, f x, f (f x), ...

Examples

Stream.iterate (\n -> n + 1) 0

range

range : Int -> Int -> Stream Int

Inclusive integer range, like List.range. Empty when lo > hi.

Examples

Stream.range 1 10

repeat

repeat : a -> Stream a

Infinite stream of the same value.

Examples

Stream.repeat 0

repeatedly

repeatedly : (() -> a) -> Stream a

Infinite stream from a thunk called for each element.

Examples

Stream.repeatedly (\() -> Time.now)

cycle

cycle : Stream a -> Stream a

Repeat a finite stream forever. Buffers the whole stream once; empty stays empty.

Examples

Stream.cycle (Stream.fromList [ 1, 2 ])

resource

resource : (() -> s) -> (s -> Maybe (a, s)) -> (s -> ()) -> Stream a

Emit values from a resource. start runs on first pull, after on exhaust or early stop (take, discarded tail).

Examples

Stream.resource open next close

map

map : (a -> b) -> Stream a -> Stream b

Lazily transform each element.

Examples

Stream.map String.toUpper lines

filter

filter : (a -> Bool) -> Stream a -> Stream a

Lazily keep elements that pass the predicate.

Examples

Stream.filter (\n -> n > 0) nums

reject

reject : (a -> Bool) -> Stream a -> Stream a

Lazily drop elements that pass the predicate.

Examples

Stream.reject String.isEmpty lines

filterMap

filterMap : (a -> Maybe b) -> Stream a -> Stream b

Lazily map and drop Nothing results.

Examples

Stream.filterMap String.toInt lines

flatMap

flatMap : (a -> Stream b) -> Stream a -> Stream b

Lazily map to an inner stream and flatten.

Examples

Stream.flatMap (\n -> Stream.range 1 n) nums

take

take : Int -> Stream a -> Stream a

Lazily take the first n elements. Negative or zero yields empty.

Examples

Stream.take 10 infinite

drop

drop : Int -> Stream a -> Stream a

Lazily skip the first n elements.

Examples

Stream.drop 1 lines

takeWhile

takeWhile : (a -> Bool) -> Stream a -> Stream a

Lazily take while the predicate holds; then stop and release the rest.

Examples

Stream.takeWhile (\n -> n < 10) nums

dropWhile

dropWhile : (a -> Bool) -> Stream a -> Stream a

Lazily skip while the predicate holds.

Examples

Stream.dropWhile String.isEmpty lines

concat

concat : Stream a -> Stream a -> Stream a

Lazily emit left then right.

Examples

Stream.concat left right

concatAll

concatAll : Stream (Stream a) -> Stream a

Flatten a stream of streams.

Examples

Stream.concatAll (Stream.fromList [ a, b ])

zip

zip : Stream a -> Stream b -> Stream (a, b)

Lazily pair elements until either stream ends.

Examples

Stream.zip names ages

withIndex

withIndex : Stream a -> Stream (Int, a)

Pair each element with its zero-based index.

Examples

Stream.withIndex lines

intersperse

intersperse : a -> Stream a -> Stream a

Lazily insert a separator between elements.

Examples

Stream.intersperse "," parts

scan

scan : (a -> b -> b) -> b -> Stream a -> Stream b

Lazily scan: each emitted value is the new accumulator.

Examples

Stream.scan (\n acc -> acc + n) 0 nums

each

each : (a -> ()) -> Stream a -> Stream a

Run an effect for each element when the stream is later consumed.

Examples

Stream.each (\line -> Debug.log "line" line) lines

chunkEvery

chunkEvery : Int -> Stream a -> Stream (List a)

Lazily emit lists of at most n elements. The last chunk may be shorter. Zero or negative n yields empty.

Examples

Stream.chunkEvery 100 rows

foldl

foldl : (a -> b -> b) -> b -> Stream a -> b

Reduce a stream left-to-right. Raises on resource failure; see tryFoldl.

Examples

Stream.foldl (\_ n -> n + 1) 0 stream

toList

toList : Stream a -> List a

Materialize the whole stream as a list. Avoid on huge inputs.

Examples

Stream.toList (Stream.range 1 3)

run

run : Stream a -> ()

Drain a stream for its effects; discard values.

Examples

Stream.run effects

tryFoldl

tryFoldl : (a -> b -> b) -> b -> Stream a -> Result Error b

Like foldl, but resource failures become Err.

Examples

Stream.tryFoldl (\_ n -> n + 1) 0 (File.stream path)

stoppableFoldl

stoppableFoldl : (a -> b -> FoldStep b) -> b -> Stream a -> Result Error b

Left fold that can stop early via List.FoldStep. On Stop, the rest of the stream is discarded (releasing files / HTTP body resources). I/O failures are Err.

Examples

Stream.stoppableFoldl (\row n -> List.Continue (n + 1)) 0 rows

tryToList

tryToList : Stream a -> Result Error (List a)

Like toList, but resource failures become Err.

Examples

Stream.tryToList (File.stream path)

attempt

attempt : Stream a -> Task Error (List a)

Consume with tryToList as a Task for TEA. Prefer attemptFoldl for large streams.

Examples

Stream.attempt (File.stream path)

attemptFoldl

attemptFoldl : (a -> b -> b) -> b -> Stream a -> Task Error b

Consume with tryFoldl as a Task for TEA. Constant memory for large files.

Examples

Stream.attemptFoldl (\_ n -> n + 1) 0 (File.stream path)