effect 3.4.8 → 3.5.0

package/dist/esm/Stream.js

@@ -32,6 +32,29 @@ export const accumulateChunks = internal.accumulateChunks;
  * Creates a stream from a single value that will get cleaned up after the
  * stream is consumed.
  *
+ * @example
+ * import { Console, Effect, Stream } from "effect"
+ *
+ * // Simulating File operations
+ * const open = (filename: string) =>
+ *   Effect.gen(function*() {
+ *     yield* Console.log(`Opening ${filename}`)
+ *     return {
+ *       getLines: Effect.succeed(["Line 1", "Line 2", "Line 3"]),
+ *       close: Console.log(`Closing ${filename}`)
+ *     }
+ *   })
+ *
+ * const stream = Stream.acquireRelease(
+ *   open("file.txt"),
+ *   (file) => file.close
+ * ).pipe(Stream.flatMap((file) => file.getLines))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // Opening file.txt
+ * // Closing file.txt
+ * // { _id: 'Chunk', values: [ [ 'Line 1', 'Line 2', 'Line 3' ] ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -83,6 +106,14 @@ export const aggregateWithinEither = internal.aggregateWithinEither;
 /**
  * Maps the success values of this stream to the specified constant value.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.range(1, 5).pipe(Stream.as(null))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ null, null, null, null, null ] }
+ *
  * @since 2.0.0
  * @category mapping
  */
