@openstage/monadyssey-core 3.0.0-rc.4 → 3.0.0-rc.5

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.
@@ -116,6 +116,25 @@ export declare abstract class Either<A, B> {
116
116
  * @returns The value of `Right` or `null`.
117
117
  */
118
118
  abstract getOrNull(): B | null;
119
+ /**
120
+ * Returns the value of this `Right`. For a `Left`, **throws**: use it to end a computation with a
121
+ * bug, a `Left` that the caller knows cannot happen. The thrown value is `toCause(left)`, or the
122
+ * left value itself without `toCause`; a primitive is wrapped in an `Error` that keeps it as
123
+ * `cause`, and whose message does not show it.
124
+ *
125
+ * It is a plain throw. Inside `IO.sync`, `map`, `flatMap` or `tap` it is a defect; inside
126
+ * `IO.lift`, `IO.cancellable`, `Either.catch` or a `forM` body with a `liftE`, it becomes a typed
127
+ * failure like any throw there. In those places use the effect form instead, which is a defect
128
+ * everywhere: `$(IO.from(either).orDefect())`.
129
+ *
130
+ * @param toCause - Builds what is thrown from the left value.
131
+ * @returns The value of this `Right`.
132
+ *
133
+ * @example
134
+ * // A port this program validated on startup.
135
+ * const port: number = Port.parse(env.PORT).getOrThrow((e) => new Error(`PORT was validated: ${e}`));
136
+ */
137
+ abstract getOrThrow(toCause?: (left: A) => unknown): B;
119
138
  /**
120
139
  * Swaps the `Left` and `Right` types.
121
140
  * @returns A new `Either` with the types swapped.
@@ -210,6 +229,11 @@ export declare interface Err<E> {
210
229
  readonly error: E;
211
230
  }
212
231
 
232
+ /** The error type of the `Err` case of `X`. */
233
+ declare type ErrorOf<X extends ReleaseExit<unknown, unknown>> = Extract<X, {
234
+ readonly type: "Err";
235
+ }>["error"];
236
+
213
237
  /**
214
238
  * `Eval` represents a deferred computation, which allows operations to be delayed, chained,
215
239
  * and lazily evaluated. It provides a foundation for creating different types of deferred operations
@@ -438,7 +462,8 @@ export declare const Exit: {
438
462
  /**
439
463
  * The handlers `Exit.fold` takes for an exit of type `X`: one for each case `X` can be, and none for
440
464
  * the others. A handler for a case `X` cannot be is refused, so `onDefect` belongs to a `ReleaseExit`
441
- * only, and `onCancelled` is refused for what `unsafeRun()` without a signal returns.
465
+ * only, and `onCancelled` is refused for what `unsafeRun()` without a signal returns. When the error
466
+ * type is `never`, no `Err` can exist, so `onErr` is optional.
442
467
  */
443
468
  declare type ExitHandlers<X extends ReleaseExit<unknown, unknown>, B> = ("Ok" extends X["type"] ? {
444
469
  readonly onOk: (value: Extract<X, {
@@ -446,10 +471,10 @@ declare type ExitHandlers<X extends ReleaseExit<unknown, unknown>, B> = ("Ok" ex
446
471
  }>["value"]) => B;
447
472
  } : {
448
473
  readonly onOk?: never;
449
- }) & ("Err" extends X["type"] ? {
450
- readonly onErr: (error: Extract<X, {
451
- readonly type: "Err";
452
- }>["error"]) => B;
474
+ }) & ("Err" extends X["type"] ? [ErrorOf<X>] extends [never] ? {
475
+ readonly onErr?: (error: never) => B;
476
+ } : {
477
+ readonly onErr: (error: ErrorOf<X>) => B;
453
478
  } : {
454
479
  readonly onErr?: never;
455
480
  }) & ("Cancelled" extends X["type"] ? {
@@ -749,6 +774,46 @@ export declare class IO<E, A> {
749
774
  * const result = await io.unsafeRun(); // { type: "Err", error: Error("something went wrong") }
750
775
  */
751
776
  static fail<E, A = never>(error: E): IO<E, A>;
777
+ /**
778
+ * Creates an IO that ends with a **defect** whose cause is `cause`: a bug that no caller can
779
+ * handle, such as an adapter that returns a value outside its contract. It is the counterpart of
780
+ * {@link IO.fail} for what is not an `E`, and the named form of a `throw` inside {@link IO.sync}.
781
+ *
782
+ * Nothing happens until the IO runs. Then it ends as a throw in `IO.sync` does: `unsafeRun()` and
783
+ * `join()` reject with `cause` itself, `onDefect` handlers and a `ReleaseExit` see a `Defect`, and
784
+ * no failure handler (`mapErr`, `flatMapErr`, `foldM`, `attempt`, `retry`, a `liftE`) sees it.
785
+ * Prefer an `Error` as the cause: it carries a stack trace.
786
+ *
787
+ * @template A The success type. It defaults to `never`; set it, or let a `fold` infer it, so
788
+ * that this IO has the type of the other branch.
789
+ * @param {unknown} cause What `unsafeRun()` and `join()` reject with.
790
+ * @returns {IO<never, A>} An IO that ends with a defect when it runs.
791
+ *
792
+ * @example
793
+ * // This program writes the settings file itself: a missing port is a bug, not a failure.
794
+ * const port: IO<never, number> = Option.ofNullable(settings.port).fold(
795
+ * () => IO.defect(new Error("The settings file has no port")),
796
+ * IO.of
797
+ * );
798
+ */
799
+ static defect<A = never>(cause: unknown): IO<never, A>;
800
+ /**
801
+ * Creates an IO that waits `ms` milliseconds, then succeeds with `undefined`.
802
+ *
803
+ * Nothing happens until the IO runs. The wait is cancellable: when the run is cancelled, the timer
804
+ * is cleared and the run ends as `Cancelled` at once. `retry` and `repeat` wait between attempts
805
+ * with the same timer.
806
+ *
807
+ * @param {number} ms How long to wait, in milliseconds. Must be a non-negative number: a negative or
808
+ * `NaN` time throws `RangeError` where it is written. A time above 2,147,483,647 ms (the
809
+ * `setTimeout` limit), including `Infinity`, is lowered to it instead of firing at once.
810
+ * @returns {IO<never, void>} An IO that succeeds after the wait.
811
+ *
812
+ * @example
813
+ * // Gives the device a second to restart before asking for its state.
814
+ * const state = device.restart().flatMap(() => IO.sleep(1000)).flatMap(() => device.state());
815
+ */
816
+ static sleep(ms: number): IO<never, void>;
752
817
  /**
753
818
  * Converts a value of another type into an `IO`. `from` is total: an `Either` carries its own
754
819
  * error, so it converts as-is; an `Option` has no error channel, so `onNone` must supply one.
@@ -891,39 +956,113 @@ export declare class IO<E, A> {
891
956
  * .flatMapErr(httpErr => refreshTokenThen(httpErr).mapErr(toDomainError));
892
957
  */
893
958
  flatMapErr<F>(f: (error: E) => IO<F, A>): IO<F, A>;
959
+ /**
960
+ * Turns every failure of this IO into a **defect** (see {@link IO.defect}), for a failure the
961
+ * caller knows cannot happen: a validation with a port that cannot refuse, a parse of a value
962
+ * this program wrote. The cause is `toCause(error)`, or the error itself without `toCause`.
963
+ *
964
+ * Success, cancellation and existing defects pass through unchanged. A handler before
965
+ * `orDefect` (a `retry`, say) still sees the failure; one after it sees nothing. A `toCause`
966
+ * that throws makes its own exception the defect.
967
+ *
968
+ * @param {(error: E) => unknown} [toCause] Builds the defect's cause from the error. Prefer one
969
+ * that returns an `Error`, for its stack trace.
970
+ * @returns {IO<never, A>} The same IO, with no failure left in its type.
971
+ *
972
+ * @example
973
+ * const config: IO<never, Config> = readBundledConfig() // IO<ParseError, Config>
974
+ * .orDefect((e) => new Error(`The bundled config does not parse: ${e.reason}`));
975
+ */
976
+ orDefect(toCause?: (error: E) => unknown): IO<never, A>;
977
+ /**
978
+ * Turns every failure into a value. The result cannot fail: what went wrong becomes part of the
979
+ * value, as `null`, a default or a state that describes the problem.
980
+ *
981
+ * Success, cancellation and defects pass through unchanged. A handler that throws makes its own
982
+ * exception a defect. The handler returns a plain value: a handler that returns an `IO` is
983
+ * refused at compile time, because that recovery is {@link IO.flatMapErr}.
984
+ *
985
+ * @template B The type of the value the handler returns.
986
+ * @param {(error: E) => B} f Builds the value from the error.
987
+ * @returns {IO<never, A | B>} An IO that succeeds with this IO's value or with the handler's.
988
+ *
989
+ * @example
990
+ * const invitations: IO<never, InvitationList> = account
991
+ * .myInvitations()
992
+ * .map(({ invitations }) => ({ invitations, problem: null }))
993
+ * .recover((problem) => ({ invitations: [], problem: describe(problem) }));
994
+ */
995
+ recover<B>(f: (error: E) => B & NotAnIO<B>): IO<never, A | B>;
996
+ /**
997
+ * Handles the failures `guard` accepts with `f`, and fails again with every other one, unchanged.
998
+ * The handled case leaves the error type: the result fails with what the guard refused, or with
999
+ * the handler's own error type `F`.
1000
+ *
1001
+ * Success, cancellation and defects pass through unchanged, and neither `guard` nor `f` is called.
1002
+ * A `guard` or `f` that throws makes its own exception a defect. `guard` must be a type guard: a
1003
+ * plain boolean predicate cannot narrow the error type, and {@link IO.flatMapErr} covers that case.
1004
+ *
1005
+ * @template E1 The case of `E` that `guard` accepts.
1006
+ * @template F The error type of the handler's IO.
1007
+ * @template B The value type of the handler's IO.
1008
+ * @param {(error: E) => error is E1} guard Decides which failures `f` handles.
1009
+ * @param {(error: E1) => IO<F, B>} f Recovers from a failure the guard accepted.
1010
+ * @returns {IO<Exclude<E, E1> | F, A | B>} An IO without the handled case in its error type.
1011
+ *
1012
+ * @example
1013
+ * const saved: IO<NotFound | Refused, Account> = repository
1014
+ * .save(account) // IO<NotFound | VersionConflict, Account>
1015
+ * .recoverIf(isVersionConflict, () => IO.fail(refused("ChangedMeanwhile")));
1016
+ */
1017
+ recoverIf<E1 extends E, F, B>(guard: (error: E) => error is E1, f: (error: E1) => IO<F, B>): IO<Exclude<E, E1> | F, A | B>;
894
1018
  /**
895
1019
  * Executes a side-effect on the success value without changing the result.
896
- * If this IO fails, the function is not called. The callback may be synchronous
897
- * or asynchronous — the interpreter awaits if it returns a Promise.
1020
+ * If this IO fails, the function is not called. The callback may be synchronous, return a
1021
+ * Promise (the interpreter awaits it), or return an `IO`.
1022
+ *
1023
+ * A returned `IO` runs as part of this run, with the same cancellation: its value is dropped,
1024
+ * and its failure fails the run, so the error type widens to `E | F`.
898
1025
  *
899
1026
  * If the side-effect throws or rejects, that is a **defect**, as a throw in `map` is: it is not
900
1027
  * an `E`, and `unsafeRun()` rejects with it. For a side effect that may fail and whose failure
901
- * should be ignored, catch it inside the callback; for one whose failure is an `E`, use
902
- * `flatMap` with an `IO.lift(f, liftE)`.
1028
+ * should be ignored, catch it inside the callback, or return an `IO` that ends with `ignore()`.
903
1029
  *
904
- * @param {(a: A) => void | Promise<void>} f The side-effect function.
905
- * @returns {IO<E, A>} A new IO that performs the side-effect but preserves the original result.
1030
+ * @template F The error type of a returned `IO`; `never` for a plain or async callback.
1031
+ * @param {(a: A) => void | Promise<void> | IO<F, unknown>} f The side-effect function.
1032
+ * @returns {IO<E | F, A>} A new IO that performs the side-effect but preserves the original result.
906
1033
  *
907
1034
  * @example
908
1035
  * const io = IO.of(42).tap(value => console.log("Got:", value));
1036
+ *
1037
+ * @example
1038
+ * // A side effect that is itself an IO.
1039
+ * const saved = save(order).tap((saved) => log.info(`order.saved.${saved.id}`));
909
1040
  */
910
- tap(f: (a: A) => void | Promise<void>): IO<E, A>;
1041
+ tap<F = never>(f: (a: A) => void | Promise<void> | IO<F, unknown>): IO<E | F, A>;
911
1042
  /**
912
1043
  * Executes a side-effect on the error value without changing the result.
913
- * If this IO succeeds, the function is not called. The callback may be synchronous
914
- * or asynchronous — the interpreter awaits if it returns a Promise.
1044
+ * If this IO succeeds, the function is not called. The callback may be synchronous, return a
1045
+ * Promise (the interpreter awaits it), or return an `IO` that cannot fail.
1046
+ *
1047
+ * A returned `IO` runs as part of this run, with the same cancellation; when it ends, the
1048
+ * original error continues. Its type is `IO<never, unknown>`, so it can never replace that error:
1049
+ * end an `IO` that can fail with `ignore()` first.
915
1050
  *
916
1051
  * If the side-effect throws or rejects, that is a **defect**, as a throw in `mapErr` is: it does
917
1052
  * not replace the error, and `unsafeRun()` rejects with it. For a side effect that may fail and
918
1053
  * whose failure should be ignored, catch it inside the callback.
919
1054
  *
920
- * @param {(e: E) => void | Promise<void>} f The side-effect function.
1055
+ * @param {(e: E) => void | Promise<void> | IO<never, unknown>} f The side-effect function.
921
1056
  * @returns {IO<E, A>} A new IO that performs the side-effect but preserves the original error.
922
1057
  *
923
1058
  * @example
924
1059
  * const io = IO.fail(new Error("boom")).tapErr(e => logger.error(e));
1060
+ *
1061
+ * @example
1062
+ * // A log call that is itself an IO.
1063
+ * const checked = passkey.verify(request).tapErr((failure) => log.warn(`passkey.refused.${failure.reason}`));
925
1064
  */
926
- tapErr(f: (e: E) => void | Promise<void>): IO<E, A>;
1065
+ tapErr(f: (e: E) => void | Promise<void> | IO<never, unknown>): IO<E, A>;
927
1066
  /**
928
1067
  * Validates the success value against a type guard (Cats `ensure`). When the guard holds, the
929
1068
  * success channel is narrowed to `B`; when it does not, the value is converted into an error
@@ -1022,9 +1161,9 @@ export declare class IO<E, A> {
1022
1161
  */
1023
1162
  ignore(): IO<never, void>;
1024
1163
  /**
1025
- * Executes the computation described by this IO and returns the result.
1026
- * The interpreter walks the ADT tree using an explicit stack (trampoline),
1027
- * ensuring stack safety for arbitrarily deep chains.
1164
+ * Executes the computation described by this IO and returns the result. It is the only way to
1165
+ * run an IO: call it at the edge of the program. The interpreter walks the ADT tree using an
1166
+ * explicit stack (trampoline), ensuring stack safety for arbitrarily deep chains.
1028
1167
  *
1029
1168
  * The promise resolves with `Ok` or `Err` (an `E`). It **rejects** only on a defect — an
1030
1169
  * exception from an effect or callback that was not declared fallible — with the original
@@ -1042,6 +1181,10 @@ export declare class IO<E, A> {
1042
1181
  * // result: { type: "Ok", value: 42 }
1043
1182
  *
1044
1183
  * @example
1184
+ * // A value or null at the edge: recover first, so the run cannot fail and needs no onErr.
1185
+ * const user = Exit.fold(await findUser(id).recover(() => null).unsafeRun(), { onOk: (u) => u });
1186
+ *
1187
+ * @example
1045
1188
  * // Stop the work when the client disconnects.
1046
1189
  * const exit = await handle(request).unsafeRun({ signal: request.signal });
1047
1190
  * if (exit.type === "Cancelled") return;
@@ -1051,61 +1194,6 @@ export declare class IO<E, A> {
1051
1194
  readonly signal: AbortSignal;
1052
1195
  }): Promise<Exit<E, A>>;
1053
1196
  unsafeRun(): Promise<Err<E> | Ok<A>>;
1054
- /**
1055
- * Executes the IO and folds both outcomes (success and error) into a single type.
1056
- * This is a terminal operation — it runs the computation and returns a plain value.
1057
- *
1058
- * @template B The result type after folding.
1059
- * @param {(e: E) => B} onErr Handler for the error case.
1060
- * @param {(a: A) => B} onOk Handler for the success case.
1061
- * @returns {Promise<B>} The folded result.
1062
- *
1063
- * @example
1064
- * const message = await IO.of(42).fold(
1065
- * err => `Failed: ${err}`,
1066
- * val => `Got: ${val}`
1067
- * );
1068
- * // message: "Got: 42"
1069
- */
1070
- fold<B>(onErr: (e: E) => B, onOk: (a: A) => B): Promise<B>;
1071
- /**
1072
- * Executes the IO and returns the success value, or `null` if the computation fails.
1073
- *
1074
- * Note: if `A` itself can be `null`, the return value is ambiguous — a `null` result
1075
- * could mean either "succeeded with null" or "failed." Use `unsafeRun()` or `fold`
1076
- * when the distinction matters.
1077
- *
1078
- * @returns {Promise<A | null>} The success value or null.
1079
- *
1080
- * @example
1081
- * const value = await IO.of(42).getOrNull(); // 42
1082
- * const nope = await IO.fail("err").getOrNull(); // null
1083
- */
1084
- getOrNull(): Promise<A | null>;
1085
- /**
1086
- * Executes the IO and returns the success value, or evaluates the provided
1087
- * default function on error. The default is lazy to avoid unnecessary computation.
1088
- *
1089
- * @param {() => A} defaultValue A function that produces the fallback value.
1090
- * @returns {Promise<A>} The success value or the default.
1091
- *
1092
- * @example
1093
- * const value = await IO.fail("err").getOrElse(() => 0); // 0
1094
- */
1095
- getOrElse<B>(defaultValue: () => B): Promise<A | B>;
1096
- /**
1097
- * Executes the IO and returns the success value, or applies the handler
1098
- * function to the error to produce a fallback value.
1099
- *
1100
- * @param {(error: E) => A} handler A function that transforms the error into a success value.
1101
- * @returns {Promise<A>} The success value or the handled error.
1102
- *
1103
- * @example
1104
- * const value = await IO.fail(new Error("boom"))
1105
- * .getOrHandleErr(e => `Handled: ${e.message}`);
1106
- * // value: "Handled: boom"
1107
- */
1108
- getOrHandleErr<B>(handler: (error: E) => B): Promise<A | B>;
1109
1197
  /**
1110
1198
  * Runs this IO again after a failure, as the {@link Schedule} allows. Succeeds with the first
1111
1199
  * success; otherwise fails with the **last error, as-is** — once the schedule's attempts are
@@ -1415,6 +1503,7 @@ export declare class Left<A> extends Either<A, never> {
1415
1503
  flatMap<F, C>(_: (right: never) => Either<F, C>): Either<A | F, C>;
1416
1504
  getOrElse(defaultValue: (left: A) => never): never;
1417
1505
  getOrNull(): null;
1506
+ getOrThrow(toCause?: (left: A) => unknown): never;
1418
1507
  swap(): Either<never, A>;
1419
1508
  fold<C>(ifLeft: (left: A) => C, _: (right: never) => C): C;
1420
1509
  tap(_: (right: never) => void): Either<A, never>;
@@ -2232,6 +2321,7 @@ export declare class None extends Option<never> {
2232
2321
  fold<B>(ifNone: () => B, _: (right: never) => B): B;
2233
2322
  getOrElse(defaultValue: () => never): never;
2234
2323
  getOrNull(): null;
2324
+ getOrThrow(toCause?: () => unknown): never;
2235
2325
  tap(_: (value: never) => void): Option<never>;
2236
2326
  tapNone(f: () => void): Option<never>;
2237
2327
  }
@@ -2893,6 +2983,12 @@ export declare class NonEmptyList<A> {
2893
2983
  toJSON(): A[];
2894
2984
  }
2895
2985
 
2986
+ /**
2987
+ * `unknown` when no part of `B` is an `IO`, `never` otherwise. Intersected with a callback's return
2988
+ * type, it refuses a callback that returns an `IO` where a plain value is expected.
2989
+ */
2990
+ declare type NotAnIO<B> = [Extract<B, IO<unknown, unknown>>] extends [never] ? unknown : never;
2991
+
2896
2992
  /**
2897
2993
  * A body result that is not a promise: an `async` body would return before its `$` calls ran, so
2898
2994
  * `forM` rejects it at compile time (and with a `TypeError` at run time).
@@ -3079,6 +3175,21 @@ export declare abstract class Option<A> {
3079
3175
  *
3080
3176
  */
3081
3177
  abstract getOrElse(defaultValue: () => A): A;
3178
+ /**
3179
+ * Returns the contained value. For `None`, **throws**: use it to end a computation with a bug, a
3180
+ * missing value that the caller knows cannot happen. The thrown value is `toCause()`, or an
3181
+ * `Error` that says the `Option` is `None` without `toCause`; a primitive is wrapped in an
3182
+ * `Error` that keeps it as `cause`.
3183
+ *
3184
+ * It is a plain throw. Inside `IO.sync`, `map`, `flatMap` or `tap` it is a defect; inside
3185
+ * `IO.lift`, `IO.cancellable`, `Either.catch` or a `forM` body with a `liftE`, it becomes a typed
3186
+ * failure like any throw there. In those places use the effect form instead, which is a defect
3187
+ * everywhere: `$(IO.from(option, () => missing).orDefect())`.
3188
+ *
3189
+ * @example
3190
+ * const admin = Option.ofNullable(seed.admin).getOrThrow(() => new Error("The seed data has no admin"));
3191
+ */
3192
+ abstract getOrThrow(toCause?: () => unknown): A;
3082
3193
  }
3083
3194
 
3084
3195
  /**
@@ -4437,6 +4548,19 @@ export declare class Resource<E, A> {
4437
4548
  * const pool = Resource.make(openPool(config), closePool).mapErr((e) => new StartFailure("db", e));
4438
4549
  */
4439
4550
  mapErr<F>(f: (e: E) => F): Resource<F, A>;
4551
+ /**
4552
+ * Turns every failure to open into a **defect** (see {@link IO.defect}), for an open the caller
4553
+ * knows cannot fail. The cause is `toCause(error)`, or the error itself without `toCause`. What
4554
+ * was already open closes with a `Defect` exit. The use's own failure is not touched.
4555
+ *
4556
+ * @param {(e: E) => unknown} [toCause] Builds the defect's cause from the error.
4557
+ * @returns {Resource<never, A>}
4558
+ *
4559
+ * @example
4560
+ * const cache = Resource.make(openInMemoryCache(), closeCache) // Resource<CacheError, Cache>
4561
+ * .orDefect((e) => new Error(`An in-memory cache cannot fail to open: ${e.kind}`));
4562
+ */
4563
+ orDefect(toCause?: (e: E) => unknown): Resource<never, A>;
4440
4564
  }
4441
4565
 
4442
4566
  /** The error type of a resource; distributes over a union of resources. */
@@ -4466,6 +4590,7 @@ export declare class Right<B> extends Either<never, B> {
4466
4590
  flatMap<F, C>(f: (right: B) => Either<F, C>): Either<F, C>;
4467
4591
  getOrElse(_: (left: never) => B): B;
4468
4592
  getOrNull(): B;
4593
+ getOrThrow(_?: (left: never) => unknown): B;
4469
4594
  swap(): Either<B, never>;
4470
4595
  fold<C>(_: (left: never) => C, ifRight: (right: B) => C): C;
4471
4596
  tap(action: (right: B) => void): Either<never, B>;
@@ -4600,6 +4725,7 @@ export declare class Some<A> extends Option<NonNullable<A>> {
4600
4725
  fold<B>(_: () => B, ifSome: (right: NonNullable<A>) => B): B;
4601
4726
  getOrElse(_: () => NonNullable<A>): NonNullable<A>;
4602
4727
  getOrNull(): NonNullable<A>;
4728
+ getOrThrow(_?: () => unknown): NonNullable<A>;
4603
4729
  tap(f: (value: NonNullable<A>) => void): Option<NonNullable<A>>;
4604
4730
  tapNone(_: () => void): Option<NonNullable<A>>;
4605
4731
  }
@@ -4790,6 +4916,20 @@ export declare class Stream<E, A> {
4790
4916
  * Transforms the error channel with `f`, leaving emitted elements unchanged.
4791
4917
  */
4792
4918
  mapErr<F>(f: (e: E) => F): Stream<F, A>;
4919
+ /**
4920
+ * Turns every failure of this stream into a **defect** (see {@link IO.defect}), for a failure the
4921
+ * caller knows cannot happen. The cause is `toCause(error)`, or the error itself without
4922
+ * `toCause`. Elements emitted before the failure are emitted as usual; finalizers and `bracket`
4923
+ * releases receive a `Defect` exit.
4924
+ *
4925
+ * @param {(error: E) => unknown} [toCause] Builds the defect's cause from the error.
4926
+ * @returns {Stream<never, A>} The same stream, with no failure left in its type.
4927
+ *
4928
+ * @example
4929
+ * // Reading a file bundled with the program cannot fail unless the build is broken.
4930
+ * const lines: Stream<never, string> = Stream.fromAsync(bundledLines()).orDefect();
4931
+ */
4932
+ orDefect(toCause?: (error: E) => unknown): Stream<never, A>;
4793
4933
  /**
4794
4934
  * Keeps only the elements for which the type guard holds. The element type is narrowed to `B`.
4795
4935
  *