@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.
- package/dist/monadyssey.d.ts +214 -74
- package/dist/monadyssey.mjs +252 -104
- package/dist/monadyssey.mjs.map +1 -1
- package/package.json +1 -1
- package/readme.md +4 -2
package/dist/monadyssey.d.ts
CHANGED
|
@@ -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
|
|
451
|
-
|
|
452
|
-
|
|
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
|
-
*
|
|
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
|
|
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
|
-
* @
|
|
905
|
-
* @
|
|
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
|
-
*
|
|
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
|
|
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
|
*
|