effect 3.4.8 → 3.5.0

package/dist/cjs/Stream.js

@@ -4,35 +4,12 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.fromIteratorSucceed = exports.fromIterableEffect = exports.fromIterable = exports.fromEventListener = exports.fromEffectOption = exports.fromEffect = exports.fromChunks = exports.fromChunkQueue = exports.fromChunkPubSub = exports.fromChunk = exports.fromChannel = exports.fromAsyncIterable = exports.forever = exports.flattenTake = exports.flattenIterables = exports.flattenExitOption = exports.flattenEffect = exports.flattenChunks = exports.flatten = exports.flatMap = exports.findEffect = exports.find = exports.finalizer = exports.filterMapWhileEffect = exports.filterMapWhile = exports.filterMapEffect = exports.filterMap = exports.filterEffect = exports.filter = exports.failSync = exports.failCauseSync = exports.failCause = exports.fail = exports.execute = exports.ensuringWith = exports.ensuring = exports.encodeText = exports.empty = exports.either = exports.dropWhileEffect = exports.dropWhile = exports.dropUntilEffect = exports.dropUntil = exports.dropRight = exports.drop = exports.drainFork = exports.drain = exports.distributedWithDynamic = exports.distributedWith = exports.dieSync = exports.dieMessage = exports.die = exports.decodeText = exports.debounce = exports.crossWith = exports.crossRight = exports.crossLeft = exports.cross = exports.contextWithStream = exports.contextWithEffect = exports.contextWith = exports.context = exports.concatAll = exports.concat = exports.combineChunks = exports.combine = exports.chunksWith = exports.chunks = exports.changesWithEffect = exports.changesWith = exports.changes = exports.catchTags = exports.catchTag = exports.catchSomeCause = exports.catchSome = exports.catchAllCause = exports.catchAll = exports.bufferChunks = exports.buffer = exports.broadcastedQueuesDynamic = exports.broadcastedQueues = exports.broadcastDynamic = exports.broadcast = exports.branchAfter = exports.bindTo = exports.bindEffect = exports.bind = exports.asyncScoped = exports.asyncEffect = exports.async = exports.as = exports.aggregateWithinEither = exports.aggregateWithin = exports.aggregate = exports.acquireRelease = exports.accumulateChunks = exports.accumulate = exports.StreamTypeId = exports.Do = exports.DefaultChunkSize = void 0;
-exports.runFoldWhile = exports.runFoldScopedEffect = exports.runFoldScoped = exports.runFoldEffect = exports.runFold = exports.runDrain = exports.runCount = exports.runCollect = exports.run = exports.retry = exports.repeatWith = exports.repeatValue = exports.repeatElementsWith = exports.repeatElements = exports.repeatEither = exports.repeatEffectWithSchedule = exports.repeatEffectOption = exports.repeatEffectChunkOption = exports.repeatEffectChunk = exports.repeatEffect = exports.repeat = exports.refineOrDieWith = exports.refineOrDie = exports.rechunk = exports.range = exports.provideSomeLayer = exports.provideServiceStream = exports.provideServiceEffect = exports.provideService = exports.provideLayer = exports.provideContext = exports.prepend = exports.pipeThroughChannelOrFail = exports.pipeThroughChannel = exports.pipeThrough = exports.peel = exports.partitionEither = exports.partition = exports.paginateEffect = exports.paginateChunkEffect = exports.paginateChunk = exports.paginate = exports.orElseSucceed = exports.orElseIfEmptyStream = exports.orElseIfEmptyChunk = exports.orElseIfEmpty = exports.orElseFail = exports.orElseEither = exports.orElse = exports.orDieWith = exports.orDie = exports.onError = exports.onDone = exports.never = exports.mkString = exports.mergeWith = exports.mergeRight = exports.mergeLeft = exports.mergeEither = exports.mergeAll = exports.merge = exports.mapInputContext = exports.mapErrorCause = exports.mapError = exports.mapEffect = exports.mapConcatEffect = exports.mapConcatChunkEffect = exports.mapConcatChunk = exports.mapConcat = exports.mapChunksEffect = exports.mapChunks = exports.mapBoth = exports.mapAccumEffect = exports.mapAccum = exports.map = exports.make = exports.let = exports.iterate = exports.intersperseAffixes = exports.intersperse = exports.interruptWhenDeferred = exports.interruptWhen = exports.interruptAfter = exports.interleaveWith = exports.interleave = exports.identity = exports.haltWhenDeferred = exports.haltWhen = exports.haltAfter = exports.groupedWithin = exports.grouped = exports.groupByKey = exports.groupBy = exports.groupAdjacentBy = exports.fromSchedule = exports.fromReadableStreamByob = exports.fromReadableStream = exports.fromQueue = exports.fromPull = exports.fromPubSub = void 0;
-exports.zipWithPreviousAndNext = exports.zipWithPrevious = exports.zipWithNext = exports.zipWithIndex = exports.zipWithChunks = exports.zipWith = exports.zipRight = exports.zipLeft = exports.zipLatestWith = exports.zipLatestAll = exports.zipLatest = exports.zipFlatten = exports.zipAllWith = exports.zipAllSortedByKeyWith = exports.zipAllSortedByKeyRight = exports.zipAllSortedByKeyLeft = exports.zipAllSortedByKey = exports.zipAllRight = exports.zipAllLeft = exports.zipAll = exports.zip = exports.withSpan = exports.whenEffect = exports.whenCaseEffect = exports.whenCase = exports.when = exports.void = exports.updateService = exports.unwrapScoped = exports.unwrap = exports.unfoldEffect = exports.unfoldChunkEffect = exports.unfoldChunk = exports.unfold = exports.transduce = exports.toReadableStreamRuntime = exports.toReadableStreamEffect = exports.toReadableStream = exports.toQueueOfElements = exports.toQueue = exports.toPull = exports.toPubSub = exports.toChannel = exports.timeoutTo = exports.timeoutFailCause = exports.timeoutFail = exports.timeout = exports.tick = exports.throttleEffect = exports.throttle = exports.tapSink = exports.tapErrorCause = exports.tapError = exports.tapBoth = exports.tap = exports.takeWhile = exports.takeUntilEffect = exports.takeUntil = exports.takeRight = exports.take = exports.sync = exports.suspend = exports.succeed = exports.splitOnChunk = exports.splitLines = exports.split = exports.someOrFail = exports.someOrElse = exports.some = exports.slidingSize = exports.sliding = exports.scoped = exports.scheduleWith = exports.schedule = exports.scanReduceEffect = exports.scanReduce = exports.scanEffect = exports.scan = exports.runSum = exports.runScoped = exports.runLast = exports.runIntoQueueScoped = exports.runIntoQueueElementsScoped = exports.runIntoQueue = exports.runIntoPubSubScoped = exports.runIntoPubSub = exports.runHead = exports.runForEachWhileScoped = exports.runForEachWhile = exports.runForEachScoped = exports.runForEachChunkScoped = exports.runForEachChunk = exports.runForEach = exports.runFoldWhileScopedEffect = exports.runFoldWhileScoped = exports.runFoldWhileEffect = void 0;
-var _groupBy = /*#__PURE__*/_interopRequireWildcard( /*#__PURE__*/require("./internal/groupBy.js"));
-var internal = /*#__PURE__*/_interopRequireWildcard( /*#__PURE__*/require("./internal/stream.js"));
-function _getRequireWildcardCache(e) {
-  if ("function" != typeof WeakMap) return null;
-  var r = new WeakMap(),
-    t = new WeakMap();
-  return (_getRequireWildcardCache = function (e) {
-    return e ? t : r;
-  })(e);
-}
-function _interopRequireWildcard(e, r) {
-  if (!r && e && e.__esModule) return e;
-  if (null === e || "object" != typeof e && "function" != typeof e) return {
-    default: e
-  };
-  var t = _getRequireWildcardCache(r);
-  if (t && t.has(e)) return t.get(e);
-  var n = {
-      __proto__: null
-    },
-    a = Object.defineProperty && Object.getOwnPropertyDescriptor;
-  for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) {
-    var i = a ? Object.getOwnPropertyDescriptor(e, u) : null;
-    i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u];
-  }
-  return n.default = e, t && t.set(e, n), n;
-}
+exports.runFoldScopedEffect = exports.runFoldScoped = exports.runFoldEffect = exports.runFold = exports.runDrain = exports.runCount = exports.runCollect = exports.run = exports.retry = exports.repeatWith = exports.repeatValue = exports.repeatElementsWith = exports.repeatElements = exports.repeatEither = exports.repeatEffectWithSchedule = exports.repeatEffectOption = exports.repeatEffectChunkOption = exports.repeatEffectChunk = exports.repeatEffect = exports.repeat = exports.refineOrDieWith = exports.refineOrDie = exports.rechunk = exports.range = exports.raceAll = exports.provideSomeLayer = exports.provideServiceStream = exports.provideServiceEffect = exports.provideService = exports.provideLayer = exports.provideContext = exports.prepend = exports.pipeThroughChannelOrFail = exports.pipeThroughChannel = exports.pipeThrough = exports.peel = exports.partitionEither = exports.partition = exports.paginateEffect = exports.paginateChunkEffect = exports.paginateChunk = exports.paginate = exports.orElseSucceed = exports.orElseIfEmptyStream = exports.orElseIfEmptyChunk = exports.orElseIfEmpty = exports.orElseFail = exports.orElseEither = exports.orElse = exports.orDieWith = exports.orDie = exports.onError = exports.onDone = exports.never = exports.mkString = exports.mergeWith = exports.mergeRight = exports.mergeLeft = exports.mergeEither = exports.mergeAll = exports.merge = exports.mapInputContext = exports.mapErrorCause = exports.mapError = exports.mapEffect = exports.mapConcatEffect = exports.mapConcatChunkEffect = exports.mapConcatChunk = exports.mapConcat = exports.mapChunksEffect = exports.mapChunks = exports.mapBoth = exports.mapAccumEffect = exports.mapAccum = exports.map = exports.make = exports.let = exports.iterate = exports.intersperseAffixes = exports.intersperse = exports.interruptWhenDeferred = exports.interruptWhen = exports.interruptAfter = exports.interleaveWith = exports.interleave = exports.identity = exports.haltWhenDeferred = exports.haltWhen = exports.haltAfter = exports.groupedWithin = exports.grouped = exports.groupByKey = exports.groupBy = exports.groupAdjacentBy = exports.fromSchedule = exports.fromReadableStreamByob = exports.fromReadableStream = exports.fromQueue = exports.fromPull = exports.fromPubSub = void 0;
+exports.zipWithPreviousAndNext = exports.zipWithPrevious = exports.zipWithNext = exports.zipWithIndex = exports.zipWithChunks = exports.zipWith = exports.zipRight = exports.zipLeft = exports.zipLatestWith = exports.zipLatestAll = exports.zipLatest = exports.zipFlatten = exports.zipAllWith = exports.zipAllSortedByKeyWith = exports.zipAllSortedByKeyRight = exports.zipAllSortedByKeyLeft = exports.zipAllSortedByKey = exports.zipAllRight = exports.zipAllLeft = exports.zipAll = exports.zip = exports.withSpan = exports.whenEffect = exports.whenCaseEffect = exports.whenCase = exports.when = exports.void = exports.updateService = exports.unwrapScoped = exports.unwrap = exports.unfoldEffect = exports.unfoldChunkEffect = exports.unfoldChunk = exports.unfold = exports.transduce = exports.toReadableStreamRuntime = exports.toReadableStreamEffect = exports.toReadableStream = exports.toQueueOfElements = exports.toQueue = exports.toPull = exports.toPubSub = exports.toChannel = exports.timeoutTo = exports.timeoutFailCause = exports.timeoutFail = exports.timeout = exports.tick = exports.throttleEffect = exports.throttle = exports.tapSink = exports.tapErrorCause = exports.tapError = exports.tapBoth = exports.tap = exports.takeWhile = exports.takeUntilEffect = exports.takeUntil = exports.takeRight = exports.take = exports.sync = exports.suspend = exports.succeed = exports.splitOnChunk = exports.splitLines = exports.split = exports.someOrFail = exports.someOrElse = exports.some = exports.slidingSize = exports.sliding = exports.scoped = exports.scheduleWith = exports.schedule = exports.scanReduceEffect = exports.scanReduce = exports.scanEffect = exports.scan = exports.runSum = exports.runScoped = exports.runLast = exports.runIntoQueueScoped = exports.runIntoQueueElementsScoped = exports.runIntoQueue = exports.runIntoPubSubScoped = exports.runIntoPubSub = exports.runHead = exports.runForEachWhileScoped = exports.runForEachWhile = exports.runForEachScoped = exports.runForEachChunkScoped = exports.runForEachChunk = exports.runForEach = exports.runFoldWhileScopedEffect = exports.runFoldWhileScoped = exports.runFoldWhileEffect = exports.runFoldWhile = void 0;
+var _groupBy = _interopRequireWildcard(require("./internal/groupBy.js"));
+var internal = _interopRequireWildcard(require("./internal/stream.js"));
+function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
+function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
 /**
  * @since 2.0.0
  * @category symbols
@@ -65,6 +42,29 @@ const accumulateChunks = exports.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
  */