@@ -97,6 +128,29 @@ export {
  * The registration function can optionally return an `Effect`, which will be
  * executed if the `Fiber` executing this Effect is interrupted.
  *
+ * @example
+ * import type { StreamEmit } from "effect"
+ * import { Chunk, Effect, Option, Stream } from "effect"
+ *
+ * const events = [1, 2, 3, 4]
+ *
+ * const stream = Stream.async(
+ *   (emit: StreamEmit.Emit<never, never, number, void>) => {
+ *     events.forEach((n) => {
+ *       setTimeout(() => {
+ *         if (n === 3) {
+ *           emit(Effect.fail(Option.none())) // Terminate the stream
+ *         } else {
+ *           emit(Effect.succeed(Chunk.of(n))) // Add the current item to the stream
+ *         }
+ *       }, 100 * n)
+ *     })
+ *   }
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -135,6 +189,77 @@ export const branchAfter = internal.branchAfter;
  * as this stream. The driver stream will only ever advance the `maximumLag`
  * chunks before the slowest downstream stream.
  *
+ * @example
+ * import { Console, Effect, Fiber, Schedule, Stream } from "effect"
+ *
+ * const numbers = Effect.scoped(
+ *   Stream.range(1, 20).pipe(
+ *     Stream.tap((n) => Console.log(`Emit ${n} element before broadcasting`)),
+ *     Stream.broadcast(2, 5),
+ *     Stream.flatMap(([first, second]) =>
+ *       Effect.gen(function*() {
+ *         const fiber1 = yield* Stream.runFold(first, 0, (acc, e) => Math.max(acc, e)).pipe(
+ *           Effect.andThen((max) => Console.log(`Maximum: ${max}`)),
+ *           Effect.fork
+ *         )
+ *         const fiber2 = yield* second.pipe(
+ *           Stream.schedule(Schedule.spaced("1 second")),
+ *           Stream.runForEach((n) => Console.log(`Logging to the Console: ${n}`)),
+ *           Effect.fork
+ *         )
+ *         yield* Fiber.join(fiber1).pipe(
+ *           Effect.zip(Fiber.join(fiber2), { concurrent: true })
+ *         )
+ *       })
+ *     ),
+ *     Stream.runCollect
+ *   )
+ * )
+ *
+ * // Effect.runPromise(numbers).then(console.log)
+ * // Emit 1 element before broadcasting
+ * // Emit 2 element before broadcasting
+ * // Emit 3 element before broadcasting
+ * // Emit 4 element before broadcasting
+ * // Emit 5 element before broadcasting
+ * // Emit 6 element before broadcasting
+ * // Emit 7 element before broadcasting
+ * // Emit 8 element before broadcasting
+ * // Emit 9 element before broadcasting
+ * // Emit 10 element before broadcasting
+ * // Emit 11 element before broadcasting
+ * // Logging to the Console: 1
+ * // Logging to the Console: 2
+ * // Logging to the Console: 3
+ * // Logging to the Console: 4
+ * // Logging to the Console: 5
+ * // Emit 12 element before broadcasting
+ * // Emit 13 element before broadcasting
+ * // Emit 14 element before broadcasting
+ * // Emit 15 element before broadcasting
+ * // Emit 16 element before broadcasting
+ * // Logging to the Console: 6
+ * // Logging to the Console: 7
+ * // Logging to the Console: 8
+ * // Logging to the Console: 9
+ * // Logging to the Console: 10
+ * // Emit 17 element before broadcasting
+ * // Emit 18 element before broadcasting
+ * // Emit 19 element before broadcasting
+ * // Emit 20 element before broadcasting
+ * // Logging to the Console: 11
+ * // Logging to the Console: 12
+ * // Logging to the Console: 13
+ * // Logging to the Console: 14
+ * // Logging to the Console: 15
+ * // Maximum: 20
+ * // Logging to the Console: 16
+ * // Logging to the Console: 17
+ * // Logging to the Console: 18
+ * // Logging to the Console: 19
+ * // Logging to the Console: 20
+ * // { _id: 'Chunk', values: [ undefined ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -174,9 +299,38 @@ export const broadcastedQueuesDynamic = internal.broadcastedQueuesDynamic;
  * Allows a faster producer to progress independently of a slower consumer by
  * buffering up to `capacity` elements in a queue.
  *
- * @note This combinator destroys the chunking structure. It's recommended to
+ * Note: This combinator destroys the chunking structure. It's recommended to
  *       use rechunk afterwards. Additionally, prefer capacities that are powers
  *       of 2 for better performance.
+ *
+ * @example
+ * import { Console, Effect, Schedule, Stream } from "effect"
+ *
+ * const stream = Stream.range(1, 10).pipe(
+ *   Stream.tap((n) => Console.log(`before buffering: ${n}`)),
+ *   Stream.buffer({ capacity: 4 }),
+ *   Stream.tap((n) => Console.log(`after buffering: ${n}`)),
+ *   Stream.schedule(Schedule.spaced("5 seconds"))
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // before buffering: 1
+ * // before buffering: 2
+ * // before buffering: 3
+ * // before buffering: 4
+ * // before buffering: 5
+ * // before buffering: 6
+ * // after buffering: 1
+ * // after buffering: 2
+ * // before buffering: 7
+ * // after buffering: 3
+ * // before buffering: 8
+ * // after buffering: 4
+ * // before buffering: 9
+ * // after buffering: 5
+ * // before buffering: 10
+ * // ...
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -245,6 +399,14 @@ export const catchSomeCause = internal.catchSomeCause;
  * previous element emitted, using natural equality to determine whether two
  * elements are equal.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.make(1, 1, 1, 2, 2, 3, 4).pipe(Stream.changes)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2, 3, 4 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -313,6 +475,17 @@ export const combineChunks = internal.combineChunks;
  * that emits the elements from this stream and then the elements from the
  * specified stream.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const s1 = Stream.make(1, 2, 3)
+ * const s2 = Stream.make(4, 5)
+ *
+ * const stream = Stream.concat(s1, s2)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2, 3, 4, 5 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -320,6 +493,24 @@ export const concat = internal.concat;
 /**
  * Concatenates all of the streams in the chunk to one stream.
  *
+ * @example
+ * import { Chunk, Effect, Stream } from "effect"
+ *
+ * const s1 = Stream.make(1, 2, 3)
+ * const s2 = Stream.make(4, 5)
+ * const s3 = Stream.make(6, 7, 8)
+ *
+ * const stream = Stream.concatAll(Chunk.make(s1, s2, s3))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // {
+ * //   _id: 'Chunk',
+ * //   values: [
+ * //     1, 2, 3, 4,
+ * //     5, 6, 7, 8
+ * //   ]
+ * // }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -331,6 +522,22 @@ export const concatAll = internal.concatAll;
  *
  * See also `Stream.zip` for the more common point-wise variant.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const s1 = Stream.make(1, 2, 3)
+ * const s2 = Stream.make("a", "b")
+ *
+ * const product = Stream.cross(s1, s2)
+ *
+ * // Effect.runPromise(Stream.runCollect(product)).then(console.log)
+ * // {
+ * //   _id: "Chunk",
+ * //   values: [
+ * //     [ 1, "a" ], [ 1, "b" ], [ 2, "a" ], [ 2, "b" ], [ 3, "a" ], [ 3, "b" ]
+ * //   ]
+ * // }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -380,6 +587,45 @@ export const crossWith = internal.crossWith;
  * example, a search engine may only want to initiate a search after a user
  * has paused typing so as to not prematurely recommend results.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * let last = Date.now()
+ * const log = (message: string) =>
+ *   Effect.sync(() => {
+ *     const end = Date.now()
+ *     console.log(`${message} after ${end - last}ms`)
+ *     last = end
+ *   })
+ *
+ * const stream = Stream.make(1, 2, 3).pipe(
+ *   Stream.concat(
+ *     Stream.fromEffect(Effect.sleep("200 millis").pipe(Effect.as(4))) // Emit 4 after 200 ms
+ *   ),
+ *   Stream.concat(Stream.make(5, 6)), // Continue with more rapid values
+ *   Stream.concat(
+ *     Stream.fromEffect(Effect.sleep("150 millis").pipe(Effect.as(7))) // Emit 7 after 150 ms
+ *   ),
+ *   Stream.concat(Stream.make(8)),
+ *   Stream.tap((n) => log(`Received ${n}`)),
+ *   Stream.debounce("100 millis"), // Only emit values after a pause of at least 100 milliseconds,
+ *   Stream.tap((n) => log(`> Emitted ${n}`))
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // Received 1 after 5ms
+ * // Received 2 after 2ms
+ * // Received 3 after 0ms
+ * // > Emitted 3 after 104ms
+ * // Received 4 after 99ms
+ * // Received 5 after 1ms
+ * // Received 6 after 0ms
+ * // > Emitted 6 after 101ms
+ * // Received 7 after 50ms
+ * // Received 8 after 1ms
+ * // > Emitted 8 after 101ms
+ * // { _id: 'Chunk', values: [ 3, 6, 8 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -430,6 +676,15 @@ export const distributedWithDynamic = internal.distributedWithDynamic;
  * Converts this stream to a stream that executes its effects but emits no
  * elements. Useful for sequencing effects using streams:
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * // We create a stream and immediately drain it.
+ * const stream = Stream.range(1, 6).pipe(Stream.drain)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -505,6 +760,14 @@ export const either = internal.either;
 /**
  * The empty stream.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.empty
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -512,6 +775,22 @@ export const empty = internal.empty;
 /**
  * Executes the provided finalizer after this stream's finalizers run.
  *
+ * @example
+ * import { Console, Effect, Stream } from "effect"
+ *
+ * const program = Stream.fromEffect(Console.log("Application Logic.")).pipe(
+ *   Stream.concat(Stream.finalizer(Console.log("Finalizing the stream"))),
+ *   Stream.ensuring(
+ *     Console.log("Doing some other works after stream's finalization")
+ *   )
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(program)).then(console.log)
+ * // Application Logic.
+ * // Finalizing the stream
+ * // Doing some other works after stream's finalization
+ * // { _id: 'Chunk', values: [ undefined, undefined ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -561,6 +840,18 @@ export const execute = internal.execute;
 /**
  * Terminates with the specified error.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.fail("Uh oh!")
+ *
+ * Effect.runPromiseExit(Stream.runCollect(stream)).then(console.log)
+ * // {
+ * //   _id: 'Exit',
+ * //   _tag: 'Failure',
+ * //   cause: { _id: 'Cause', _tag: 'Fail', failure: 'Uh oh!' }
+ * // }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -589,6 +880,14 @@ export const failCauseSync = internal.failCauseSync;
 /**
  * Filters the elements emitted by this stream using the provided function.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.range(1, 11).pipe(Stream.filter((n) => n % 2 === 0))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 2, 4, 6, 8, 10 ] }
+ *
  * @since 2.0.0
  * @category filtering
  */
@@ -634,6 +933,29 @@ export const filterMapWhileEffect = internal.filterMapWhileEffect;
  * Creates a one-element stream that never fails and executes the finalizer
  * when it ends.
  *
+ * @example
+ * import { Console, Effect, Stream } from "effect"
+ *
+ * const application = Stream.fromEffect(Console.log("Application Logic."))
+ *
+ * const deleteDir = (dir: string) => Console.log(`Deleting dir: ${dir}`)
+ *
+ * const program = application.pipe(
+ *   Stream.concat(
+ *     Stream.finalizer(
+ *       deleteDir("tmp").pipe(
+ *         Effect.andThen(Console.log("Temporary directory was deleted."))
+ *       )
+ *     )
+ *   )
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(program)).then(console.log)
+ * // Application Logic.
+ * // Deleting dir: tmp
+ * // Temporary directory was deleted.
+ * // { _id: 'Chunk', values: [ undefined, undefined ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -725,6 +1047,22 @@ export const forever = internal.forever;
 /**
  * Creates a stream from an `AsyncIterable`.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const myAsyncIterable = async function*() {
+ *   yield 1
+ *   yield 2
+ * }
+ *
+ * const stream = Stream.fromAsyncIterable(
+ *   myAsyncIterable(),
+ *   (e) => new Error(String(e)) // Error Handling
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -746,6 +1084,15 @@ export const toChannel = internal.toChannel;
 /**
  * Creates a stream from a `Chunk` of values.
  *
+ * @example
+ * import { Chunk, Effect, Stream } from "effect"
+ *
+ * // Creating a stream with values from a single Chunk
+ * const stream = Stream.fromChunk(Chunk.make(1, 2, 3))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2, 3 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -769,6 +1116,15 @@ export const fromChunkQueue = internal.fromChunkQueue;
 /**
  * Creates a stream from an arbitrary number of chunks.
  *
+ * @example
+ * import { Chunk, Effect, Stream } from "effect"
+ *
+ * // Creating a stream with values from multiple Chunks
+ * const stream = Stream.fromChunks(Chunk.make(1, 2, 3), Chunk.make(4, 5, 6))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2, 3, 4, 5, 6 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -777,6 +1133,14 @@ export const fromChunks = internal.fromChunks;
  * Either emits the success value of this effect or terminates the stream
  * with the failure value of this effect.
  *
+ * @example
+ * import { Effect, Random, Stream } from "effect"
+ *
+ * const stream = Stream.fromEffect(Random.nextInt)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // Example Output: { _id: 'Chunk', values: [ 922694024 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -800,6 +1164,16 @@ export const fromPubSub = internal.fromPubSub;
 /**
  * Creates a new `Stream` from an iterable collection of values.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const numbers = [1, 2, 3]
+ *
+ * const stream = Stream.fromIterable(numbers)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2, 3 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -807,6 +1181,23 @@ export const fromIterable = internal.fromIterable;
 /**
  * Creates a stream from an effect producing a value of type `Iterable<A>`.
  *
+ * @example
+ * import { Context, Effect, Stream } from "effect"
+ *
+ * class Database extends Context.Tag("Database")<
+ *   Database,
+ *   { readonly getUsers: Effect.Effect<Array<string>> }
+ * >() {}
+ *
+ * const getUsers = Database.pipe(Effect.andThen((_) => _.getUsers))
+ *
+ * const stream = Stream.fromIterableEffect(getUsers)
+ *
+ * // Effect.runPromise(
+ * //   Stream.runCollect(stream.pipe(Stream.provideService(Database, { getUsers: Effect.succeed(["user1", "user2"]) })))
+ * // ).then(console.log)
+ * // { _id: 'Chunk', values: [ 'user1', 'user2' ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -860,6 +1251,19 @@ export const fromReadableStreamByob = internal.fromReadableStreamByob;
  * input. The stream will emit an element for each value output from the
  * schedule, continuing for as long as the schedule continues.
  *
+ * @example
+ * import { Effect, Schedule, Stream } from "effect"
+ *
+ * // Emits values every 1 second for a total of 5 emissions
+ * const schedule = Schedule.spaced("1 second").pipe(
+ *   Schedule.compose(Schedule.recurs(5))
+ * )
+ *
+ * const stream = Stream.fromSchedule(schedule)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 0, 1, 2, 3, 4 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -875,6 +1279,35 @@ export const groupAdjacentBy = internal.groupAdjacentBy;
 /**
  * More powerful version of `Stream.groupByKey`.
  *
+ * @example
+ * import { Chunk, Effect, GroupBy, Stream } from "effect"
+ *
+ * const groupByKeyResult = Stream.fromIterable([
+ *   "Mary",
+ *   "James",
+ *   "Robert",
+ *   "Patricia",
+ *   "John",
+ *   "Jennifer",
+ *   "Rebecca",
+ *   "Peter"
+ * ]).pipe(
+ *   Stream.groupBy((name) => Effect.succeed([name.substring(0, 1), name]))
+ * )
+ *
+ * const stream = GroupBy.evaluate(groupByKeyResult, (key, stream) =>
+ *   Stream.fromEffect(
+ *     Stream.runCollect(stream).pipe(
+ *       Effect.andThen((chunk) => [key, Chunk.size(chunk)] as const)
+ *     )
+ *   ))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // {
+ * //   _id: 'Chunk',
+ * //   values: [ [ 'M', 1 ], [ 'J', 3 ], [ 'R', 2 ], [ 'P', 2 ] ]
+ * // }
+ *
  * @since 2.0.0
  * @category grouping
  */
@@ -920,6 +1353,22 @@ export const groupByKey = _groupBy.groupByKey;
 /**
  * Partitions the stream with specified `chunkSize`.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.range(0, 8).pipe(Stream.grouped(3))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then((chunks) => console.log("%o", chunks))
+ * // {
+ * //   _id: 'Chunk',
+ * //   values: [
+ * //     { _id: 'Chunk', values: [ 0, 1, 2, [length]: 3 ] },
+ * //     { _id: 'Chunk', values: [ 3, 4, 5, [length]: 3 ] },
+ * //     { _id: 'Chunk', values: [ 6, 7, 8, [length]: 3 ] },
+ * //     [length]: 3
+ * //   ]
+ * // }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -928,6 +1377,43 @@ export const grouped = internal.grouped;
  * Partitions the stream with the specified `chunkSize` or until the specified
  * `duration` has passed, whichever is satisfied first.
  *
+ * @example
+ * import { Chunk, Effect, Schedule, Stream } from "effect"
+ *
+ * const stream = Stream.range(0, 9).pipe(
+ *   Stream.repeat(Schedule.spaced("1 second")),
+ *   Stream.groupedWithin(18, "1.5 seconds"),
+ *   Stream.take(3)
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then((chunks) => console.log(Chunk.toArray(chunks)))
+ * // [
+ * //   {
+ * //     _id: 'Chunk',
+ * //     values: [
+ * //       0, 1, 2, 3, 4, 5, 6,
+ * //       7, 8, 9, 0, 1, 2, 3,
+ * //       4, 5, 6, 7
+ * //     ]
+ * //   },
+ * //   {
+ * //     _id: 'Chunk',
+ * //     values: [
+ * //       8, 9, 0, 1, 2,
+ * //       3, 4, 5, 6, 7,
+ * //       8, 9
+ * //     ]
+ * //   },
+ * //   {
+ * //     _id: 'Chunk',
+ * //     values: [
+ * //       0, 1, 2, 3, 4, 5, 6,
+ * //       7, 8, 9, 0, 1, 2, 3,
+ * //       4, 5, 6, 7
+ * //     ]
+ * //   }
+ * // ]
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -979,6 +1465,16 @@ export const identity = internal.identityStream;
  * one stream is exhausted all remaining values in the other stream will be
  * pulled.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const s1 = Stream.make(1, 2, 3)
+ * const s2 = Stream.make(4, 5, 6)
+ *
+ * const stream = Stream.interleave(s1, s2)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 4, 2, 5, 3, 6 ] }
  * @since 2.0.0
  * @category utils
  */
@@ -992,6 +1488,25 @@ export const interleave = internal.interleave;
  * stream are exhausted further requests for values from that stream will be
  * ignored.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const s1 = Stream.make(1, 3, 5, 7, 9)
+ * const s2 = Stream.make(2, 4, 6, 8, 10)
+ *
+ * const booleanStream = Stream.make(true, false, false).pipe(Stream.forever)
+ *
+ * const stream = Stream.interleaveWith(s1, s2, booleanStream)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // {
+ * //   _id: 'Chunk',
+ * //   values: [
+ * //     1, 2,  4, 3, 6,
+ * //     8, 5, 10, 7, 9
+ * //   ]
+ * // }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -999,6 +1514,20 @@ export const interleaveWith = internal.interleaveWith;
 /**
  * Intersperse stream with provided `element`.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.make(1, 2, 3, 4, 5).pipe(Stream.intersperse(0))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // {
+ * //   _id: 'Chunk',
+ * //   values: [
+ * //     1, 0, 2, 0, 3,
+ * //     0, 4, 0, 5
+ * //   ]
+ * // }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -1006,6 +1535,27 @@ export const intersperse = internal.intersperse;
 /**
  * Intersperse the specified element, also adding a prefix and a suffix.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.make(1, 2, 3, 4, 5).pipe(
+ *   Stream.intersperseAffixes({
+ *     start: "[",
+ *     middle: "-",
+ *     end: "]"
+ *   })
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // {
+ * //   _id: 'Chunk',
+ * //   values: [
+ * //     '[', 1,   '-', 2,   '-',
+ * //     3,   '-', 4,   '-', 5,
+ * //     ']'
+ * //   ]
+ * // }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -1046,6 +1596,15 @@ export const interruptWhenDeferred = internal.interruptWhenDeferred;
  * The infinite stream of iterative function application: a, f(a), f(f(a)),
  * f(f(f(a))), ...
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * // An infinite Stream of numbers starting from 1 and incrementing
+ * const stream = Stream.iterate(1, (n) => n + 1)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream.pipe(Stream.take(10)))).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -1053,6 +1612,14 @@ export const iterate = internal.iterate;
 /**
  * Creates a stream from an sequence of values.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.make(1, 2, 3)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2, 3 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -1060,6 +1627,14 @@ export const make = internal.make;
 /**
  * Transforms the elements of this stream using the supplied function.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.make(1, 2, 3).pipe(Stream.map((n) => n + 1))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 2, 3, 4 ] }
+ *
  * @since 2.0.0
  * @category mapping
  */
@@ -1067,6 +1642,18 @@ export const map = internal.map;
 /**
  * Statefully maps over the elements of this stream to produce new elements.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const runningTotal = (stream: Stream.Stream<number>): Stream.Stream<number> =>
+ *   stream.pipe(Stream.mapAccum(0, (s, a) => [s + a, s + a]))
+ *
+ * // input:  0, 1, 2, 3, 4, 5, 6
+ * // Effect.runPromise(Stream.runCollect(runningTotal(Stream.range(0, 6)))).then(
+ * //   console.log
+ * // )
+ * // { _id: "Chunk", values: [ 0, 1, 3, 6, 10, 15, 21 ] }
+ *
  * @since 2.0.0
  * @category mapping
  */
@@ -1105,6 +1692,17 @@ export const mapChunksEffect = internal.mapChunksEffect;
  * Maps each element to an iterable, and flattens the iterables into the
  * output of this stream.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const numbers = Stream.make("1-2-3", "4-5", "6").pipe(
+ *   Stream.mapConcat((s) => s.split("-")),
+ *   Stream.map((s) => parseInt(s))
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(numbers)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2, 3, 4, 5, 6 ] }
+ *
  * @since 2.0.0
  * @category mapping
  */
@@ -1136,6 +1734,16 @@ export const mapConcatEffect = internal.mapConcatEffect;
 /**
  * Maps over elements of the stream with the specified effectful function.
  *
+ * @example
+ * import { Effect, Random, Stream } from "effect"
+ *
+ * const stream = Stream.make(10, 20, 30).pipe(
+ *   Stream.mapEffect((n) => Random.nextIntBetween(0, n))
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // Example Output: { _id: 'Chunk', values: [ 7, 19, 8 ] }
+ *
  * @since 2.0.0
  * @category mapping
  */
@@ -1160,6 +1768,21 @@ export const mapErrorCause = internal.mapErrorCause;
  * New produced stream will terminate when both specified stream terminate if
  * no termination strategy is specified.
  *
+ * @example
+ * import { Effect, Schedule, Stream } from "effect"
+ *
+ * const s1 = Stream.make(1, 2, 3).pipe(
+ *   Stream.schedule(Schedule.spaced("100 millis"))
+ * )
+ * const s2 = Stream.make(4, 5, 6).pipe(
+ *   Stream.schedule(Schedule.spaced("200 millis"))
+ * )
+ *
+ * const stream = Stream.merge(s1, s2)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 4, 2, 3, 5, 6 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -1180,6 +1803,24 @@ export const mergeAll = internal.mergeAll;
  * New produced stream will terminate when both specified stream terminate if
  * no termination strategy is specified.
  *
+ * @example
+ * import { Effect, Schedule, Stream } from "effect"
+ *
+ * const s1 = Stream.make("1", "2", "3").pipe(
+ *   Stream.schedule(Schedule.spaced("100 millis"))
+ * )
+ * const s2 = Stream.make(4.1, 5.3, 6.2).pipe(
+ *   Stream.schedule(Schedule.spaced("200 millis"))
+ * )
+ *
+ * const stream = Stream.mergeWith(s1, s2, {
+ *   onSelf: (s) => parseInt(s),
+ *   onOther: (n) => Math.floor(n)
+ * })
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 4, 2, 3, 5, 6 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -1317,6 +1958,17 @@ export const orElseSucceed = internal.orElseSucceed;
  * than the unfolding of the state. This is useful for embedding paginated
  * APIs, hence the name.
  *
+ * @example
+ * import { Effect, Option, Stream } from "effect"
+ *
+ * const stream = Stream.paginate(0, (n) => [
+ *   n,
+ *   n < 3 ? Option.some(n + 1) : Option.none()
+ * ])
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 0, 1, 2, 3 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -1354,6 +2006,25 @@ export const paginateEffect = internal.paginateEffect;
  * evaluated to false. The faster stream may advance by up to buffer elements
  * further than the slower one.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const partition = Stream.range(1, 10).pipe(
+ *   Stream.partition((n) => n % 2 === 0, { bufferSize: 5 })
+ * )
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function*() {
+ *     const [evens, odds] = yield* partition
+ *     console.log(yield* Stream.runCollect(evens))
+ *     console.log(yield* Stream.runCollect(odds))
+ *   })
+ * )
+ *
+ * // Effect.runPromise(program)
+ * // { _id: 'Chunk', values: [ 2, 4, 6, 8, 10 ] }
+ * // { _id: 'Chunk', values: [ 1, 3, 5, 7, 9 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -1362,6 +2033,28 @@ export const partition = internal.partition;
  * Split a stream by an effectful predicate. The faster stream may advance by
  * up to buffer elements further than the slower one.
  *
