effect 3.4.8 → 3.5.0

package/src/Stream.ts

@@ -30,7 +30,7 @@ import type * as Emit from "./StreamEmit.js"
 import type * as HaltStrategy from "./StreamHaltStrategy.js"
 import type * as Take from "./Take.js"
 import type * as Tracer from "./Tracer.js"
-import type { Covariant, NoInfer } from "./Types.js"
+import type { Covariant, NoInfer, TupleOf } from "./Types.js"
 import type * as Unify from "./Unify.js"
 
 /**
@@ -146,6 +146,7 @@ export declare namespace Stream {
   /**
    * @since 2.0.0
    * @category models
+   * @deprecated use Types.TupleOf instead
    */
   export type DynamicTuple<T, N extends number> = N extends N ? number extends N ? Array<T> : DynamicTupleOf<T, N, []>
     : never
@@ -153,6 +154,7 @@ export declare namespace Stream {
   /**
    * @since 2.0.0
    * @category models
+   * @deprecated use Types.TupleOf instead
    */
   export type DynamicTupleOf<T, N extends number, R extends Array<unknown>> = R["length"] extends N ? R
     : DynamicTupleOf<T, N, [T, ...R]>
@@ -188,6 +190,29 @@ export const accumulateChunks: <A, E, R>(self: Stream<A, E, R>) => Stream<A, E,
  * 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
  */
@@ -269,6 +294,14 @@ export const 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
  */
@@ -279,7 +312,10 @@ export const as: {
 
 const _async: <A, E = never, R = never>(
   register: (emit: Emit.Emit<R, E, A, void>) => Effect.Effect<void, never, R> | void,
-  outputBuffer?: number
+  bufferSize?: number | "unbounded" | {
+    readonly bufferSize?: number | undefined
+    readonly strategy?: "dropping" | "sliding" | "suspend" | undefined
+  } | undefined
 ) => Stream<A, E, R> = internal._async
 
 export {
@@ -291,6 +327,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
    */
@@ -308,7 +367,10 @@ export {
  */
 export const asyncEffect: <A, E = never, R = never>(
   register: (emit: Emit.Emit<R, E, A, void>) => Effect.Effect<unknown, E, R>,
-  outputBuffer?: number
+  bufferSize?: number | "unbounded" | {
+    readonly bufferSize?: number | undefined
+    readonly strategy?: "dropping" | "sliding" | "suspend" | undefined
+  } | undefined
 ) => Stream<A, E, R> = internal.asyncEffect
 
 /**
@@ -322,7 +384,10 @@ export const asyncEffect: <A, E = never, R = never>(
  */
 export const asyncScoped: <A, E = never, R = never>(
   register: (emit: Emit.Emit<R, E, A, void>) => Effect.Effect<unknown, E, R | Scope.Scope>,
-  outputBuffer?: number
+  bufferSize?: number | "unbounded" | {
+    readonly bufferSize?: number | undefined
+    readonly strategy?: "dropping" | "sliding" | "suspend" | undefined
+  } | undefined
 ) => Stream<A, E, Exclude<R, Scope.Scope>> = internal.asyncScoped
 
 /**
@@ -350,6 +415,77 @@ export const 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
  */
@@ -359,12 +495,12 @@ export const broadcast: {
     maximumLag: number
   ): <A, E, R>(
     self: Stream<A, E, R>
-  ) => Effect.Effect<Stream.DynamicTuple<Stream<A, E>, N>, never, Scope.Scope | R>
+  ) => Effect.Effect<TupleOf<N, Stream<A, E>>, never, Scope.Scope | R>
   <A, E, R, N extends number>(
     self: Stream<A, E, R>,
     n: N,
     maximumLag: number
-  ): Effect.Effect<Stream.DynamicTuple<Stream<A, E>, N>, never, Scope.Scope | R>
+  ): Effect.Effect<TupleOf<N, Stream<A, E>>, never, Scope.Scope | R>
 } = internal.broadcast
 
 /**
@@ -396,12 +532,12 @@ export const broadcastedQueues: {
     maximumLag: number
   ): <A, E, R>(
     self: Stream<A, E, R>
-  ) => Effect.Effect<Stream.DynamicTuple<Queue.Dequeue<Take.Take<A, E>>, N>, never, R | Scope.Scope>
+  ) => Effect.Effect<TupleOf<N, Queue.Dequeue<Take.Take<A, E>>>, never, R | Scope.Scope>
   <A, E, R, N extends number>(
     self: Stream<A, E, R>,
     n: N,
     maximumLag: number
-  ): Effect.Effect<Stream.DynamicTuple<Queue.Dequeue<Take.Take<A, E>>, N>, never, Scope.Scope | R>
+  ): Effect.Effect<TupleOf<N, Queue.Dequeue<Take.Take<A, E>>>, never, Scope.Scope | R>
 } = internal.broadcastedQueues
 
 /**
@@ -430,9 +566,38 @@ export const 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
  */
@@ -618,6 +783,14 @@ export const 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
  */
@@ -749,6 +922,17 @@ export const 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
  */
@@ -760,6 +944,24 @@ export const 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
  */
@@ -772,6 +974,22 @@ export const concatAll: <A, E, R>(streams: Chunk.Chunk<Stream<A, E, R>>) => Stre
  *
  * 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
  */
@@ -844,6 +1062,45 @@ export const 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
  */
@@ -893,7 +1150,7 @@ export const distributedWith: {
     }
   ): <E, R>(
     self: Stream<A, E, R>
-  ) => Effect.Effect<Stream.DynamicTuple<Queue.Dequeue<Exit.Exit<A, Option.Option<E>>>, N>, never, Scope.Scope | R>
+  ) => Effect.Effect<TupleOf<N, Queue.Dequeue<Exit.Exit<A, Option.Option<E>>>>, never, Scope.Scope | R>
   <A, E, R, N extends number>(
     self: Stream<A, E, R>,
     options: {
@@ -901,7 +1158,7 @@ export const distributedWith: {
       readonly maximumLag: number
       readonly decide: (a: A) => Effect.Effect<Predicate<number>>
     }
-  ): Effect.Effect<Stream.DynamicTuple<Queue.Dequeue<Exit.Exit<A, Option.Option<E>>>, N>, never, Scope.Scope | R>
+  ): Effect.Effect<TupleOf<N, Queue.Dequeue<Exit.Exit<A, Option.Option<E>>>>, never, Scope.Scope | R>
 } = internal.distributedWith
 
 /**
@@ -939,6 +1196,15 @@ export const 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
  */
