@openstage/monadyssey-core 3.0.0-rc.1 → 3.0.0-rc.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -2,10 +2,20 @@ export declare interface Cancelled {
2
2
  readonly type: "Cancelled";
3
3
  }
4
4
 
5
+ /** How many items `parTraverse` / `parSequence` run at once. */
6
+ declare interface Concurrency {
7
+ /** At most this many items run at once: a positive integer, or `Infinity` (the default). */
8
+ readonly concurrency?: number;
9
+ }
10
+
5
11
  /**
6
- * Represents a type which is either a Left (failure) or a Right (success).
7
- * Left typically stores an error or failure state, while Right stores a success value.
12
+ * A run that ended with a defect: an exception that was not declared as an `E`. It carries no
13
+ * exception; the defect itself still reaches `unsafeRun()` / `join()`.
8
14
  */
15
+ export declare interface Defect {
16
+ readonly type: "Defect";
17
+ }
18
+
9
19
  export declare abstract class Either<A, B> {
10
20
  abstract readonly type: "Left" | "Right";
11
21
  /**
@@ -139,6 +149,46 @@ export declare abstract class Either<A, B> {
139
149
  * Left.of('Error').tapLeft(err => console.log(err)); // Logs "Error"
140
150
  */
141
151
  abstract tapLeft(action: (left: A) => void): Either<A, B>;
152
+ /**
153
+ * Applicative combine of independent `Either`s ("applicative for"): collects *every* `Left`
154
+ * into a `NonEmptyList`, in argument order, instead of stopping at the first. When all are
155
+ * `Right`, the last argument combines their values (in argument order). Use it to validate
156
+ * several fields and report every failure at once; {@link forM} stops at the first `Left`.
157
+ *
158
+ * Each `Either` may have a different error type; the result's is `NonEmptyList<E1 | E2 | …>`.
159
+ *
160
+ * @example
161
+ * const form = Either.forA(
162
+ * required("name", input.name), // Either<FieldError, string>
163
+ * validEmail(input.email), // Either<FieldError, Email>
164
+ * (name, email) => ({ name, email })
165
+ * ); // Either<NonEmptyList<FieldError>, { name, email }>
166
+ */
167
+ static forA<E1, E2, A1, A2, R>(e1: Either<E1, A1>, e2: Either<E2, A2>, f: (a1: A1, a2: A2) => R): Either<NonEmptyList<E1 | E2>, R>;
168
+ static forA<E1, E2, E3, A1, A2, A3, R>(e1: Either<E1, A1>, e2: Either<E2, A2>, e3: Either<E3, A3>, f: (a1: A1, a2: A2, a3: A3) => R): Either<NonEmptyList<E1 | E2 | E3>, R>;
169
+ static forA<E1, E2, E3, E4, A1, A2, A3, A4, R>(e1: Either<E1, A1>, e2: Either<E2, A2>, e3: Either<E3, A3>, e4: Either<E4, A4>, f: (a1: A1, a2: A2, a3: A3, a4: A4) => R): Either<NonEmptyList<E1 | E2 | E3 | E4>, R>;
170
+ static forA<E1, E2, E3, E4, E5, A1, A2, A3, A4, A5, R>(e1: Either<E1, A1>, e2: Either<E2, A2>, e3: Either<E3, A3>, e4: Either<E4, A4>, e5: Either<E5, A5>, f: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5) => R): Either<NonEmptyList<E1 | E2 | E3 | E4 | E5>, R>;
171
+ static forA<E1, E2, E3, E4, E5, E6, A1, A2, A3, A4, A5, A6, R>(e1: Either<E1, A1>, e2: Either<E2, A2>, e3: Either<E3, A3>, e4: Either<E4, A4>, e5: Either<E5, A5>, e6: Either<E6, A6>, f: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6) => R): Either<NonEmptyList<E1 | E2 | E3 | E4 | E5 | E6>, R>;
172
+ static forA<E1, E2, E3, E4, E5, E6, E7, A1, A2, A3, A4, A5, A6, A7, R>(e1: Either<E1, A1>, e2: Either<E2, A2>, e3: Either<E3, A3>, e4: Either<E4, A4>, e5: Either<E5, A5>, e6: Either<E6, A6>, e7: Either<E7, A7>, f: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6, a7: A7) => R): Either<NonEmptyList<E1 | E2 | E3 | E4 | E5 | E6 | E7>, R>;
173
+ static forA<E1, E2, E3, E4, E5, E6, E7, E8, A1, A2, A3, A4, A5, A6, A7, A8, R>(e1: Either<E1, A1>, e2: Either<E2, A2>, e3: Either<E3, A3>, e4: Either<E4, A4>, e5: Either<E5, A5>, e6: Either<E6, A6>, e7: Either<E7, A7>, e8: Either<E8, A8>, f: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6, a7: A7, a8: A8) => R): Either<NonEmptyList<E1 | E2 | E3 | E4 | E5 | E6 | E7 | E8>, R>;
174
+ static forA<E1, E2, E3, E4, E5, E6, E7, E8, E9, A1, A2, A3, A4, A5, A6, A7, A8, A9, R>(e1: Either<E1, A1>, e2: Either<E2, A2>, e3: Either<E3, A3>, e4: Either<E4, A4>, e5: Either<E5, A5>, e6: Either<E6, A6>, e7: Either<E7, A7>, e8: Either<E8, A8>, e9: Either<E9, A9>, f: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6, a7: A7, a8: A8, a9: A9) => R): Either<NonEmptyList<E1 | E2 | E3 | E4 | E5 | E6 | E7 | E8 | E9>, R>;
175
+ /**
176
+ * Monadic comprehension ("monadic for") over `Either`, synchronous. Inside `operation`,
177
+ * `bind(either)` returns the `Right` value; the first `Left` stops the body, and `forM` returns
178
+ * that `Left`. The body's return value becomes the `Right`. An exception that is not a `Left`
179
+ * is not caught: it propagates from `forM`. Use {@link forA} to collect every `Left` instead.
180
+ *
181
+ * `bind` stops the body by throwing, so a `try` / `catch` in the body must rethrow what it does
182
+ * not handle, and the body must be synchronous.
183
+ *
184
+ * @example
185
+ * const total = Either.forM<ParseError, number>((bind) => {
186
+ * const price = bind(parsePrice(input.price));
187
+ * const quantity = bind(parseQuantity(input.quantity));
188
+ * return price * quantity;
189
+ * });
190
+ */
191
+ static forM<E, A>(operation: (bind: <B>(either: Either<E, B>) => B) => A & NotThenable): Either<E, A>;
142
192
  }