+ * @example
+ * import { Effect, Either, Stream } from "effect"
+ *
+ * const partition = Stream.range(1, 9).pipe(
+ *   Stream.partitionEither(
+ *     (n) => Effect.succeed(n % 2 === 0 ? Either.left(n) : Either.right(n)),
+ *     { bufferSize: 5 }
+ *   )
+ * )
+ *
+ * const program = Effect.scoped(
+ *   Effect.gen(function*() {
+ *     const [evens, odds] = yield* partition
+ *     console.log(yield* Stream.runCollect(evens))
+ *     console.log(yield* Stream.runCollect(odds))
+ *   })
+ * )
+ *
+ * // Effect.runPromise(program)
+ * // { _id: 'Chunk', values: [ 2, 4, 6, 8 ] }
+ * // { _id: 'Chunk', values: [ 1, 3, 5, 7, 9 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -1462,9 +2155,45 @@ export const mapInputContext = internal.mapInputContext;
  * @category context
  */
 export const provideSomeLayer = internal.provideSomeLayer;
+/**
+ * Returns a stream that mirrors the first upstream to emit an item.
+ * As soon as one of the upstream emits a first value, all the others are interrupted.
+ * The resulting stream will forward all items from the "winning" source stream.
+ * Any upstream failures will cause the returned stream to fail.
+ *
+ * @example
+ * import { Stream, Schedule, Console, Effect } from "effect"
+ *
+ * const stream = Stream.raceAll(
+ *   Stream.fromSchedule(Schedule.spaced('1 millis')),
+ *   Stream.fromSchedule(Schedule.spaced('2 millis')),
+ *   Stream.fromSchedule(Schedule.spaced('4 millis')),
+ * ).pipe(Stream.take(6), Stream.tap(Console.log))
+ *
+ * Effect.runPromise(Stream.runDrain(stream))
+ * // Output each millisecond from the first stream, the rest streams are interrupted
+ * // 0
+ * // 1
+ * // 2
+ * // 3
+ * // 4
+ * // 5
+ * @since 3.5.0
+ * @category racing
+ */
+export const raceAll = internal.raceAll;
 /**
  * Constructs a stream from a range of integers, including both endpoints.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * // A Stream with a range of numbers from 1 to 5
+ * const stream = Stream.range(1, 5)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2, 3, 4, 5 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -1496,6 +2225,14 @@ export const refineOrDieWith = internal.refineOrDieWith;
  * Repeats the entire stream using the specified schedule. The stream will
  * execute normally, and then repeat again according to the provided schedule.
  *
+ * @example
+ * import { Effect, Schedule, Stream } from "effect"
+ *
+ * const stream = Stream.repeat(Stream.succeed(1), Schedule.forever)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream.pipe(Stream.take(5)))).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 1, 1, 1, 1 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -1504,6 +2241,14 @@ export const repeat = internal.repeat;
  * Creates a stream from an effect producing a value of type `A` which repeats
  * forever.
  *
+ * @example
+ * import { Effect, Random, Stream } from "effect"
+ *
+ * const stream = Stream.repeatEffect(Random.nextInt)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream.pipe(Stream.take(5)))).then(console.log)
+ * // Example Output: { _id: 'Chunk', values: [ 3891571149, 4239494205, 2352981603, 2339111046, 1488052210 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -1528,6 +2273,22 @@ export const repeatEffectChunkOption = internal.repeatEffectChunkOption;
  * Creates a stream from an effect producing values of type `A` until it fails
  * with `None`.
  *
+ * @example
+ * // In this example, we're draining an Iterator to create a stream from it
+ * import { Stream, Effect, Option } from "effect"
+ *
+ * const drainIterator = <A>(it: Iterator<A>): Stream.Stream<A> =>
+ *   Stream.repeatEffectOption(
+ *     Effect.sync(() => it.next()).pipe(
+ *       Effect.andThen((res) => {
+ *         if (res.done) {
+ *           return Effect.fail(Option.none())
+ *         }
+ *         return Effect.succeed(res.value)
+ *       })
+ *     )
+ *   )
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -1579,6 +2340,14 @@ export const repeatElementsWith = internal.repeatElementsWith;
 /**
  * Repeats the provided value infinitely.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.repeatValue(0)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream.pipe(Stream.take(5)))).then(console.log)
+ * // { _id: 'Chunk', values: [ 0, 0, 0, 0, 0 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -1820,6 +2589,14 @@ export const runSum = internal.runSum;
  * Statefully maps over the elements of this stream to produce all
  * intermediate results of type `S` given an initial S.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.range(1, 6).pipe(Stream.scan(0, (a, b) => a + b))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 0,  1,  3, 6, 10, 15, 21 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -1871,6 +2648,24 @@ export const scheduleWith = internal.scheduleWith;
 /**
  * Creates a single-valued stream from a scoped resource.
  *
+ * @example
+ * import { Console, Effect, Stream } from "effect"
+ *
+ * // Creating a single-valued stream from a scoped resource
+ * const stream = Stream.scoped(
+ *   Effect.acquireUseRelease(
+ *     Console.log("acquire"),
+ *     () => Console.log("use"),
+ *     () => Console.log("release")
+ *   )
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // acquire
+ * // use
+ * // release
+ * // { _id: 'Chunk', values: [ undefined ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -1959,6 +2754,15 @@ export const splitLines = internal.splitLines;
 /**
  * Creates a single-valued pure stream.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * // A Stream with a single number
+ * const stream = Stream.succeed(3)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 3 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -1980,6 +2784,14 @@ export const suspend = internal.suspend;
 /**
  * Takes the specified number of elements from this stream.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.take(Stream.iterate(0, (n) => n + 1), 5)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 0, 1, 2, 3, 4 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -1987,6 +2799,14 @@ export const take = internal.take;
 /**
  * Takes the last specified number of elements from this stream.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.takeRight(Stream.make(1, 2, 3, 4, 5, 6), 3)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 4, 5, 6 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -1995,6 +2815,14 @@ export const takeRight = internal.takeRight;
  * Takes all elements of the stream until the specified predicate evaluates to
  * `true`.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.takeUntil(Stream.iterate(0, (n) => n + 1), (n) => n === 4)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 0, 1, 2, 3, 4 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -2011,6 +2839,14 @@ export const takeUntilEffect = internal.takeUntilEffect;
  * Takes all elements of the stream for as long as the specified predicate
  * evaluates to `true`.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.takeWhile(Stream.iterate(0, (n) => n + 1), (n) => n < 5)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ 0, 1, 2, 3, 4 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -2018,6 +2854,24 @@ export const takeWhile = internal.takeWhile;
 /**
  * Adds an effect to consumption of every element of the stream.
  *
+ * @example
+ * import { Console, Effect, Stream } from "effect"
+ *
+ * const stream = Stream.make(1, 2, 3).pipe(
+ *   Stream.tap((n) => Console.log(`before mapping: ${n}`)),
+ *   Stream.map((n) => n * 2),
+ *   Stream.tap((n) => Console.log(`after mapping: ${n}`))
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // before mapping: 1
+ * // after mapping: 2
+ * // before mapping: 2
+ * // after mapping: 4
+ * // before mapping: 3
+ * // after mapping: 6
+ * // { _id: 'Chunk', values: [ 2, 4, 6 ] }
+ *
  * @since 2.0.0
  * @category sequencing
  */