@@ -116,6 +116,14 @@ const aggregateWithinEither = exports.aggregateWithinEither = internal.aggregate
 /**
  * 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
  */
@@ -155,6 +163,77 @@ const branchAfter = exports.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
  */
@@ -194,9 +273,38 @@ const broadcastedQueuesDynamic = exports.broadcastedQueuesDynamic = internal.bro
  * 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
  */
@@ -265,6 +373,14 @@ const catchSomeCause = exports.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
  */
@@ -333,6 +449,17 @@ const combineChunks = exports.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
  */
@@ -340,6 +467,24 @@ const concat = exports.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
  */
@@ -351,6 +496,22 @@ const concatAll = exports.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
  */
@@ -400,6 +561,45 @@ const crossWith = exports.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
  */
@@ -450,6 +650,15 @@ const distributedWithDynamic = exports.distributedWithDynamic = internal.distrib
  * 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
  */
@@ -525,6 +734,14 @@ const either = exports.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
  */
@@ -532,6 +749,22 @@ const empty = exports.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
  */
@@ -581,6 +814,18 @@ const execute = exports.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
  */
@@ -609,6 +854,14 @@ const failCauseSync = exports.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
  */
@@ -654,6 +907,29 @@ const filterMapWhileEffect = exports.filterMapWhileEffect = internal.filterMapWh
  * 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
  */
