@openstage/monadyssey-core 3.0.0-rc.3 → 3.0.0-rc.4
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 +298 -32
- package/dist/monadyssey.mjs +314 -34
- package/dist/monadyssey.mjs.map +1 -1
- package/package.json +1 -1
- package/readme.md +5 -0
package/dist/monadyssey.d.ts
CHANGED
|
@@ -174,21 +174,21 @@ export declare abstract class Either<A, B> {
|
|
|
174
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
175
|
/**
|
|
176
176
|
* Monadic comprehension ("monadic for") over `Either`, synchronous. Inside `operation`,
|
|
177
|
-
*
|
|
177
|
+
* `$(either)` returns the `Right` value; the first `Left` stops the body, and `forM` returns
|
|
178
178
|
* that `Left`. The body's return value becomes the `Right`. An exception that is not a `Left`
|
|
179
179
|
* is not caught: it propagates from `forM`. Use {@link forA} to collect every `Left` instead.
|
|
180
180
|
*
|
|
181
|
-
*
|
|
181
|
+
* `$` stops the body by throwing, so a `try` / `catch` in the body must rethrow what it does
|
|
182
182
|
* not handle, and the body must be synchronous.
|
|
183
183
|
*
|
|
184
184
|
* @example
|
|
185
|
-
* const total = Either.forM<ParseError, number>((
|
|
186
|
-
* const price =
|
|
187
|
-
* const quantity =
|
|
185
|
+
* const total = Either.forM<ParseError, number>(($) => {
|
|
186
|
+
* const price = $(parsePrice(input.price));
|
|
187
|
+
* const quantity = $(parseQuantity(input.quantity));
|
|
188
188
|
* return price * quantity;
|
|
189
189
|
* });
|
|
190
190
|
*/
|
|
191
|
-
static forM<E, A>(operation: (
|
|
191
|
+
static forM<E, A>(operation: ($: <B>(either: Either<E, B>) => B) => A & NotThenable): Either<E, A>;
|
|
192
192
|
}
|
|
193
193
|
|
|
194
194
|
/**
|
|
@@ -399,6 +399,69 @@ export declare class EvaluationError<E> extends Error {
|
|
|
399
399
|
*/
|
|
400
400
|
export declare type Exit<E, A> = Ok<A> | Err<E> | Cancelled;
|
|
401
401
|
|
|
402
|
+
export declare const Exit: {
|
|
403
|
+
/**
|
|
404
|
+
* Maps each case of an exit to a single type. Every case the exit's type can be needs a handler, so
|
|
405
|
+
* a missing one is a compile error: an `Exit` takes `onOk`, `onErr` and `onCancelled`, a
|
|
406
|
+
* `ReleaseExit` also takes `onDefect`, and what `unsafeRun()` without a signal returns takes `onOk`
|
|
407
|
+
* and `onErr` only.
|
|
408
|
+
*
|
|
409
|
+
* @template X The type of the exit.
|
|
410
|
+
* @template B The result type of every handler.
|
|
411
|
+
* @param {X} exit The exit to fold: what `unsafeRun()` or `fiber.join()` resolves to, or what a
|
|
412
|
+
* `bracket` release receives.
|
|
413
|
+
* @param handlers One handler for each case of `X`.
|
|
414
|
+
* @returns {B} What the handler of the exit's case returns.
|
|
415
|
+
* @throws {TypeError} When `exit` is not an exit: its `type` is not `Ok`, `Err`, `Cancelled` or `Defect`.
|
|
416
|
+
*
|
|
417
|
+
* @example
|
|
418
|
+
* const status = Exit.fold(await fiber.join(), {
|
|
419
|
+
* onOk: (user) => `loaded ${user.id}`,
|
|
420
|
+
* onErr: (error) => `failed: ${error.message}`,
|
|
421
|
+
* onCancelled: () => "stopped",
|
|
422
|
+
* });
|
|
423
|
+
*
|
|
424
|
+
* @example
|
|
425
|
+
* // A bracket release that acts on how `use` ended.
|
|
426
|
+
* IO.bracket(connect(), work, (conn, exit) =>
|
|
427
|
+
* Exit.fold(exit, {
|
|
428
|
+
* onOk: () => IO.sync(() => conn.release()),
|
|
429
|
+
* onErr: () => rollback(conn),
|
|
430
|
+
* onCancelled: () => IO.sync(() => conn.destroy()),
|
|
431
|
+
* onDefect: () => IO.sync(() => conn.destroy()),
|
|
432
|
+
* })
|
|
433
|
+
* );
|
|
434
|
+
*/
|
|
435
|
+
fold: <X extends ReleaseExit<unknown, unknown>, B>(exit: X, handlers: ExitHandlers<X, B>) => B;
|
|
436
|
+
};
|
|
437
|
+
|
|
438
|
+
/**
|
|
439
|
+
* The handlers `Exit.fold` takes for an exit of type `X`: one for each case `X` can be, and none for
|
|
440
|
+
* 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.
|
|
442
|
+
*/
|
|
443
|
+
declare type ExitHandlers<X extends ReleaseExit<unknown, unknown>, B> = ("Ok" extends X["type"] ? {
|
|
444
|
+
readonly onOk: (value: Extract<X, {
|
|
445
|
+
readonly type: "Ok";
|
|
446
|
+
}>["value"]) => B;
|
|
447
|
+
} : {
|
|
448
|
+
readonly onOk?: never;
|
|
449
|
+
}) & ("Err" extends X["type"] ? {
|
|
450
|
+
readonly onErr: (error: Extract<X, {
|
|
451
|
+
readonly type: "Err";
|
|
452
|
+
}>["error"]) => B;
|
|
453
|
+
} : {
|
|
454
|
+
readonly onErr?: never;
|
|
455
|
+
}) & ("Cancelled" extends X["type"] ? {
|
|
456
|
+
readonly onCancelled: () => B;
|
|
457
|
+
} : {
|
|
458
|
+
readonly onCancelled?: never;
|
|
459
|
+
}) & ("Defect" extends X["type"] ? {
|
|
460
|
+
readonly onDefect: () => B;
|
|
461
|
+
} : {
|
|
462
|
+
readonly onDefect?: never;
|
|
463
|
+
});
|
|
464
|
+
|
|
402
465
|
export declare interface Fiber<E, A> {
|
|
403
466
|
/**
|
|
404
467
|
* Wait for the computation to complete. Rejects with the original exception on a defect. A
|
|
@@ -1151,8 +1214,8 @@ export declare class IO<E, A> {
|
|
|
1151
1214
|
* @returns {IO<never, Fiber<E, A>>} An IO that, when executed, starts this IO and returns a Fiber.
|
|
1152
1215
|
*
|
|
1153
1216
|
* @example
|
|
1154
|
-
* const io = IO.forM<AppError, string>(async
|
|
1155
|
-
* const fiber = await
|
|
1217
|
+
* const io = IO.forM<AppError, string>(async ($) => {
|
|
1218
|
+
* const fiber = await $(longRunningTask.fork());
|
|
1156
1219
|
* // ... do other work ...
|
|
1157
1220
|
* const outcome = await fiber.join(); // Ok | Err | Cancelled
|
|
1158
1221
|
* return outcome.type === "Ok" ? outcome.value : "unavailable";
|
|
@@ -1225,13 +1288,13 @@ export declare class IO<E, A> {
|
|
|
1225
1288
|
static race<E, A>(...ops: IO<E, A>[]): IO<NonEmptyList<E>, A>;
|
|
1226
1289
|
/**
|
|
1227
1290
|
* Monadic for-comprehension ("monadic for"). Sequences dependent IO operations using an
|
|
1228
|
-
* imperative-style
|
|
1291
|
+
* imperative-style `$` function that unwraps IO values or short-circuits on the first
|
|
1229
1292
|
* error. This is the sequential, fail-fast counterpart to the applicative {@link forA}
|
|
1230
1293
|
* (which runs independent IOs in parallel and accumulates all errors).
|
|
1231
1294
|
*
|
|
1232
|
-
* Inside the `operation` callback, call
|
|
1295
|
+
* Inside the `operation` callback, call `$(io)` to execute an IO and extract its
|
|
1233
1296
|
* success value. If any bound IO fails, the whole comprehension short-circuits with that
|
|
1234
|
-
* error — subsequent
|
|
1297
|
+
* error — subsequent `$` calls are not executed.
|
|
1235
1298
|
*
|
|
1236
1299
|
* Uses an `IOEscape` sentinel internally to preserve the typed error `E` through
|
|
1237
1300
|
* JavaScript's throw/catch mechanism, ensuring the error channel remains type-safe.
|
|
@@ -1242,19 +1305,19 @@ export declare class IO<E, A> {
|
|
|
1242
1305
|
*
|
|
1243
1306
|
* @template E The error type shared by all bound IO operations.
|
|
1244
1307
|
* @template A The final success type produced by the comprehension.
|
|
1245
|
-
* @param {(
|
|
1246
|
-
* An async function that receives a
|
|
1308
|
+
* @param {($: <B>(effect: IO<E, B>) => Promise<B>) => Promise<A>} operation
|
|
1309
|
+
* An async function that receives a `$` callback for unwrapping IO values.
|
|
1247
1310
|
* @param {(e: unknown) => E} [liftE] Optional function to transform non-IO exceptions into E.
|
|
1248
1311
|
* @returns {IO<E, A>} An IO that, when executed, runs the comprehension.
|
|
1249
1312
|
*
|
|
1250
1313
|
* @example
|
|
1251
|
-
* const io = IO.forM<AppError, number>(async
|
|
1252
|
-
* const user = await
|
|
1253
|
-
* const orders = await
|
|
1314
|
+
* const io = IO.forM<AppError, number>(async ($) => {
|
|
1315
|
+
* const user = await $(fetchUser(userId));
|
|
1316
|
+
* const orders = await $(fetchOrders(user.id));
|
|
1254
1317
|
* return orders.length;
|
|
1255
1318
|
* });
|
|
1256
1319
|
*/
|
|
1257
|
-
static forM<E, A>(operation: (
|
|
1320
|
+
static forM<E, A>(operation: ($: <B>(effect: IO<E, B>) => Promise<B>) => Promise<A>, liftE?: (e: unknown) => E): IO<E, A>;
|
|
1258
1321
|
/**
|
|
1259
1322
|
* Sequentially executes a function over each item, collecting results into an array.
|
|
1260
1323
|
* Fail-fast: if any invocation fails, the remaining items are not processed and the
|
|
@@ -2831,7 +2894,7 @@ export declare class NonEmptyList<A> {
|
|
|
2831
2894
|
}
|
|
2832
2895
|
|
|
2833
2896
|
/**
|
|
2834
|
-
* A body result that is not a promise: an `async` body would return before its
|
|
2897
|
+
* A body result that is not a promise: an `async` body would return before its `$` calls ran, so
|
|
2835
2898
|
* `forM` rejects it at compile time (and with a `TypeError` at run time).
|
|
2836
2899
|
*/
|
|
2837
2900
|
declare type NotThenable = {
|
|
@@ -2975,21 +3038,21 @@ export declare abstract class Option<A> {
|
|
|
2975
3038
|
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
3039
|
/**
|
|
2977
3040
|
* Monadic comprehension ("monadic for") over `Option`, synchronous. Inside `operation`,
|
|
2978
|
-
*
|
|
3041
|
+
* `$(option)` returns the `Some` value; the first `None` stops the body, and `forM` returns
|
|
2979
3042
|
* `None`. The body's return value becomes the result, `None` when it is `null` or `undefined`.
|
|
2980
3043
|
* An exception is not caught: it propagates from `forM`.
|
|
2981
3044
|
*
|
|
2982
|
-
*
|
|
3045
|
+
* `$` stops the body by throwing, so a `try` / `catch` in the body must rethrow what it does
|
|
2983
3046
|
* not handle, and the body must be synchronous.
|
|
2984
3047
|
*
|
|
2985
3048
|
* @example
|
|
2986
|
-
* const city = Option.forM((
|
|
2987
|
-
* const user =
|
|
2988
|
-
* const address =
|
|
3049
|
+
* const city = Option.forM(($) => {
|
|
3050
|
+
* const user = $(findUser(id));
|
|
3051
|
+
* const address = $(user.address);
|
|
2989
3052
|
* return address.city;
|
|
2990
3053
|
* }); // Option<string>
|
|
2991
3054
|
*/
|
|
2992
|
-
static forM<A>(operation: (
|
|
3055
|
+
static forM<A>(operation: ($: <B>(option: Option<B>) => B) => A & NotThenable): Option<NonNullable<A>>;
|
|
2993
3056
|
/**
|
|
2994
3057
|
* Applies one of two provided functions based on the contents of this `Option`.
|
|
2995
3058
|
* If it is `None`, it applies `ifNone`. If it is `Some`, it applies `ifSome`.
|
|
@@ -3675,11 +3738,11 @@ export declare type Pipe<E, A, B> = (stream: Stream<E, A>) => Stream<E, B>;
|
|
|
3675
3738
|
*
|
|
3676
3739
|
* @example
|
|
3677
3740
|
* // Turn an EventEmitter into a Stream
|
|
3678
|
-
* const program = IO.forM<never, void>(async (
|
|
3679
|
-
* const queue = await
|
|
3741
|
+
* const program = IO.forM<never, void>(async ($) => {
|
|
3742
|
+
* const queue = await $(Queue.bounded<Message>(1024, OverflowStrategy.DropOldest));
|
|
3680
3743
|
* emitter.on("message", (m) => queue.unsafeOffer(m));
|
|
3681
3744
|
* emitter.once("close", () => queue.unsafeClose());
|
|
3682
|
-
* await
|
|
3745
|
+
* await $(Stream.from(queue).runForEach((m) => handle(m)));
|
|
3683
3746
|
* });
|
|
3684
3747
|
*/
|
|
3685
3748
|
export declare class Queue<in out A> {
|
|
@@ -4087,11 +4150,11 @@ declare type ReaderValue<T> = T extends Reader<never, infer A> ? A : never;
|
|
|
4087
4150
|
* @typeParam A The type of the value held in the cell.
|
|
4088
4151
|
*
|
|
4089
4152
|
* @example
|
|
4090
|
-
* const program = IO.forM<never, number>(async (
|
|
4091
|
-
* const counter = await
|
|
4092
|
-
* await
|
|
4093
|
-
* await
|
|
4094
|
-
* return
|
|
4153
|
+
* const program = IO.forM<never, number>(async ($) => {
|
|
4154
|
+
* const counter = await $(Ref.of(0));
|
|
4155
|
+
* await $(counter.update((n) => n + 1));
|
|
4156
|
+
* await $(counter.update((n) => n + 1));
|
|
4157
|
+
* return $(counter.get());
|
|
4095
4158
|
* });
|
|
4096
4159
|
* await program.unsafeRun(); // { type: "Ok", value: 2 }
|
|
4097
4160
|
*/
|
|
@@ -4179,6 +4242,209 @@ export declare class Ref<in out A> {
|
|
|
4179
4242
|
/** How the `use` step of a `bracket` ended, as its release receives it. */
|
|
4180
4243
|
export declare type ReleaseExit<E, A> = Exit<E, A> | Defect;
|
|
4181
4244
|
|
|
4245
|
+
/**
|
|
4246
|
+
* A resource that opens with an effect and closes with another: a database pool, an HTTP server, a
|
|
4247
|
+
* worker queue. A `Resource` is a description, like an {@link IO}: nothing opens until {@link use}
|
|
4248
|
+
* runs, and each `use` opens its own copy.
|
|
4249
|
+
*
|
|
4250
|
+
* Resources compose with {@link flatMap}, {@link zip} and {@link forM}. `use` opens them in order,
|
|
4251
|
+
* runs its body, and then closes them in reverse order, whatever happened: success, failure, defect
|
|
4252
|
+
* or cancellation. Each open stays next to its close, and the close order follows from the open
|
|
4253
|
+
* order.
|
|
4254
|
+
*
|
|
4255
|
+
* For one resource used inside one step, {@link IO.bracket} is enough. A `Resource` is for several
|
|
4256
|
+
* resources that live as long as a process.
|
|
4257
|
+
*
|
|
4258
|
+
* @typeParam E The error type of opening.
|
|
4259
|
+
* @typeParam A The value the resource gives to its use.
|
|
4260
|
+
*
|
|
4261
|
+
* @example
|
|
4262
|
+
* const server = Resource.forM<StartFailure, RunningServer>(async ($) => {
|
|
4263
|
+
* const db = await $(Resource.make(openPool(config), (pool) => closePool(pool)));
|
|
4264
|
+
* const http = await $(Resource.make(listen(db), (server) => stopListening(server)));
|
|
4265
|
+
* return { db, http };
|
|
4266
|
+
* });
|
|
4267
|
+
*
|
|
4268
|
+
* // Closes the HTTP server first, then the pool.
|
|
4269
|
+
* await server.use(() => untilSignal).unsafeRun();
|
|
4270
|
+
*/
|
|
4271
|
+
export declare class Resource<E, A> {
|
|
4272
|
+
private readonly open;
|
|
4273
|
+
/** Build a `Resource` through its static constructors: `Resource.make`, `Resource.of`, `Resource.eval`. */
|
|
4274
|
+
private constructor();
|
|
4275
|
+
/**
|
|
4276
|
+
* A resource that opens with `acquire` and closes with `release`. `release` learns how the use
|
|
4277
|
+
* ended: `Ok` with the use's value, `Err` with its error, `Cancelled`, or `Defect`. When a later
|
|
4278
|
+
* resource fails to open, `release` receives that `Err`.
|
|
4279
|
+
*
|
|
4280
|
+
* `acquire` runs masked, as in {@link IO.bracket}. If the use is cancelled while `acquire` runs,
|
|
4281
|
+
* the use ends as `Cancelled` at once, and a value `acquire` still produces later is released as
|
|
4282
|
+
* soon as it arrives, with `Cancelled`.
|
|
4283
|
+
*
|
|
4284
|
+
* `release` runs to its end, without the abort signal. A release that never ends holds the use for
|
|
4285
|
+
* ever, even under `timeout`, so a release that may hang bounds its own time with `timeout`.
|
|
4286
|
+
*
|
|
4287
|
+
* If `release` fails (throws, even before it returns its `IO`, or rejects) after a successful use,
|
|
4288
|
+
* the use fails with that failure as a defect. After a failed, defective or cancelled use, and for a
|
|
4289
|
+
* value released after it arrived late, the failure is dropped and leaves no trace: a release whose
|
|
4290
|
+
* failure matters handles it itself, for example by logging it.
|
|
4291
|
+
*
|
|
4292
|
+
* @template E The error type of `acquire`.
|
|
4293
|
+
* @template A The value `acquire` produces.
|
|
4294
|
+
* @param {IO<E, A>} acquire Opens the resource.
|
|
4295
|
+
* @param {(a: A, exit: ReleaseExit<unknown, unknown>) => IO<never, void>} release Closes the
|
|
4296
|
+
* resource. Must not fail.
|
|
4297
|
+
* @returns {Resource<E, A>}
|
|
4298
|
+
*
|
|
4299
|
+
* @example
|
|
4300
|
+
* const pool = Resource.make(
|
|
4301
|
+
* IO.lift(() => createPool(config), toDbError),
|
|
4302
|
+
* (pool) => IO.promise(() => pool.end())
|
|
4303
|
+
* );
|
|
4304
|
+
*/
|
|
4305
|
+
static make<E, A>(acquire: IO<E, A>, release: (a: A, exit: ReleaseExit<unknown, unknown>) => IO<never, void>): Resource<E, A>;
|
|
4306
|
+
/**
|
|
4307
|
+
* A step with nothing to open, whose `release` runs when the use ends, in its place in the reverse
|
|
4308
|
+
* order. `release` learns how the use ended and follows the rules of a {@link make} release. Use it
|
|
4309
|
+
* for a shutdown step that only closes, such as draining work that exists from the start.
|
|
4310
|
+
*
|
|
4311
|
+
* @param {(exit: ReleaseExit<unknown, unknown>) => IO<never, void>} release Runs when the use ends.
|
|
4312
|
+
* Must not fail.
|
|
4313
|
+
* @returns {Resource<never, void>}
|
|
4314
|
+
*
|
|
4315
|
+
* @example
|
|
4316
|
+
* await $(Resource.onClose(() => IO.promise(() => work.drain()))); // after serving stops, before the pool closes
|
|
4317
|
+
*/
|
|
4318
|
+
static onClose(release: (exit: ReleaseExit<unknown, unknown>) => IO<never, void>): Resource<never, void>;
|
|
4319
|
+
/**
|
|
4320
|
+
* A plain value, with nothing to close.
|
|
4321
|
+
*
|
|
4322
|
+
* @template A The type of the value.
|
|
4323
|
+
* @param {A} value The value.
|
|
4324
|
+
* @returns {Resource<never, A>}
|
|
4325
|
+
*
|
|
4326
|
+
* @example
|
|
4327
|
+
* const config = Resource.of({ port: 8080 });
|
|
4328
|
+
*/
|
|
4329
|
+
static of<A>(value: A): Resource<never, A>;
|
|
4330
|
+
/**
|
|
4331
|
+
* An effect with nothing to close. It runs each time the resource is used, not when it is built.
|
|
4332
|
+
*
|
|
4333
|
+
* @template E The error type of `io`.
|
|
4334
|
+
* @template A The success type of `io`.
|
|
4335
|
+
* @param {IO<E, A>} io The effect.
|
|
4336
|
+
* @returns {Resource<E, A>}
|
|
4337
|
+
*
|
|
4338
|
+
* @example
|
|
4339
|
+
* const app = Resource.eval(IO.sync(() => App.create(options)));
|
|
4340
|
+
*/
|
|
4341
|
+
static eval<E, A>(io: IO<E, A>): Resource<E, A>;
|
|
4342
|
+
/**
|
|
4343
|
+
* Combines independent resources into one that gives a tuple of their values. They open in the
|
|
4344
|
+
* order given and close in reverse order. When one fails to open, the ones already open close.
|
|
4345
|
+
*
|
|
4346
|
+
* @template T The resources, as a tuple.
|
|
4347
|
+
* @param {T} resources The resources to combine.
|
|
4348
|
+
* @returns A resource whose error is the union of their errors, and whose value is the tuple of
|
|
4349
|
+
* their values.
|
|
4350
|
+
*
|
|
4351
|
+
* @example
|
|
4352
|
+
* const both = Resource.zip(pool, cache); // Resource<DbError | CacheError, readonly [Pool, Cache]>
|
|
4353
|
+
* await both.use(([pool, cache]) => serve(pool, cache)).unsafeRun();
|
|
4354
|
+
*/
|
|
4355
|
+
static zip<const T extends readonly Resource<any, any>[]>(...resources: T): Resource<ResourceError<T[number]>, {
|
|
4356
|
+
[K in keyof T]: ResourceValue<T[K]>;
|
|
4357
|
+
}>;
|
|
4358
|
+
/**
|
|
4359
|
+
* Monadic for-comprehension, like {@link IO.forM}. Each `$(resource)` call opens a resource and
|
|
4360
|
+
* returns its value; the resource stays open until the use ends. Resources close in reverse order
|
|
4361
|
+
* of the `$` calls. When one fails to open, the comprehension stops with its error, and the ones
|
|
4362
|
+
* already open close.
|
|
4363
|
+
*
|
|
4364
|
+
* `$` takes a `Resource` only, so each step says whether it opens something that closes. A step
|
|
4365
|
+
* with nothing to close is `$(Resource.eval(io))`. Await every `$` call: one the body does not
|
|
4366
|
+
* await opens in an order nobody chose.
|
|
4367
|
+
*
|
|
4368
|
+
* When `liftE` is provided, exceptions thrown inside the body become errors of type `E`. Without
|
|
4369
|
+
* `liftE` such an exception is a defect.
|
|
4370
|
+
*
|
|
4371
|
+
* @template E The error type shared by all opened resources.
|
|
4372
|
+
* @template A The value the comprehension gives to its use.
|
|
4373
|
+
* @param {($: <B>(resource: Resource<E, B>) => Promise<B>) => Promise<A>} body An async function
|
|
4374
|
+
* that receives a `$` callback for opening resources.
|
|
4375
|
+
* @param {(e: unknown) => E} [liftE] Optional function to turn exceptions into E.
|
|
4376
|
+
* @returns {Resource<E, A>}
|
|
4377
|
+
*
|
|
4378
|
+
* @example
|
|
4379
|
+
* const server = Resource.forM<StartFailure, RunningServer>(async ($) => {
|
|
4380
|
+
* const app = await $(Resource.eval(IO.sync(() => App.create(options)))); // nothing to close
|
|
4381
|
+
* const account = await $(Resource.make(startAccount(app), (a) => a.close));
|
|
4382
|
+
* await $(Resource.make(listen(app), () => App.close(app))); // closed first
|
|
4383
|
+
* return { app, account };
|
|
4384
|
+
* });
|
|
4385
|
+
*/
|
|
4386
|
+
static forM<E, A>(body: ($: <B>(resource: Resource<E, B>) => Promise<B>) => Promise<A>, liftE?: (e: unknown) => E): Resource<E, A>;
|
|
4387
|
+
/**
|
|
4388
|
+
* Opens the resource, runs `f` with its value, and then closes everything it opened, in reverse
|
|
4389
|
+
* order. The closes run after a success, a failure, a defect and a cancellation alike, to their end
|
|
4390
|
+
* and without the abort signal.
|
|
4391
|
+
*
|
|
4392
|
+
* - A failing release after a successful `f` makes the use fail with a defect.
|
|
4393
|
+
* - After a failed, defective or cancelled `f`, a failing release is dropped and `f`'s outcome is
|
|
4394
|
+
* kept.
|
|
4395
|
+
*
|
|
4396
|
+
* @template F The error type of `f`.
|
|
4397
|
+
* @template B The success type of `f`.
|
|
4398
|
+
* @param {(a: A) => IO<F, B>} f Uses the resource.
|
|
4399
|
+
* @returns {IO<E | F, B>} An IO that opens, uses and closes.
|
|
4400
|
+
*
|
|
4401
|
+
* @example
|
|
4402
|
+
* const count = pool.use((pool) => IO.lift(() => pool.query("SELECT count(*) FROM users"), toDbError));
|
|
4403
|
+
*/
|
|
4404
|
+
use<F, B>(f: (a: A) => IO<F, B>): IO<E | F, B>;
|
|
4405
|
+
/**
|
|
4406
|
+
* Transforms the value. The release is unchanged.
|
|
4407
|
+
*
|
|
4408
|
+
* @template B The new value type.
|
|
4409
|
+
* @param {(a: A) => B} f The transformation.
|
|
4410
|
+
* @returns {Resource<E, B>}
|
|
4411
|
+
*
|
|
4412
|
+
* @example
|
|
4413
|
+
* const users = pool.map((pool) => new UserRepository(pool));
|
|
4414
|
+
*/
|
|
4415
|
+
map<B>(f: (a: A) => B): Resource<E, B>;
|
|
4416
|
+
/**
|
|
4417
|
+
* Opens a second resource that may depend on the value of the first. The second closes before the
|
|
4418
|
+
* first.
|
|
4419
|
+
*
|
|
4420
|
+
* @template F The error type of the second resource.
|
|
4421
|
+
* @template B The value type of the second resource.
|
|
4422
|
+
* @param {(a: A) => Resource<F, B>} f Builds the second resource from the first value.
|
|
4423
|
+
* @returns {Resource<E | F, B>}
|
|
4424
|
+
*
|
|
4425
|
+
* @example
|
|
4426
|
+
* const server = pool.flatMap((pool) => Resource.make(listen(pool), (server) => server.stop()));
|
|
4427
|
+
*/
|
|
4428
|
+
flatMap<F, B>(f: (a: A) => Resource<F, B>): Resource<E | F, B>;
|
|
4429
|
+
/**
|
|
4430
|
+
* Transforms the error of opening. The error of the body given to {@link use} is not changed.
|
|
4431
|
+
*
|
|
4432
|
+
* @template F The new error type.
|
|
4433
|
+
* @param {(e: E) => F} f The transformation.
|
|
4434
|
+
* @returns {Resource<F, A>}
|
|
4435
|
+
*
|
|
4436
|
+
* @example
|
|
4437
|
+
* const pool = Resource.make(openPool(config), closePool).mapErr((e) => new StartFailure("db", e));
|
|
4438
|
+
*/
|
|
4439
|
+
mapErr<F>(f: (e: E) => F): Resource<F, A>;
|
|
4440
|
+
}
|
|
4441
|
+
|
|
4442
|
+
/** The error type of a resource; distributes over a union of resources. */
|
|
4443
|
+
declare type ResourceError<R> = R extends Resource<infer E, any> ? E : never;
|
|
4444
|
+
|
|
4445
|
+
/** The value type of a resource. */
|
|
4446
|
+
declare type ResourceValue<R> = R extends Resource<any, infer A> ? A : never;
|
|
4447
|
+
|
|
4182
4448
|
export declare class Right<B> extends Either<never, B> {
|
|
4183
4449
|
readonly value: B;
|
|
4184
4450
|
readonly type: "Right";
|