@@ -2058,7 +2912,7 @@ export const tapSink = internal.tapSink;
  * parameters using the token bucket algorithm. Allows for burst in the
  * processing of elements by allowing the token bucket to accumulate tokens up
  * to a `units + burst` threshold. The weight of each chunk is determined by
- * the `costFn` function.
+ * the `cost` function.
  *
  * If using the "enforce" strategy, chunks that do not meet the bandwidth
  * constraints are dropped. If using the "shape" strategy, chunks are delayed
@@ -2066,6 +2920,43 @@ export const tapSink = internal.tapSink;
  *
  * Defaults to the "shape" strategy.
  *
+ * @example
+ * import { Chunk, Effect, Schedule, Stream } from "effect"
+ *
+ * let last = Date.now()
+ * const log = (message: string) =>
+ *   Effect.sync(() => {
+ *     const end = Date.now()
+ *     console.log(`${message} after ${end - last}ms`)
+ *     last = end
+ *   })
+ *
+ * const stream = Stream.fromSchedule(Schedule.spaced("50 millis")).pipe(
+ *   Stream.take(6),
+ *   Stream.tap((n) => log(`Received ${n}`)),
+ *   Stream.throttle({
+ *     cost: Chunk.size,
+ *     duration: "100 millis",
+ *     units: 1
+ *   }),
+ *   Stream.tap((n) => log(`> Emitted ${n}`))
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // Received 0 after 56ms
+ * // > Emitted 0 after 0ms
+ * // Received 1 after 52ms
+ * // > Emitted 1 after 48ms
+ * // Received 2 after 52ms
+ * // > Emitted 2 after 49ms
+ * // Received 3 after 52ms
+ * // > Emitted 3 after 48ms
+ * // Received 4 after 52ms
+ * // > Emitted 4 after 47ms
+ * // Received 5 after 52ms
+ * // > Emitted 5 after 49ms
+ * // { _id: 'Chunk', values: [ 0, 1, 2, 3, 4, 5 ] }
+ *
  * @since 2.0.0
  * @category utils
  */
@@ -2090,6 +2981,27 @@ export const throttleEffect = internal.throttleEffect;
 /**
  * A stream that emits void values spaced by the specified duration.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * let last = Date.now()
+ * const log = (message: string) =>
+ *   Effect.sync(() => {
+ *     const end = Date.now()
+ *     console.log(`${message} after ${end - last}ms`)
+ *     last = end
+ *   })
+ *
+ * const stream = Stream.tick("1 seconds").pipe(Stream.tap(() => log("tick")))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream.pipe(Stream.take(5)))).then(console.log)
+ * // tick after 4ms
+ * // tick after 1003ms
+ * // tick after 1001ms
+ * // tick after 1002ms
+ * // tick after 1002ms
+ * // { _id: 'Chunk', values: [ undefined, undefined, undefined, undefined, undefined ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -2139,6 +3051,32 @@ export const toPubSub = internal.toPubSub;
  * finished, or with Some error if it fails, otherwise it returns a chunk of
  * the stream's output.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * // Simulate a chunked stream
+ * const stream = Stream.fromIterable([1, 2, 3, 4, 5]).pipe(Stream.rechunk(2))
+ *
+ * const program = Effect.gen(function*() {
+ *   // Create an effect to get data chunks from the stream
+ *   const getChunk = yield* Stream.toPull(stream)
+ *
+ *   // Continuously fetch and process chunks
+ *   while (true) {
+ *     const chunk = yield* getChunk
+ *     console.log(chunk)
+ *   }
+ * })
+ *
+ * // Effect.runPromise(Effect.scoped(program)).then(console.log, console.error)
+ * // { _id: 'Chunk', values: [ 1, 2 ] }
+ * // { _id: 'Chunk', values: [ 3, 4 ] }
+ * // { _id: 'Chunk', values: [ 5 ] }
+ * // (FiberFailure) Error: {
+ * //   "_id": "Option",
+ * //   "_tag": "None"
+ * // }
+ *
  * @since 2.0.0
  * @category destructors
  */
@@ -2200,6 +3138,14 @@ export const transduce = internal.transduce;
 /**
  * Creates a stream by peeling off the "layers" of a value of type `S`.
  *
+ * @example
+ * import { Effect, Option, Stream } from "effect"
+ *
+ * const stream = Stream.unfold(1, (n) => Option.some([n, n + 1]))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream.pipe(Stream.take(5)))).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, 2, 3, 4, 5 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -2223,6 +3169,17 @@ export const unfoldChunkEffect = internal.unfoldChunkEffect;
  * Creates a stream by effectfully peeling off the "layers" of a value of type
  * `S`.
  *
+ * @example
+ * import { Effect, Option, Random, Stream } from "effect"
+ *
+ * const stream = Stream.unfoldEffect(1, (n) =>
+ *   Random.nextBoolean.pipe(
+ *     Effect.map((b) => (b ? Option.some([n, -n]) : Option.some([n, n])))
+ *   ))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream.pipe(Stream.take(5)))).then(console.log)
+ * // { _id: 'Chunk', values: [ 1, -1, -1, -1, -1 ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -2232,6 +3189,14 @@ export {
 /**
  * A stream that contains a single `void` value.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.void
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ undefined ] }
+ *
  * @since 2.0.0
  * @category constructors
  */
@@ -2302,6 +3267,18 @@ export const withSpan = internal.withSpan;
  *
  * The new stream will end when one of the sides ends.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * // We create two streams and zip them together.
+ * const stream = Stream.zip(
+ *   Stream.make(1, 2, 3, 4, 5, 6),
+ *   Stream.make("a", "b", "c")
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ [ 1, 'a' ], [ 2, 'b' ], [ 3, 'c' ] ] }
+ *
  * @since 2.0.0
  * @category zipping
  */