143
193
 
144
194
  /**
@@ -172,6 +222,15 @@ export declare interface Err<E> {
172
222
  * @template A The type of the value that this computation produces.
173
223
  */
174
224
  export declare abstract class Eval<A> {
225
+ /**
226
+ * Retrieves the value of the operation.
227
+ * This is an internal method used by the trampoline interpreter. External code should
228
+ * always use `evaluate()` instead — calling `value()` directly on `Map` or `FlatMap`
229
+ * nodes throws an `EvaluationError`.
230
+ *
231
+ * @returns {A} The value produced by the operation.
232
+ */
233
+ protected abstract value(): A;
175
234
  /**
176
235
  * Creates a deferred operation that will be evaluated later.
177
236
  * The provided function is not executed until the value of the operation is needed.
@@ -333,19 +392,39 @@ export declare class EvaluationError<E> extends Error {
333
392
  constructor(error: E);
334
393
  }
335
394
 
395
+ /**
396
+ * The outcome of a run: a value, a typed error, or cancellation. A forked fiber's `join()` resolves to
397
+ * an `Exit`, and so does `unsafeRun({ signal })`; `unsafeRun()` without a signal cannot be cancelled
398
+ * from outside, so it yields `Ok<A> | Err<E>`.
399
+ */
400
+ export declare type Exit<E, A> = Ok<A> | Err<E> | Cancelled;
401
+
336
402
  export declare interface Fiber<E, A> {
337
403
  /**
338
404
  * Wait for the computation to complete. Rejects with the original exception on a defect. A
339
405
  * defect in a fiber that nobody joins is reported as an unhandled rejection instead, once the
340
406
  * run that forked the fiber has ended (until then, that run may still join it).
341
407
  */
342
- readonly join: () => Promise<Ok<A> | Err<E> | Cancelled>;
408
+ readonly join: () => Promise<Exit<E, A>>;
343
409
  /** Request cancellation. Idempotent. Resolves after finalizers run. */
344
410
  readonly cancel: () => Promise<void>;
345
411
  /** The underlying AbortSignal for interop with platform APIs. */
346
412
  readonly signal: AbortSignal;
347
413
  }
348
414
 
415
+ /** Options for {@link IO.fork} and {@link IO.forkDaemon}. */
416
+ export declare interface ForkOptions {
417
+ /**
418
+ * Receives the defect of the fiber when nobody joins it, right after the defect happens (one
419
+ * macrotask later), for `fork` and `forkDaemon` alike: the forking run keeps no record of the
420
+ * fiber, so a long-running run can fork any number of them. It is not called when the fiber is
421
+ * joined first (`join()` rejects with the defect as usual), nor for a typed error or a
422
+ * cancellation. A fiber joined after the handler was called still rejects `join()` with the
423
+ * defect. If the handler throws, that exception is reported as an unhandled rejection instead.
424
+ */
425
+ readonly onDefect?: (cause: unknown) => void;
426
+ }
427
+
349
428
  /**
350
429
  * `Ordering.GT` as a bare module constant.
351
430
  *
@@ -389,6 +468,8 @@ export declare function identity<A>(a: A): A;
389
468
  * to evaluate the tree, ensuring stack safety for arbitrarily deep chains.
390
469
  */
391
470
  export declare class IO<E, A> {
471
+ /** Build an `IO` through its static constructors: `IO.of`, `IO.fail`, `IO.lift`, `IO.sync`, `IO.promise`. */
472
+ private constructor();
392
473
  /**
393
474
  * Creates an IO from an effectful function that may be synchronous or asynchronous.
394
475
  * The function is not executed until `unsafeRun()` is called on the resulting IO,
@@ -467,8 +548,8 @@ export declare class IO<E, A> {
467
548
  * Creates an IO from a function that receives an `AbortSignal` for cooperative cancellation.
468
549
  * Use this when the underlying operation supports cancellation (e.g., `fetch`, streams, timers).
469
550
  *
470
- * The signal is provided by the interpreter when the IO is forked. If the IO is run
471
- * without forking (via `unsafeRun`), the signal is never aborted.
551
+ * The signal is the run's: a fiber's, a `timeout`'s or `race`'s, or the one passed to
552
+ * `unsafeRun({ signal })`. Under a plain `unsafeRun()`, the signal is never aborted.
472
553
  *
473
554
  * On cancellation the interpreter does not wait for the returned promise: it runs the
474
555
  * finalizers and reports `Cancelled` straight away, and `f` is expected to stop its own work
@@ -500,9 +581,11 @@ export declare class IO<E, A> {
500
581
  * Semantics:
501
582
  * - If **acquire** fails, or is cancelled before producing a resource, `use` and `release` are
502
583
  * never called.
503
- * - **acquire** is never abandoned half-way: if cancellation arrives while it runs and it still
504
- * produces a resource, that resource is released and `Cancelled` is propagated. (A
505
- * cancellable acquire still sees the signal and may stop early.)
584
+ * - If cancellation arrives while **acquire** runs, the bracket ends as `Cancelled` at once,
585
+ * without waiting for it: a slow acquire cannot hold a cancellation or a timeout. A resource
586
+ * it still produces later is released as soon as it arrives, with `Cancelled` as the exit. (A
587
+ * cancellable acquire sees the signal and may stop early. To keep a step from being left
588
+ * behind, such as a commit, use {@link IO.uncancellable}.)
506
589
  * - If **use** succeeds, `release` runs and the success value is returned.
507
590
  * - If **use** fails, `release` runs and the original error is returned.
508
591
  * - If **use** is cancelled, `release` runs and `Cancelled` is propagated.
@@ -545,7 +628,34 @@ export declare class IO<E, A> {
545
628
  * (pool) => IO.promise(() => pool.shutdown())
546
629
  * ).mapErr(e => new AppError(e));
547
630
  */
548
- static bracket<E, F, R, A>(acquire: IO<E, R>, use: (r: R) => IO<F, A>, release: (r: R) => IO<never, void>): IO<E | F, A>;
631
+ static bracket<E, F, R, A>(acquire: IO<E, R>, use: (r: R) => IO<F, A>, release: (r: R, exit: ReleaseExit<F, A>) => IO<never, void>): IO<E | F, A>;
632
+ /**
633
+ * Runs `io` to its end even when the run is cancelled while it runs. The cancellation takes
634
+ * effect right after `io` ends: the run then ends as `Cancelled`, and `io`'s value or error is
635
+ * dropped. Use it for a step that must not be abandoned half-way, such as a database commit, an
636
+ * `fsync` after a rename, or acknowledging a message.
637
+ *
638
+ * - The effects inside never see an abort: the signal they receive does not abort while they run.
639
+ * - An enclosing `timeout` or a lost `race` waits for `io` to end before it settles.
640
+ * - A run that is already cancelled when it reaches this step does not start `io`.
641
+ * - A fiber forked inside is a child of the outer run, but the outer cancellation reaches it only
642
+ * when `io` ends, so `io` can still join it. After that, it is cancelled with the outer run like
643
+ * any other child. A `forkDaemon` fiber has no parent, here as anywhere else.
644
+ *
645
+ * Failures and defects of `io` pass through unchanged.
646
+ *
647
+ * @template E The error type of `io`.
648
+ * @template A The success type of `io`.
649
+ * @param {IO<E, A>} io The IO to protect from cancellation.
650
+ * @returns {IO<E, A>} An IO that runs `io` to its end.
651
+ *
652
+ * @example
653
+ * const transaction = (conn: Connection): IO<DbError, Order> =>
654
+ * insertOrder(conn).flatMap((order) =>
655
+ * IO.uncancellable(IO.lift(() => conn.commit(), toDbError)).map(() => order)
656
+ * );
657
+ */
658
+ static uncancellable<E, A>(io: IO<E, A>): IO<E, A>;
549
659
  /**
550
660
  * Lifts an already-computed value into IO with no side effect.
551
661
  * The value is available immediately — no deferred computation takes place.
@@ -723,8 +833,10 @@ export declare class IO<E, A> {
723
833
  * If this IO fails, the function is not called. The callback may be synchronous
724
834
  * or asynchronous — the interpreter awaits if it returns a Promise.
725
835
  *
726
- * If the side-effect throws, the exception is swallowed and the original success
727
- * value is preserved. Use `map` or `flatMap` if failure should propagate.
836
+ * If the side-effect throws or rejects, that is a **defect**, as a throw in `map` is: it is not
837
+ * an `E`, and `unsafeRun()` rejects with it. For a side effect that may fail and whose failure
838
+ * should be ignored, catch it inside the callback; for one whose failure is an `E`, use
839
+ * `flatMap` with an `IO.lift(f, liftE)`.
728
840
  *
729
841
  * @param {(a: A) => void | Promise<void>} f The side-effect function.
730
842
  * @returns {IO<E, A>} A new IO that performs the side-effect but preserves the original result.
@@ -738,8 +850,9 @@ export declare class IO<E, A> {
738
850
  * If this IO succeeds, the function is not called. The callback may be synchronous
739
851
  * or asynchronous — the interpreter awaits if it returns a Promise.
740
852
  *
741
- * If the side-effect throws, the exception is swallowed and the original error
742
- * is preserved. Use `mapErr` or `flatMapErr` if failure should propagate.
853
+ * If the side-effect throws or rejects, that is a **defect**, as a throw in `mapErr` is: it does
854
+ * not replace the error, and `unsafeRun()` rejects with it. For a side effect that may fail and
855
+ * whose failure should be ignored, catch it inside the callback.
743
856
  *
744
857
  * @param {(e: E) => void | Promise<void>} f The side-effect function.
745
858
  * @returns {IO<E, A>} A new IO that performs the side-effect but preserves the original error.
@@ -854,12 +967,26 @@ export declare class IO<E, A> {
854
967
  * exception from an effect or callback that was not declared fallible — with the original
855
968
  * exception, after cleanup has run; handle it with `.catch` at the edge of the program.
856
969
  *
970
+ * With a `signal`, aborting it cancels the run as cancelling a fiber does: effects receive the
971
+ * signal, an effect that ignores it is abandoned, finalizers and `bracket` releases run, forked
972
+ * child fibers are cancelled, and the promise resolves with `Cancelled` once that is done. A
973
+ * signal that has already aborted gives `Cancelled` without running anything.
974
+ *
857
975
  * @returns {Promise<Err<E> | Ok<A>>} The result of the computation.
858
976
  *
859
977
  * @example
860
978
  * const result = await IO.of(42).unsafeRun();
861
979
  * // result: { type: "Ok", value: 42 }
980
+ *
981
+ * @example
982
+ * // Stop the work when the client disconnects.
983
+ * const exit = await handle(request).unsafeRun({ signal: request.signal });
984
+ * if (exit.type === "Cancelled") return;
862
985
  */
986
+ /** Runs the IO under `signal`; aborting it cancels the run, which then ends as `Cancelled`. */
987
+ unsafeRun(options: {
988
+ readonly signal: AbortSignal;
989
+ }): Promise<Exit<E, A>>;
863
990
  unsafeRun(): Promise<Err<E> | Ok<A>>;
864
991
  /**
865
992
  * Executes the IO and folds both outcomes (success and error) into a single type.
@@ -966,6 +1093,10 @@ export declare class IO<E, A> {
966
1093
  * returned once the cancelled computation has unwound (its finalizers have run); an effect that
967
1094
  * ignores the signal is abandoned rather than waited for.
968
1095
  *
1096
+ * The deadline bounds waiting, not work: it fires on a timer, so work that never waits for the
1097
+ * next macrotask (a long synchronous loop, a large `traverse` of synchronous steps) runs to its
1098
+ * end before the timeout can take effect.
1099
+ *
969
1100
  * This is a first-class replacement for the verbose `IO.race` workaround:
970
1101
  * ```typescript
971
1102
  * // Before — manual race
@@ -979,7 +1110,9 @@ export declare class IO<E, A> {
979
1110
  * ```
980
1111
  *
981
1112
  * @template F The timeout error type.
982
- * @param {number} ms The timeout duration in milliseconds.
1113
+ * @param {number} ms The timeout duration in milliseconds. Must be a non-negative number: a negative or `NaN`
1114
+ * deadline throws `RangeError` where it is written. A deadline above 2,147,483,647 ms (the
1115
+ * `setTimeout` limit), including `Infinity`, is lowered to it instead of firing at once.
983
1116
  * @param {() => F} onTimeout A thunk that produces the timeout error value. If it throws, that
984
1117
  * is a defect.
985
1118
  * @returns {IO<E | F, A>} A new IO that fails with `F` if the timeout elapses.
@@ -1011,8 +1144,10 @@ export declare class IO<E, A> {
1011
1144
  *
1012
1145
  * A defect in the fiber makes `join()` reject with it. If the fiber is never joined, the defect
1013
1146
  * is reported as an unhandled rejection once the run that forked it has ended, or straight away
1014
- * when it happens after that (a handle returned out of its run that nobody joins).
1147
+ * when it happens after that (a handle returned out of its run that nobody joins). With
1148
+ * `onDefect`, that defect goes to the handler instead, right after it happens.
1015
1149
  *
1150
+ * @param options `onDefect`: receives the defect of a fiber nobody joins. See {@link ForkOptions}.
1016
1151
  * @returns {IO<never, Fiber<E, A>>} An IO that, when executed, starts this IO and returns a Fiber.
1017
1152
  *
1018
1153
  * @example
@@ -1023,15 +1158,24 @@ export declare class IO<E, A> {
1023
1158
  * return outcome.type === "Ok" ? outcome.value : "unavailable";
1024
1159
  * });
1025
1160
  */
1026
- fork(): IO<never, Fiber<E, A>>;
1161
+ fork(options?: ForkOptions): IO<never, Fiber<E, A>>;
1027
1162
  /**
1028
1163
  * Like {@link fork}, but the fiber is not a child of the run that forks it: cancelling that run
1029
1164
  * does not cancel the fiber. Use it for work that must finish on its own (a flush, an audit
1030
1165
  * write) regardless of what happens to the code that started it; cancel it through its handle.
1031
1166
  *
1167
+ * A daemon often outlives the request that started it, so a defect in it has nobody to reach:
1168
+ * pass `onDefect` to log it instead of letting it become an unhandled rejection, which stops a
1169
+ * Node process by default. A daemon's `onDefect` is called right after the defect happens,
1170
+ * unless the fiber is joined before then, even while the run that forked it is still running.
1171
+ *
1172
+ * @param options `onDefect`: receives the defect of a fiber nobody joins. See {@link ForkOptions}.
1032
1173
  * @returns {IO<never, Fiber<E, A>>} An IO that, when executed, starts this IO and returns a Fiber.
1174
+ *
1175
+ * @example
1176
+ * audit(event).forkDaemon({ onDefect: (cause) => logger.error("audit write failed", cause) });
1033
1177
  */
1034
- forkDaemon(): IO<never, Fiber<E, A>>;
1178
+ forkDaemon(options?: ForkOptions): IO<never, Fiber<E, A>>;
1035
1179
  /**
1036
1180
  * Applicative combine of independent IOs ("applicative for"). The IOs do not depend on one
1037
1181
  * another, so they run concurrently via `Promise.all`, and — unlike the monadic {@link forM},
@@ -1041,7 +1185,8 @@ export declare class IO<E, A> {
1041
1185
  *
1042
1186
  * Supports heterogeneous error types — each IO may have a different error type, and the
1043
1187
  * accumulated error is `NonEmptyList<E1 | E2 | …>`. The last argument is the combiner that
1044
- * receives the success values in argument order (the applicative `yield`).
1188
+ * receives the success values in argument order (the applicative `yield`). Accumulated errors are in
1189
+ * argument order too.
1045
1190
  *
1046
1191
  * @example
1047
1192
  * const io = IO.forA(
@@ -1130,20 +1275,31 @@ export declare class IO<E, A> {
1130
1275
  /**
1131
1276
  * Executes a function over each item in parallel, collecting all results or all errors.
1132
1277
  * Unlike `traverse`, all items are processed concurrently. If any fail, all errors
1133
- * are collected into a `NonEmptyList`.
1278
+ * are collected into a `NonEmptyList`. Results, and errors, keep the order of
1279
+ * `items`, not the order of completion.
1280
+ *
1281
+ * With `concurrency: n`, at most `n` items run at once; the next item starts as soon as one
1282
+ * ends. Every item still runs, so every error is still collected. After a defect, or once the
1283
+ * run is cancelled, no further item starts. A `concurrency` that is not a positive integer or
1284
+ * `Infinity` throws `RangeError` where the call is written.
1134
1285
  *
1135
1286
  * @template E The error type.
1136
1287
  * @template A The input item type.
1137
1288
  * @template B The output type for each item.
1138
1289
  * @param {A[]} items The items to traverse in parallel.
1139
1290
  * @param {(a: A) => IO<E, B>} f A function that produces an IO for each item.
1291
+ * @param options `concurrency`: how many items run at once (default `Infinity`).
1140
1292
  * @returns {IO<NonEmptyList<E>, List<B>>} An IO that succeeds with all results as a List, or fails with all errors.
1141
1293
  *
1142
1294
  * @example
1143
1295
  * const io = IO.parTraverse([1, 2, 3], n => IO.of(n * 2));
1144
1296
  * // result: { type: "Ok", value: List [2, 4, 6] }
1297
+ *
1298
+ * @example
1299
+ * // At most 5 queries at once, however many ids the request carries.
1300
+ * const users = IO.parTraverse(ids, (id) => findUser(id), { concurrency: 5 });
1145
1301
  */
1146
- static parTraverse<E, A, B>(items: readonly A[], f: (a: A) => IO<E, B>): IO<NonEmptyList<E>, List<B>>;
1302
+ static parTraverse<E, A, B>(items: readonly A[], f: (a: A) => IO<E, B>, options?: Concurrency): IO<NonEmptyList<E>, List<B>>;
1147
1303
  /**
1148
1304
  * Sequentially executes an array of IOs, collecting results into an array.
1149
1305
  * Equivalent to `traverse(ios, x => x)`. Fail-fast on the first error.
@@ -1160,18 +1316,19 @@ export declare class IO<E, A> {
1160
1316
  static sequence<E, A>(ios: readonly IO<E, A>[]): IO<E, List<A>>;
1161
1317
  /**
1162
1318
  * Executes an array of IOs in parallel, collecting all results or all errors.
1163
- * Equivalent to `parTraverse(ios, x => x)`.
1319
+ * Equivalent to `parTraverse(ios, x => x, options)`. Results and errors keep the order of `ios`.
1164
1320
  *
1165
1321
  * @template E The error type.
1166
1322
  * @template A The success type of each IO.
1167
1323
  * @param {IO<E, A>[]} ios The IO operations to execute in parallel.
1324
+ * @param options `concurrency`: how many IOs run at once (default `Infinity`); see {@link parTraverse}.
1168
1325
  * @returns {IO<NonEmptyList<E>, List<A>>} An IO that succeeds with all results as a List, or fails with all errors.
1169
1326
  *
1170
1327
  * @example
1171
1328
  * const io = IO.parSequence([IO.of(1), IO.of(2), IO.of(3)]);
1172
1329
  * // result: { type: "Ok", value: List [1, 2, 3] }
1173
1330
  */
1174
- static parSequence<E, A>(ios: readonly IO<E, A>[]): IO<NonEmptyList<E>, List<A>>;
1331
+ static parSequence<E, A>(ios: readonly IO<E, A>[], options?: Concurrency): IO<NonEmptyList<E>, List<A>>;
1175
1332
  }
1176
1333
 
1177
1334
  export declare class Left<A> extends Either<A, never> {
@@ -1226,7 +1383,7 @@ export declare class List<A> {
1226
1383
  * @example
1227
1384
  * List.empty<number>().isEmpty; // true
1228
1385
  */
1229
- static empty<A>(): List<A>;
1386
+ static empty<A = never>(): List<A>;
1230
1387
  /**
1231
1388
  * Creates a `List` from a variadic argument list.
1232
1389
  *
@@ -1238,7 +1395,7 @@ export declare class List<A> {
1238
1395
  * List.of(1, 2, 3).toArray(); // [1, 2, 3]
1239
1396
  * List.of<number>().toArray(); // []
1240
1397
  */
1241
- static of<A>(...values: A[]): List<A>;
1398
+ static of<A = never>(...values: A[]): List<A>;
1242
1399
  /**
1243
1400
  * Creates a `List` from any iterable — an array, `Set`, `Map` (yields `[key, value]`
1244
1401
  * entries), generator, another `List` or `NonEmptyList`, etc. The iterable is consumed once
@@ -1272,7 +1429,7 @@ export declare class List<A> {
1272
1429
  * @param {number} endExclusive The exclusive end value.
1273
1430
  * @param {number} [step=1] The increment between successive values. Must be non-zero.
1274
1431
  * @returns {List<number>} A `List<number>` of the requested range.
1275
- * @throws {Error} If `step` is zero.
1432
+ * @throws {RangeError} If `step` is zero, an argument is not finite, or the range would hold more than 2^32 − 1 elements.
1276
1433
  *
1277
1434
  * @example
1278
1435
  * List.range(0, 5).toArray(); // [0, 1, 2, 3, 4]
@@ -1964,6 +2121,8 @@ export declare class List<A> {
1964
2121
  * List.empty<number>().toString(); // "[]"
1965
2122
  */
1966
2123
  toString(): string;
2124
+ /** The elements of a `List` or `NonEmptyList`, including one built by another copy of the library. */
2125
+ private static _elements;
1967
2126
  /**
1968
2127
  * The JSON form of a `List`: a plain array of its elements, so `JSON.stringify(list)` is
1969
2128
  * `JSON.stringify(list.toArray())`.
@@ -2671,6 +2830,14 @@ export declare class NonEmptyList<A> {
2671
2830
  toJSON(): A[];
2672
2831
  }
2673
2832
 
2833
+ /**
2834
+ * A body result that is not a promise: an `async` body would return before its `bind`s ran, so
2835
+ * `forM` rejects it at compile time (and with a `TypeError` at run time).
2836
+ */
2837
+ declare type NotThenable = {
2838
+ readonly then?: never;
2839
+ } | null | undefined;
2840
+
2674
2841
  export declare interface Ok<A> {
2675
2842
  readonly type: "Ok";
2676
2843
  readonly value: A;
@@ -2789,6 +2956,40 @@ export declare abstract class Option<A> {
2789
2956
  * Option.empty<number>().tapNone(() => console.log("No value")); // Logs "No value"
2790
2957
  */
2791
2958
  abstract tapNone(f: () => void): Option<A>;
2959
+ /**
2960
+ * Applicative combine of independent `Option`s ("applicative for"): `Some` of the last
2961
+ * argument applied to their values (in argument order) when all are `Some`, and `None` as soon
2962
+ * as one is `None` — the combiner is then not called. A `None` carries nothing, so unlike
2963
+ * `Either.forA` there is nothing to collect. A combiner result of `null` or `undefined` is `None`.
2964
+ *
2965
+ * @example
2966
+ * const contact = Option.forA(name, email, (n, e) => ({ name: n, email: e })); // Option<{ name, email }>
2967
+ */
2968
+ static forA<A1, A2, R>(o1: Option<A1>, o2: Option<A2>, f: (a1: A1, a2: A2) => R | null | undefined): Option<NonNullable<R>>;
2969
+ static forA<A1, A2, A3, R>(o1: Option<A1>, o2: Option<A2>, o3: Option<A3>, f: (a1: A1, a2: A2, a3: A3) => R | null | undefined): Option<NonNullable<R>>;
2970
+ static forA<A1, A2, A3, A4, R>(o1: Option<A1>, o2: Option<A2>, o3: Option<A3>, o4: Option<A4>, f: (a1: A1, a2: A2, a3: A3, a4: A4) => R | null | undefined): Option<NonNullable<R>>;
2971
+ static forA<A1, A2, A3, A4, A5, R>(o1: Option<A1>, o2: Option<A2>, o3: Option<A3>, o4: Option<A4>, o5: Option<A5>, f: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5) => R | null | undefined): Option<NonNullable<R>>;
2972
+ static forA<A1, A2, A3, A4, A5, A6, R>(o1: Option<A1>, o2: Option<A2>, o3: Option<A3>, o4: Option<A4>, o5: Option<A5>, o6: Option<A6>, f: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6) => R | null | undefined): Option<NonNullable<R>>;
2973
+ static forA<A1, A2, A3, A4, A5, A6, A7, R>(o1: Option<A1>, o2: Option<A2>, o3: Option<A3>, o4: Option<A4>, o5: Option<A5>, o6: Option<A6>, o7: Option<A7>, f: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6, a7: A7) => R | null | undefined): Option<NonNullable<R>>;
2974
+ static forA<A1, A2, A3, A4, A5, A6, A7, A8, R>(o1: Option<A1>, o2: Option<A2>, o3: Option<A3>, o4: Option<A4>, o5: Option<A5>, o6: Option<A6>, o7: Option<A7>, o8: Option<A8>, f: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6, a7: A7, a8: A8) => R | null | undefined): Option<NonNullable<R>>;
2975
+ static forA<A1, A2, A3, A4, A5, A6, A7, A8, A9, R>(o1: Option<A1>, o2: Option<A2>, o3: Option<A3>, o4: Option<A4>, o5: Option<A5>, o6: Option<A6>, o7: Option<A7>, o8: Option<A8>, o9: Option<A9>, f: (a1: A1, a2: A2, a3: A3, a4: A4, a5: A5, a6: A6, a7: A7, a8: A8, a9: A9) => R | null | undefined): Option<NonNullable<R>>;
2976
+ /**
2977
+ * Monadic comprehension ("monadic for") over `Option`, synchronous. Inside `operation`,
2978
+ * `bind(option)` returns the `Some` value; the first `None` stops the body, and `forM` returns
2979
+ * `None`. The body's return value becomes the result, `None` when it is `null` or `undefined`.
2980
+ * An exception is not caught: it propagates from `forM`.
2981
+ *
2982
+ * `bind` stops the body by throwing, so a `try` / `catch` in the body must rethrow what it does
2983
+ * not handle, and the body must be synchronous.
2984
+ *
2985
+ * @example
2986
+ * const city = Option.forM((bind) => {
2987
+ * const user = bind(findUser(id));
2988
+ * const address = bind(user.address);
2989
+ * return address.city;
2990
+ * }); // Option<string>
2991
+ */
2992
+ static forM<A>(operation: (bind: <B>(option: Option<B>) => B) => A & NotThenable): Option<NonNullable<A>>;
2792
2993
  /**
2793
2994
  * Applies one of two provided functions based on the contents of this `Option`.
2794
2995
  * If it is `None`, it applies `ifNone`. If it is `Some`, it applies `ifSome`.
@@ -2806,7 +3007,7 @@ export declare abstract class Option<A> {
2806
3007
  * const value = Option.of(5).getOrNull(); // Returns 5
2807
3008
  * const empty = Option.empty<number>().getOrNull(); // Returns null
2808
3009
  */
2809
- getOrNull(): A | null;
3010
+ abstract getOrNull(): A | null;
2810
3011
  /**
2811
3012
  * Returns the contained value if `Some`, otherwise returns the provided default value.
2812
3013
  * @example
@@ -2814,7 +3015,7 @@ export declare abstract class Option<A> {
2814
3015
  * const empty = Option.empty<number>().getOrElse(() => 10); // Returns 10
2815
3016
  *
2816
3017
  */
2817
- getOrElse(defaultValue: () => A): A;
3018
+ abstract getOrElse(defaultValue: () => A): A;
2818
3019
  }