@@ -745,6 +1021,22 @@ const forever = exports.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
  */
@@ -766,6 +1058,15 @@ const toChannel = exports.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
  */
@@ -789,6 +1090,15 @@ const fromChunkQueue = exports.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
  */
@@ -797,6 +1107,14 @@ const fromChunks = exports.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
  */
@@ -820,6 +1138,16 @@ const fromPubSub = exports.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
  */
@@ -827,6 +1155,23 @@ const fromIterable = exports.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
  */
@@ -880,6 +1225,19 @@ const fromReadableStreamByob = exports.fromReadableStreamByob = internal.fromRea
  * 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
  */
@@ -895,6 +1253,35 @@ const groupAdjacentBy = exports.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
  */
@@ -940,6 +1327,22 @@ const groupByKey = exports.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
  */
@@ -948,6 +1351,43 @@ const grouped = exports.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
  */
@@ -999,6 +1439,16 @@ const identity = exports.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
  */
@@ -1012,6 +1462,25 @@ const interleave = exports.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
  */
@@ -1019,6 +1488,20 @@ const interleaveWith = exports.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
  */
@@ -1026,6 +1509,27 @@ const intersperse = exports.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
  */
@@ -1066,6 +1570,15 @@ const interruptWhenDeferred = exports.interruptWhenDeferred = internal.interrupt
  * 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
  */