@@ -2323,6 +3300,18 @@ export const zipFlatten = internal.zipFlatten;
  * The defaults `defaultLeft` and `defaultRight` will be used if the streams
  * have different lengths and one of the streams has ended before the other.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.zipAll(Stream.make(1, 2, 3, 4, 5, 6), {
+ *   other: Stream.make("a", "b", "c"),
+ *   defaultSelf: 0,
+ *   defaultOther: "x"
+ * })
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: "Chunk", values: [ [ 1, "a" ], [ 2, "b" ], [ 3, "c" ], [ 4, "x" ], [ 5, "x" ], [ 6, "x" ] ] }
+ *
  * @since 2.0.0
  * @category zipping
  */
@@ -2414,6 +3403,19 @@ export const zipAllSortedByKeyWith = internal.zipAllSortedByKeyWith;
  * The functions `left` and `right` will be used if the streams have different
  * lengths and one of the streams has ended before the other.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.zipAllWith(Stream.make(1, 2, 3, 4, 5, 6), {
+ *   other: Stream.make("a", "b", "c"),
+ *   onSelf: (n) => [n, "x"],
+ *   onOther: (s) => [0, s],
+ *   onBoth: (n, s) => [n - s.length, s]
+ * })
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: "Chunk", values: [ [ 0, "a" ], [ 1, "b" ], [ 2, "c" ], [ 4, "x" ], [ 5, "x" ], [ 6, "x" ] ] }
+ *
  * @since 2.0.0
  * @category zipping
  */