@@ -1054,6 +1320,14 @@ export const either: <A, E, R>(self: Stream<A, E, R>) => Stream<Either.Either<A,
 /**
  * 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
  */
@@ -1062,6 +1336,22 @@ export const empty: Stream<never> = 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
  */
@@ -1133,6 +1423,18 @@ export const execute: <X, E, R>(effect: Effect.Effect<X, E, R>) => Stream<never,
 /**
  * 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
  */
@@ -1165,6 +1467,14 @@ export const failCauseSync: <E>(evaluate: LazyArg<Cause.Cause<E>>) => Stream<nev
 /**
  * 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
  */
@@ -1248,6 +1558,29 @@ export const 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
  */
@@ -1408,6 +1741,22 @@ export const forever: <A, E, R>(self: Stream<A, E, R>) => Stream<A, E, R> = inte
 /**
  * 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
  */
@@ -1437,6 +1786,15 @@ export const toChannel: <A, E, R>(
 /**
  * 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
  */
@@ -1477,6 +1835,15 @@ export const fromChunkQueue: <A>(
 /**
  * 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
  */
@@ -1486,6 +1853,14 @@ export const fromChunks: <A>(...chunks: Array<Chunk.Chunk<A>>) => Stream<A> = in
  * 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
  */
@@ -1530,6 +1905,16 @@ export const 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
  */
@@ -1538,6 +1923,23 @@ export const fromIterable: <A>(iterable: Iterable<A>) => Stream<A> = internal.fr
 /**
  * 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
  */
@@ -1614,6 +2016,19 @@ export const fromReadableStreamByob: <E>(
  * 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
  */
@@ -1635,6 +2050,35 @@ export const 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
  */
@@ -1706,6 +2150,22 @@ export const 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
  */
@@ -1718,6 +2178,43 @@ export const 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
  */
@@ -1789,6 +2286,16 @@ export const identity: <A, E = never, R = never>() => Stream<A, E, R> = internal
  * 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
  */
@@ -1806,6 +2313,25 @@ export const 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
  */
@@ -1824,6 +2350,20 @@ export const 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
  */
@@ -1835,6 +2375,27 @@ export const 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
  */
@@ -1896,6 +2457,15 @@ export const 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
  */
@@ -1904,6 +2474,14 @@ export const iterate: <A>(value: A, next: (value: A) => A) => Stream<A> = intern
 /**
  * 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
  */
@@ -1912,6 +2490,14 @@ export const make: <As extends Array<any>>(...as: As) => Stream<As[number]> = in
 /**
  * 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
  */
@@ -1923,6 +2509,18 @@ export const 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
  */
@@ -1998,6 +2596,17 @@ export const 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
  */
@@ -2055,6 +2664,16 @@ export const 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
  */
@@ -2111,6 +2730,21 @@ export const 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
  */
@@ -2157,6 +2791,24 @@ export const 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
  */
@@ -2202,8 +2854,8 @@ export const mergeEither: {
  * @category utils
  */
 export const mergeLeft: {
-  <A2, E2, R2>(that: Stream<A2, E2, R2>): <A, E, R>(self: Stream<A, E, R>) => Stream<A, E2 | E, R2 | R>
-  <A, E, R, A2, E2, R2>(self: Stream<A, E, R>, that: Stream<A2, E2, R2>): Stream<A, E | E2, R | R2>
+  <AR, ER, RR>(right: Stream<AR, ER, RR>): <AL, EL, RL>(left: Stream<AL, EL, RL>) => Stream<AL, ER | EL, RR | RL>
+  <AL, EL, RL, AR, ER, RR>(left: Stream<AL, EL, RL>, right: Stream<AR, ER, RR>): Stream<AL, EL | ER, RL | RR>
 } = internal.mergeLeft
 
 /**
@@ -2214,8 +2866,8 @@ export const mergeLeft: {
  * @category utils
  */
 export const mergeRight: {
-  <A2, E2, R2>(that: Stream<A2, E2, R2>): <A, E, R>(self: Stream<A, E, R>) => Stream<A2, E2 | E, R2 | R>
-  <A, E, R, A2, E2, R2>(self: Stream<A, E, R>, that: Stream<A2, E2, R2>): Stream<A2, E | E2, R | R2>
+  <AR, ER, RR>(right: Stream<AR, ER, RR>): <AL, EL, RL>(left: Stream<AL, EL, RL>) => Stream<AR, ER | EL, RR | RL>
+  <AL, EL, RL, AR, ER, RR>(left: Stream<AL, EL, RL>, right: Stream<AR, ER, RR>): Stream<AR, EL | ER, RL | RR>
 } = internal.mergeRight
 
 /**
@@ -2380,6 +3032,17 @@ export const 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
  */
@@ -2430,6 +3093,25 @@ export const paginateEffect: <S, A, E, R>(
  * 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
  */
@@ -2462,6 +3144,28 @@ export const 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
  */
@@ -2664,9 +3368,52 @@ export const provideSomeLayer: {
   ): Stream<A, E | E2, RIn | Exclude<R, ROut>>
 } = 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: <S extends ReadonlyArray<Stream<any, any, any>>>(
+  ...streams: S
+) => Stream<
+  Stream.Success<S[number]>,
+  Stream.Error<S[number]>,
+  Stream.Context<S[number]>
+> = 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
  */
@@ -2714,6 +3461,14 @@ export const 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
  */
@@ -2726,6 +3481,14 @@ export const 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
  */
@@ -2756,6 +3519,22 @@ export const repeatEffectChunkOption: <A, E, R>(
  * 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
  */
@@ -2837,6 +3616,14 @@ export const 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
  */
@@ -2896,7 +3683,7 @@ export const run: {
   <A, E, R, A2, E2, R2>(
     self: Stream<A, E, R>,
     sink: Sink.Sink<A2, A, unknown, E2, R2>
-  ): Effect.Effect<A2, E | E2, R | R2>
+  ): Effect.Effect<A2, E | E2, Exclude<R | R2, Scope.Scope>>
 } = internal.run
 
 /**
@@ -2905,7 +3692,8 @@ export const run: {
  * @since 2.0.0
  * @category destructors
  */
-export const runCollect: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<Chunk.Chunk<A>, E, R> = internal.runCollect
+export const runCollect: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<Chunk.Chunk<A>, E, Exclude<R, Scope.Scope>> =
+  internal.runCollect
 
 /**
  * Runs the stream and emits the number of elements processed
@@ -2913,7 +3701,8 @@ export const runCollect: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<Chunk
  * @since 2.0.0
  * @category destructors
  */
-export const runCount: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<number, E, R> = internal.runCount
+export const runCount: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<number, E, Exclude<R, Scope.Scope>> =
+  internal.runCount
 
 /**
  * Runs the stream only for its effects. The emitted elements are discarded.
@@ -2921,7 +3710,8 @@ export const runCount: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<number,
  * @since 2.0.0
  * @category destructors
  */
-export const runDrain: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<void, E, R> = internal.runDrain
+export const runDrain: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<void, E, Exclude<R, Scope.Scope>> =
+  internal.runDrain
 
 /**
  * Executes a pure fold over the stream of values - reduces all elements in
@@ -2931,8 +3721,8 @@ export const runDrain: <A, E, R>(self: Stream<A, E, R>) => Effect.Effect<void, E
  * @category destructors
  */
 export const runFold: {
-  <S, A>(s: S, f: (s: S, a: A) => S): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E, R>
-  <A, E, R, S>(self: Stream<A, E, R>, s: S, f: (s: S, a: A) => S): Effect.Effect<S, E, R>
+  <S, A>(s: S, f: (s: S, a: A) => S): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E, Exclude<R, Scope.Scope>>
+  <A, E, R, S>(self: Stream<A, E, R>, s: S, f: (s: S, a: A) => S): Effect.Effect<S, E, Exclude<R, Scope.Scope>>
 } = internal.runFold
 
 /**
@@ -2945,12 +3735,12 @@ export const runFoldEffect: {
   <S, A, E2, R2>(
     s: S,
     f: (s: S, a: A) => Effect.Effect<S, E2, R2>
-  ): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E2 | E, R2 | R>
+  ): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E2 | E, Exclude<R | R2, Scope.Scope>>
   <A, E, R, S, E2, R2>(
     self: Stream<A, E, R>,
     s: S,
     f: (s: S, a: A) => Effect.Effect<S, E2, R2>
-  ): Effect.Effect<S, E | E2, R | R2>
+  ): Effect.Effect<S, E | E2, Exclude<R | R2, Scope.Scope>>
 } = internal.runFoldEffect
 
 /**
@@ -2992,8 +3782,17 @@ export const runFoldScopedEffect: {
  * @category destructors
  */
 export const runFoldWhile: {
-  <S, A>(s: S, cont: Predicate<S>, f: (s: S, a: A) => S): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E, R>
-  <A, E, R, S>(self: Stream<A, E, R>, s: S, cont: Predicate<S>, f: (s: S, a: A) => S): Effect.Effect<S, E, R>
+  <S, A>(
+    s: S,
+    cont: Predicate<S>,
+    f: (s: S, a: A) => S
+  ): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E, Exclude<R, Scope.Scope>>
+  <A, E, R, S>(
+    self: Stream<A, E, R>,
+    s: S,
+    cont: Predicate<S>,
+    f: (s: S, a: A) => S
+  ): Effect.Effect<S, E, Exclude<R, Scope.Scope>>
 } = internal.runFoldWhile
 
 /**
@@ -3008,13 +3807,13 @@ export const runFoldWhileEffect: {
     s: S,
     cont: Predicate<S>,
     f: (s: S, a: A) => Effect.Effect<S, E2, R2>
-  ): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E2 | E, R2 | R>
+  ): <E, R>(self: Stream<A, E, R>) => Effect.Effect<S, E2 | E, Exclude<R | R2, Scope.Scope>>
   <A, E, R, S, E2, R2>(
     self: Stream<A, E, R>,
     s: S,
     cont: Predicate<S>,
     f: (s: S, a: A) => Effect.Effect<S, E2, R2>
-  ): Effect.Effect<S, E | E2, R | R2>
+  ): Effect.Effect<S, E | E2, Exclude<R | R2, Scope.Scope>>
 } = internal.runFoldWhileEffect
 
 /**
@@ -3276,6 +4075,14 @@ export const runSum: <E, R>(self: Stream<number, E, R>) => Effect.Effect<number,
  * 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
  */
@@ -3372,6 +4179,24 @@ export const 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
  */
@@ -3488,6 +4313,15 @@ export const splitLines: <E, R>(self: Stream<string, E, R>) => Stream<string, E,
 /**
  * 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
  */
@@ -3512,6 +4346,14 @@ export const suspend: <A, E, R>(stream: LazyArg<Stream<A, E, R>>) => Stream<A, E
 /**
  * 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
  */
@@ -3523,6 +4365,14 @@ export const 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
  */
@@ -3535,6 +4385,14 @@ export const 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
  */
@@ -3564,6 +4422,14 @@ export const 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
  */
@@ -3577,6 +4443,24 @@ export const 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
  */
@@ -3657,7 +4541,7 @@ export const 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
@@ -3665,6 +4549,43 @@ export const 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
  */
@@ -3731,6 +4652,27 @@ export const 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
  */
@@ -3820,6 +4762,32 @@ export const 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
  */
@@ -3947,6 +4915,14 @@ export const 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
  */
@@ -3979,6 +4955,17 @@ export const unfoldChunkEffect: <S, A, E, R>(
  * 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
  */
@@ -3992,6 +4979,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
    */
@@ -4112,6 +5107,18 @@ export const 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
  */
@@ -4146,6 +5153,18 @@ export const 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
  */
@@ -4331,6 +5350,19 @@ export const 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
  */
@@ -4363,6 +5395,22 @@ export const 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
  */
@@ -4388,7 +5436,7 @@ export const 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 ]
@@ -4468,6 +5516,19 @@ export const 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
  */
@@ -4513,6 +5574,19 @@ export const 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
  */
@@ -4522,6 +5596,19 @@ export const zipWithNext: <A, E, R>(self: Stream<A, E, R>) => Stream<[A, Option.
  * 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
  */
@@ -4531,6 +5618,35 @@ export const zipWithPrevious: <A, E, R>(self: Stream<A, E, R>) => Stream<[Option
 /**
  * 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
  */
@@ -4541,6 +5657,19 @@ export const zipWithPreviousAndNext: <A, E, R>(
 /**
  * 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
  */