@@ -1073,6 +1586,14 @@ const iterate = exports.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
  */
@@ -1080,6 +1601,14 @@ const make = exports.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
  */
@@ -1087,6 +1616,18 @@ const map = exports.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
  */
@@ -1125,6 +1666,17 @@ const mapChunksEffect = exports.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
  */
@@ -1156,6 +1708,16 @@ const mapConcatEffect = exports.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
  */
@@ -1180,6 +1742,21 @@ const mapErrorCause = exports.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
  */
@@ -1200,6 +1777,24 @@ const mergeAll = exports.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
  */
@@ -1337,6 +1932,17 @@ const orElseSucceed = exports.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
  */
@@ -1374,6 +1980,25 @@ const paginateEffect = exports.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
  */
@@ -1382,6 +2007,28 @@ const partition = exports.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
  */
@@ -1482,9 +2129,45 @@ const mapInputContext = exports.mapInputContext = internal.mapInputContext;
  * @category context
  */
 const provideSomeLayer = exports.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
+ */
+const raceAll = exports.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
  */
@@ -1516,6 +2199,14 @@ const refineOrDieWith = exports.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
  */
@@ -1524,6 +2215,14 @@ const repeat = exports.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
  */
@@ -1548,6 +2247,22 @@ const repeatEffectChunkOption = exports.repeatEffectChunkOption = internal.repea
  * 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
  */