@@ -2427,6 +3429,22 @@ export const zipAllWith = internal.zipAllWith;
  * that emitted elements that are not the last value in chunks will never be
  * used for zipping.
  *
+ * @example
+ * import { Effect, Schedule, Stream } from "effect"
+ *
+ * const s1 = Stream.make(1, 2, 3).pipe(
+ *   Stream.schedule(Schedule.spaced("1 second"))
+ * )
+ *
+ * const s2 = Stream.make("a", "b", "c", "d").pipe(
+ *   Stream.schedule(Schedule.spaced("500 millis"))
+ * )
+ *
+ * const stream = Stream.zipLatest(s1, s2)
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: "Chunk", values: [ [ 1, "a" ], [ 1, "b" ], [ 2, "b" ], [ 2, "c" ], [ 2, "d" ], [ 3, "d" ] ] }
+ *
  * @since 2.0.0
  * @category zipping
  */
@@ -2448,7 +3466,7 @@ export const zipLatest = internal.zipLatest;
  *     Stream.fromSchedule(Schedule.spaced('4 millis')),
  * ).pipe(Stream.take(6), Stream.tap(Console.log))
  *
- * Effect.runPromise(Stream.runDrain(stream))
+ * // Effect.runPromise(Stream.runDrain(stream))
  * // Output:
  * // [ 0, 0, 0 ]
  * // [ 1, 0, 0 ]
