From 51a44fc1c6aa93d6787bb022b3fc7054a8036a08 Mon Sep 17 00:00:00 2001
From: bowzee <dilame.bowzee@gmail.com>
Date: Thu, 4 Jul 2024 07:51:16 +0300
Subject: [PATCH] refactor(Stream/raceAll): improve documentation

---
 .changeset/stream-race-all.md | 25 ++++++++++++++++++++++++-
 packages/effect/src/Stream.ts |  6 +++++-
 2 files changed, 29 insertions(+), 2 deletions(-)

diff --git a/.changeset/stream-race-all.md b/.changeset/stream-race-all.md
index 2a37d55202..f31c5920d0 100644
--- a/.changeset/stream-race-all.md
+++ b/.changeset/stream-race-all.md
@@ -2,4 +2,27 @@
 "effect": minor
 ---
 
-feat(Stream): raceAll
\ No newline at end of file
+feat(Stream): implement "raceAll" operator, which returns a stream that mirrors the first source stream to emit an item.
+
+
+```ts
+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 only from the first stream, the rest streams are interrupted
+// 0 
+// 1 
+// 2 
+// 3 
+// 4 
+// 5
+```
\ No newline at end of file
diff --git a/packages/effect/src/Stream.ts b/packages/effect/src/Stream.ts
index 991b15d1a4..81334ba15f 100644
--- a/packages/effect/src/Stream.ts
+++ b/packages/effect/src/Stream.ts
@@ -2695,7 +2695,11 @@ export const provideSomeLayer: {
 } = internal.provideSomeLayer
 
 /**
- * Returns a stream that mirrors the first source stream to emit an item.
+ * 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 being 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"
  *