@@ -1599,6 +2314,14 @@ const repeatElementsWith = exports.repeatElementsWith = internal.repeatElementsW
 /**
  * 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
  */
@@ -1840,6 +2563,14 @@ const runSum = exports.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
  */
@@ -1891,6 +2622,24 @@ const scheduleWith = exports.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
  */
@@ -1979,6 +2728,15 @@ const splitLines = exports.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
  */
@@ -2000,6 +2758,14 @@ const suspend = exports.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
  */
@@ -2007,6 +2773,14 @@ const take = exports.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
  */
@@ -2015,6 +2789,14 @@ const takeRight = exports.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
  */
@@ -2031,6 +2813,14 @@ const takeUntilEffect = exports.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
  */
@@ -2038,6 +2828,24 @@ const takeWhile = exports.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
  */
@@ -2078,7 +2886,7 @@ const tapSink = exports.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
@@ -2086,6 +2894,43 @@ const tapSink = exports.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
  */
@@ -2110,6 +2955,27 @@ const throttleEffect = exports.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
  */
@@ -2159,6 +3025,32 @@ const toPubSub = exports.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
  */
@@ -2220,6 +3112,14 @@ const transduce = exports.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
  */
@@ -2243,6 +3143,17 @@ const unfoldChunkEffect = exports.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
  */
@@ -2314,6 +3225,18 @@ const withSpan = exports.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
  */
@@ -2335,6 +3258,18 @@ const zipFlatten = exports.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
  */
@@ -2426,6 +3361,19 @@ const zipAllSortedByKeyWith = exports.zipAllSortedByKeyWith = internal.zipAllSor
  * 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
  */
@@ -2439,6 +3387,22 @@ const zipAllWith = exports.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
  */
@@ -2460,7 +3424,7 @@ const zipLatest = exports.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 ]
@@ -2513,6 +3477,19 @@ const zipRight = exports.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
  */
@@ -2530,6 +3507,19 @@ const zipWithChunks = exports.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
  */
@@ -2538,6 +3528,19 @@ const zipWithNext = exports.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
  */
@@ -2545,6 +3548,35 @@ const zipWithPrevious = exports.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
  */
@@ -2552,6 +3584,19 @@ const zipWithPreviousAndNext = exports.zipWithPreviousAndNext = internal.zipWith
 /**
  * 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
  */