@@ -2501,6 +3519,19 @@ export const zipRight = internal.zipRight;
  *
  * The new stream will end when one of the sides ends.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * // We create two streams and zip them with custom logic.
+ * const stream = Stream.zipWith(
+ *   Stream.make(1, 2, 3, 4, 5, 6),
+ *   Stream.make("a", "b", "c"),
+ *   (n, s) => [n - s.length, s]
+ * )
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then(console.log)
+ * // { _id: 'Chunk', values: [ [ 0, 'a' ], [ 1, 'b' ], [ 2, 'c' ] ] }
+ *
  * @since 2.0.0
  * @category zipping
  */
@@ -2518,6 +3549,19 @@ export const zipWithChunks = internal.zipWithChunks;
 /**
  * Zips each element with the next element if present.
  *
+ * @example
+ * import { Chunk, Effect, Stream } from "effect"
+ *
+ * const stream = Stream.zipWithNext(Stream.make(1, 2, 3, 4))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then((chunk) => console.log(Chunk.toArray(chunk)))
+ * // [
+ * //   [ 1, { _id: 'Option', _tag: 'Some', value: 2 } ],
+ * //   [ 2, { _id: 'Option', _tag: 'Some', value: 3 } ],
+ * //   [ 3, { _id: 'Option', _tag: 'Some', value: 4 } ],
+ * //   [ 4, { _id: 'Option', _tag: 'None' } ]
+ * // ]
+ *
  * @since 2.0.0
  * @category zipping
  */