2819
3020
 
2820
3021
  /**
@@ -3481,7 +3682,7 @@ export declare type Pipe<E, A, B> = (stream: Stream<E, A>) => Stream<E, B>;
3481
3682
  * await bind(Stream.from(queue).runForEach((m) => handle(m)));
3482
3683
  * });
3483
3684
  */
3484
- export declare class Queue<A> {
3685
+ export declare class Queue<in out A> {
3485
3686
  private readonly capacity;
3486
3687
  private readonly onOverflow;
3487
3688
  private readonly items;
@@ -3548,7 +3749,8 @@ export declare class Queue<A> {
3548
3749
  * Offers a value. Resolves `true` when the value was accepted with nothing lost, `false` when
3549
3750
  * it was refused (queue closed, or `DropNewest` at capacity) or an older value was evicted
3550
3751
  * (`DropOldest` at capacity). Under `Suspend`, an offer at capacity waits for a `take`;
3551
- * cancelling the waiting fiber withdraws the offer.
3752
+ * cancelling the waiting fiber withdraws the offer, unless a `take` accepted the value at the
3753
+ * same moment: the run then ends `Cancelled` with the value in the queue all the same.
3552
3754
  *
3553
3755
  * @param {A} value The value to enqueue.
3554
3756
  * @returns {IO<never, boolean>}
@@ -3575,6 +3777,8 @@ export declare class Queue<A> {
3575
3777
  * if (next.type === "Ok" && !next.value.done) handle(next.value.value);
3576
3778
  */
3577
3779
  take(): IO<never, IteratorResult<A, void>>;
3780
+ /** Returns a value a cancelled taker received: to the next waiting taker, else to the front. */
3781
+ private putBack;
3578
3782
  /**
3579
3783
  * Closes the queue: every waiting `take` resumes with `{ done: true }`, every waiting `offer` resumes
3580
3784
  * with `false`, and later offers are refused. Values already buffered stay available to `take`.
@@ -3635,8 +3839,8 @@ export declare class Queue<A> {
3635
3839
  * const data = await fetchData.run({ multiplier: 1, apiEndpoint: 'https://api.example.com' });
3636
3840
  * ```
3637
3841
  */
3638
- export declare class Reader<R, A> {
3639
- private f;
3842
+ export declare class Reader<in R, out A> {
3843
+ private readonly f;
3640
3844
  /**
3641
3845
  * Initializes a new `Reader` instance.
3642
3846
  *
@@ -3711,6 +3915,10 @@ export declare class Reader<R, A> {
3711
3915
  * computation can determine the next computation. It is useful for creating complex
3712
3916
  * workflows that depend on the environment and previous results.
3713
3917
  *
3918
+ * The chain needs every environment its steps read: a `Reader<{ db: Db }, A>` chained with a
3919
+ * step that reads `{ cache: Cache }` is a `Reader<{ db: Db } & { cache: Cache }, B>`. A step
3920
+ * that reads the same environment, or none, keeps it.
3921
+ *
3714
3922
  * @param f - A function that takes the result of the current `Reader` and returns a new `Reader`.
3715
3923
  * @returns A new `Reader` instance that represents the chained computation.
3716
3924
  *
@@ -3727,6 +3935,8 @@ export declare class Reader<R, A> {
3727
3935
  * // Running the Reader with an environment will fetch and process the data
3728
3936
  * processData.run({ apiEndpoint: 'https://api.example.com' }).then(console.log);
3729
3937
  */
3938
+ flatMap<R2, B>(f: (a: A) => Reader<R2, B>): Reader<R & R2, B>;
3939
+ /** Chains a Reader that reads the same environment (explicit type argument `<B>`). */
3730
3940
  flatMap<B>(f: (a: A) => Reader<R, B>): Reader<R, B>;
3731
3941
  /**
3732
3942
  * Creates a `Reader` instance that provides access to the environment.
@@ -3758,6 +3968,10 @@ export declare class Reader<R, A> {
3758
3968
  * environment and collecting their results into a single value. It is purely
3759
3969
  * sequential — a `Reader` performs no concurrency.
3760
3970
  *
3971
+ * The combined `Reader` needs every environment its parts read: zipping a
3972
+ * `Reader<{ db: Db }, A>` with a `Reader<{ cache: Cache }, B>` gives a
3973
+ * `Reader<{ db: Db } & { cache: Cache }, readonly [A, B]>`.
3974
+ *
3761
3975
  * @param readers - An array of `Reader` instances to be combined.
3762
3976
  * @returns A new `Reader` instance that returns a tuple of the results of the given `Reader` instances.
3763
3977
  *
@@ -3774,6 +3988,10 @@ export declare class Reader<R, A> {
3774
3988
  * const env = { valueA: 42, valueB: "hello", valueC: true };
3775
3989
  * console.log(combinedReader.run(env)); // [42, "hello", true]
3776
3990
  */
3991
+ static zip<const T extends readonly Reader<never, unknown>[]>(...readers: T): Reader<ReaderEnvs<T>, {
3992
+ [K in keyof T]: ReaderValue<T[K]>;
3993
+ }>;
3994
+ /** Combines Readers that share an environment (explicit type arguments `<R, A>`). */
3777
3995
  static zip<R, const A extends readonly unknown[]>(...readers: {
3778
3996
  [K in keyof A]: Reader<R, A[K]>;
3779
3997
  }): Reader<R, A>;
@@ -3838,6 +4056,18 @@ export declare class Reader<R, A> {
3838
4056
  run(env: R): A;
3839
4057
  }
3840
4058
 
4059
+ /** The environment a Reader reads. */
4060
+ declare type ReaderEnv<T> = T extends Reader<infer R, unknown> ? R : never;
4061
+
4062
+ /**
4063
+ * The environment that every Reader of a tuple reads: the intersection of their environments. A
4064
+ * plain array (not a tuple) gives the environment of its element type.
4065
+ */
4066
+ declare type ReaderEnvs<T extends readonly unknown[]> = T extends readonly [] ? unknown : T extends readonly [infer Head, ...infer Rest] ? ReaderEnv<Head> & ReaderEnvs<Rest> : ReaderEnv<T[number]>;
4067
+
4068
+ /** The value a Reader produces. */
4069
+ declare type ReaderValue<T> = T extends Reader<never, infer A> ? A : never;
4070
+
3841
4071
  /**
3842
4072
  * A mutable cell whose every operation is an `IO<never, _>`. `Ref` is how state lives *inside* an
3843
4073
  * `IO` program — a session, a cache, a counter — instead of in a closure variable the effect
@@ -3865,7 +4095,7 @@ export declare class Reader<R, A> {
3865
4095
  * });
3866
4096
  * await program.unsafeRun(); // { type: "Ok", value: 2 }
3867
4097
  */
3868
- export declare class Ref<A> {
4098
+ export declare class Ref<in out A> {
3869
4099
  private value;
3870
4100
  private constructor();
3871
4101
  /**
@@ -3946,6 +4176,9 @@ export declare class Ref<A> {
3946
4176
  getAndSet(value: A): IO<never, A>;
3947
4177
  }
3948
4178
 
4179
+ /** How the `use` step of a `bracket` ended, as its release receives it. */
4180
+ export declare type ReleaseExit<E, A> = Exit<E, A> | Defect;
4181
+
3949
4182
  export declare class Right<B> extends Either<never, B> {
3950
4183
  readonly value: B;
3951
4184
  readonly type: "Right";
@@ -4041,7 +4274,9 @@ export declare class Schedule {
4041
4274
  */
4042
4275
  jittered(factor?: number): Schedule;
4043
4276
  /**
4044
- * Whether another attempt is allowed after `attempts` attempts have run.
4277
+ * Whether another attempt is allowed after `attempts` attempts have run. Together with
4278
+ * {@link delayAfter} this is the schedule protocol that `IO.retry`, `IO.repeat` and the SSE
4279
+ * reconnect in `@openstage/monadyssey-fetch` consume; both are public so other drivers can use it.
4045
4280
  *
4046
4281
  * @param {number} attempts The number of attempts made so far (`>= 1`).
4047
4282
  * @returns {boolean}
@@ -4050,6 +4285,7 @@ export declare class Schedule {
4050
4285
  /**
4051
4286
  * The delay before the next attempt, after `attempts` attempts have run: `initialDelay ×
4052
4287
  * factor^(attempts − 1)`, capped at `maxDelay`, then jittered.
4288
+ * The second half of the schedule protocol (see {@link allowsAttempt}).
4053
4289
  *
4054
4290
  * @param {number} attempts The number of attempts made so far (`>= 1`).
4055
4291
  * @returns {number} The delay in milliseconds.
@@ -4152,7 +4388,7 @@ export declare class Stream<E, A> {
4152
4388
  * (conn) => IO.promise(() => conn.close())
4153
4389
  * );
4154
4390
  */
4155
- static bracket<E, F, R, A>(acquire: IO<E, R>, use: (r: R) => Stream<F, A>, release: (r: R) => IO<never, void>): Stream<E | F, A>;
4391
+ static bracket<E, F, R, A>(acquire: IO<E, R>, use: (r: R) => Stream<F, A>, release: (r: R, exit: ReleaseExit<unknown, void>) => IO<never, void>): Stream<E | F, A>;
4156
4392
  /**
4157
4393
  * Builds a stream by repeatedly running an effectful step over a threaded seed. The step
4158
4394
  * returns `Some([element, nextSeed])` to emit and continue, or `None` to end the stream.
@@ -4184,7 +4420,7 @@ export declare class Stream<E, A> {
4184
4420
  * @example
4185
4421
  * Stream.of(1, 2, 3); // emits 1, 2, 3
4186
4422
  */
4187
- static of<A>(...values: A[]): Stream<never, A>;
4423
+ static of<A = never>(...values: A[]): Stream<never, A>;
4188
4424
  /**
4189
4425
  * A stream over any iterable (array, `Set`, `List`, generator, …), in iteration order. Lazy:
4190
4426
  * iteration starts when the stream is run, and each run iterates afresh — so a one-shot
@@ -4201,6 +4437,30 @@ export declare class Stream<E, A> {
4201
4437
  * const events = Stream.from(queue).map(parse).runForEach(handle);
4202
4438
  */
4203
4439
  static from<A>(queue: Queue<A>): Stream<never, A>;
4440
+ /**
4441
+ * Builds a stream that pulls from an async iterable — a Node `Readable`, a `ReadableStream`, a
4442
+ * `Response.body`, an async generator — one value at a time, only when the consumer asks: the
4443
+ * source is never read ahead.
4444
+ *
4445
+ * A `next()` that rejects, or an iterable that cannot give an iterator, fails the stream with
4446
+ * `liftE(error)`, or with the error itself (typed `unknown`) without `liftE`. When the stream
4447
+ * stops before the source ends — the consumer stops early, the run fails or is cancelled — the
4448
+ * iterator's `return()` is called, so the source can release what it holds (a Node `Readable` is
4449
+ * destroyed). It is called without waiting, so a source whose `return()` never settles cannot
4450
+ * hold the stream's end, a `timeout` or a cancellation; the source may still be closing when the
4451
+ * stream ends. A `return()` that fails is ignored. A source that ends by itself is not asked to
4452
+ * return.
4453
+ *
4454
+ * @template A The element type.
4455
+ * @template E The error type `liftE` produces.
4456
+ * @param source The async iterable to read.
4457
+ * @param liftE Turns a rejection of `next()` into an `E`.
4458
+ *
4459
+ * @example
4460
+ * const lines = Stream.fromAsync(readline.createInterface({ input: file }), toReadError);
4461
+ */
4462
+ static fromAsync<A>(source: AsyncIterable<A>): Stream<unknown, A>;
4463
+ static fromAsync<A, E>(source: AsyncIterable<A>, liftE: (e: unknown) => E): Stream<E, A>;
4204
4464
  /**
4205
4465
  * Builds a stream from a callback-based source. `register` attaches the listeners and receives
4206
4466
  * three synchronous functions — `emit` (a {@link Queue.unsafeOffer}), `end` (a
@@ -4210,7 +4470,11 @@ export declare class Stream<E, A> {
4210
4470
  *
4211
4471
  * Values are buffered in a bounded {@link Queue} (default capacity 1024, `OverflowStrategy.DropOldest`),
4212
4472
  * so a source that outpaces its consumer never grows memory without limit; a `Suspend` queue
4213
- * makes no sense here because `emit` is synchronous, so it is not offered.
4473
+ * makes no sense here because `emit` is synchronous, so it is not offered. `DropOldest` and
4474
+ * `DropNewest` lose values, so they suit signals where the newest value is enough (a position, a
4475
+ * status). For data that must arrive whole, pass a function as `onOverflow`: when the buffer is
4476
+ * full, the stream fails with the error it returns, after the values already buffered, and
4477
+ * `emit` returns `false` for that value and every later one. A function that throws is a defect.
4214
4478
  *
4215
4479
  * `register` runs when the stream starts — on the first pull of each **run** (each terminal
4216
4480
  * operation), not when `Stream.async` is called — so a value emitted before that point cannot
@@ -4228,17 +4492,29 @@ export declare class Stream<E, A> {
4228
4492
  * @template A The element type.
4229
4493
  * @template E The error type passed to `fail` (default `never`: a source that cannot fail).
4230
4494
  * @param register Attaches listeners; returns the detach effect, if any.
4231
- * @param options `capacity` (positive integer, default 1024) and `onOverflow` (default `OverflowStrategy.DropOldest`).
4495
+ * @param options `capacity` (positive integer, default 1024) and `onOverflow`: `OverflowStrategy.DropOldest`
4496
+ * (the default), `OverflowStrategy.DropNewest`, or a function from the capacity to the error to fail with.
4232
4497
  *
4233
4498
  * @example
4234
4499
  * const clicks = Stream.async<MouseEvent>((emit) => {
4235
4500
  * button.addEventListener("click", emit);
4236
4501
  * return IO.sync(() => button.removeEventListener("click", emit));
4237
4502
  * });
4503
+ *
4504
+ * @example
4505
+ * // An upload must arrive whole: fail instead of dropping chunks.
4506
+ * const chunks = Stream.async<Uint8Array, UploadError>(
4507
+ * (emit, end, fail) => {
4508
+ * request.on("data", emit);
4509
+ * request.on("end", end);
4510
+ * request.on("error", (e) => fail(toUploadError(e)));
4511
+ * },
4512
+ * { capacity: 64, onOverflow: () => ({ kind: "uploadTooFast" }) }
4513
+ * );
4238
4514
  */
4239
4515
  static async<A, E = never>(register: (emit: (a: A) => boolean, end: () => void, fail: (error: E) => void) => IO<never, void> | void, options?: {
4240
4516
  readonly capacity?: number;
4241
- readonly onOverflow?: Exclude<OverflowStrategy, typeof OverflowStrategy.Suspend>;
4517
+ readonly onOverflow?: Exclude<OverflowStrategy, typeof OverflowStrategy.Suspend> | ((capacity: number) => E);
4242
4518
  }): Stream<E, A>;
4243
4519
  /**
4244
4520
  * Transforms each emitted element with `f`. Lazy — nothing runs until the stream is consumed.
@@ -4380,6 +4656,11 @@ export declare class Stream<E, A> {
4380
4656
  * stream consumed by a fallible `f` is simply `IO<F, void>`).
4381
4657
  */
4382
4658
  runForEach<F>(f: (a: A) => IO<F, void>): IO<E | F, void>;
4659
+ /**
4660
+ * Runs `drive` over this stream in a new root scope, and closes the scope with how the run
4661
+ * ended. `drive` pulls until it decides to stop; stopping early is the end of the stream.
4662
+ */
4663
+ private runScoped;
4383
4664
  /**
4384
4665
  * Runs the stream purely for its effects, discarding emitted elements.
4385
4666
  */