@@ -2526,6 +3570,19 @@ export const zipWithNext = internal.zipWithNext;
  * Zips each element with the previous element. Initially accompanied by
  * `None`.
  *
+ * @example
+ * import { Chunk, Effect, Stream } from "effect"
+ *
+ * const stream = Stream.zipWithPrevious(Stream.make(1, 2, 3, 4))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then((chunk) => console.log(Chunk.toArray(chunk)))
+ * // [
+ * //   [ { _id: 'Option', _tag: 'None' }, 1 ],
+ * //   [ { _id: 'Option', _tag: 'Some', value: 1 }, 2 ],
+ * //   [ { _id: 'Option', _tag: 'Some', value: 2 }, 3 ],
+ * //   [ { _id: 'Option', _tag: 'Some', value: 3 }, 4 ]
+ * // ]
+ *
  * @since 2.0.0
  * @category zipping
  */
@@ -2533,6 +3590,35 @@ export const zipWithPrevious = internal.zipWithPrevious;
 /**
  * Zips each element with both the previous and next element.
  *
+ * @example
+ * import { Chunk, Effect, Stream } from "effect"
+ *
+ * const stream = Stream.zipWithPreviousAndNext(Stream.make(1, 2, 3, 4))
+ *
+ * // Effect.runPromise(Stream.runCollect(stream)).then((chunk) => console.log(Chunk.toArray(chunk)))
+ * // [
+ * //   [
+ * //     { _id: 'Option', _tag: 'None' },
+ * //     1,
+ * //     { _id: 'Option', _tag: 'Some', value: 2 }
+ * //   ],
+ * //   [
+ * //     { _id: 'Option', _tag: 'Some', value: 1 },
+ * //     2,
+ * //     { _id: 'Option', _tag: 'Some', value: 3 }
+ * //   ],
+ * //   [
+ * //     { _id: 'Option', _tag: 'Some', value: 2 },
+ * //     3,
+ * //     { _id: 'Option', _tag: 'Some', value: 4 }
+ * //   ],
+ * //   [
+ * //     { _id: 'Option', _tag: 'Some', value: 3 },
+ * //     4,
+ * //     { _id: 'Option', _tag: 'None' }
+ * //   ]
+ * // ]
+ *
  * @since 2.0.0
  * @category zipping
  */
@@ -2540,6 +3626,19 @@ export const zipWithPreviousAndNext = internal.zipWithPreviousAndNext;
 /**
  * Zips this stream together with the index of elements.
  *
+ * @example
+ * import { Effect, Stream } from "effect"
+ *
+ * const stream = Stream.make("Mary", "James", "Robert", "Patricia")
+ *
+ * const indexedStream = Stream.zipWithIndex(stream)
+ *
+ * // Effect.runPromise(Stream.runCollect(indexedStream)).then(console.log)
+ * // {
+ * //   _id: 'Chunk',
+ * //   values: [ [ 'Mary', 0 ], [ 'James', 1 ], [ 'Robert', 2 ], [ 'Patricia', 3 ] ]
+ * // }
+ *
  * @since 2.0.0
  * @category zipping
  */