unthrown 0.3.0 → 1.1.0
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/README.md +2 -2
- package/dist/index.cjs +211 -58
- package/dist/index.d.cts +168 -47
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.mts +168 -47
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +207 -56
- package/dist/index.mjs.map +1 -1
- package/docs/index.md +197 -121
- package/package.json +3 -2
package/docs/index.md
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
### UnwrapError
|
|
10
10
|
|
|
11
|
-
Defined in: [packages/core/src/core.ts:
|
|
11
|
+
Defined in: [packages/core/src/core.ts:30](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/core.ts#L30)
|
|
12
12
|
|
|
13
13
|
Thrown by a [Result](#result)'s `unwrap` / `unwrapErr` when the assertion is
|
|
14
14
|
wrong on a *modeled* result — `unwrap()` on an `Err`, or `unwrapErr()` on an
|
|
@@ -37,7 +37,7 @@ re-thrown (with its original stack) instead.
|
|
|
37
37
|
new UnwrapError<E>(error): UnwrapError<E>;
|
|
38
38
|
```
|
|
39
39
|
|
|
40
|
-
Defined in: [packages/core/src/core.ts:
|
|
40
|
+
Defined in: [packages/core/src/core.ts:36](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/core.ts#L36)
|
|
41
41
|
|
|
42
42
|
###### Parameters
|
|
43
43
|
|
|
@@ -60,7 +60,7 @@ Error.constructor
|
|
|
60
60
|
| Property | Modifier | Type | Description | Inherited from | Defined in |
|
|
61
61
|
| ------ | ------ | ------ | ------ | ------ | ------ |
|
|
62
62
|
| <a id="cause"></a> `cause?` | `public` | `unknown` | - | `Error.cause` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es2022.error.d.ts:24 |
|
|
63
|
-
| <a id="error"></a> `error` | `readonly` | `E` | The offending value: the `Err` error for `unwrap()`, or the `Ok` value for `unwrapErr()`. | - | [packages/core/src/core.ts:
|
|
63
|
+
| <a id="error"></a> `error` | `readonly` | `E` | The offending value: the `Err` error for `unwrap()`, or the `Ok` value for `unwrapErr()`. | - | [packages/core/src/core.ts:35](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/core.ts#L35) |
|
|
64
64
|
| <a id="message"></a> `message` | `public` | `string` | - | `Error.message` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1075 |
|
|
65
65
|
| <a id="name"></a> `name` | `public` | `string` | - | `Error.name` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1074 |
|
|
66
66
|
| <a id="stack"></a> `stack?` | `public` | `string` | - | `Error.stack` | node\_modules/.pnpm/typescript@6.0.3/node\_modules/typescript/lib/lib.es5.d.ts:1076 |
|
|
@@ -174,7 +174,7 @@ Error.prepareStackTrace
|
|
|
174
174
|
type AsyncErrOf<R> = R extends AsyncResult<unknown, infer E> ? E : never;
|
|
175
175
|
```
|
|
176
176
|
|
|
177
|
-
Defined in: [packages/core/src/types.ts:
|
|
177
|
+
Defined in: [packages/core/src/types.ts:468](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L468)
|
|
178
178
|
|
|
179
179
|
Extract the error type `E` from an [AsyncResult](#asyncresult).
|
|
180
180
|
|
|
@@ -192,7 +192,7 @@ Extract the error type `E` from an [AsyncResult](#asyncresult).
|
|
|
192
192
|
type AsyncOkOf<R> = R extends AsyncResult<infer T, unknown> ? T : never;
|
|
193
193
|
```
|
|
194
194
|
|
|
195
|
-
Defined in: [packages/core/src/types.ts:
|
|
195
|
+
Defined in: [packages/core/src/types.ts:462](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L462)
|
|
196
196
|
|
|
197
197
|
Extract the success type `T` from an [AsyncResult](#asyncresult).
|
|
198
198
|
|
|
@@ -210,7 +210,7 @@ Extract the success type `T` from an [AsyncResult](#asyncresult).
|
|
|
210
210
|
type AsyncResult<T, E> = Awaitable<Result<T, E>> & object;
|
|
211
211
|
```
|
|
212
212
|
|
|
213
|
-
Defined in: [packages/core/src/types.ts:
|
|
213
|
+
Defined in: [packages/core/src/types.ts:369](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L369)
|
|
214
214
|
|
|
215
215
|
The asynchronous counterpart of [Result](#result): an awaitable wrapper with the
|
|
216
216
|
same method surface, collapsing to a `Result<T, E>` when `await`-ed.
|
|
@@ -219,24 +219,27 @@ same method surface, collapsing to a `Result<T, E>` when `await`-ed.
|
|
|
219
219
|
|
|
220
220
|
| Name | Type | Description | Defined in |
|
|
221
221
|
| ------ | ------ | ------ | ------ |
|
|
222
|
-
| `as()` | (`value`) => [`AsyncResult`](#asyncresult)<`U`, `E`> | Asynchronous `as`. | [packages/core/src/types.ts:
|
|
223
|
-
| `
|
|
224
|
-
| `
|
|
225
|
-
| `
|
|
226
|
-
| `
|
|
227
|
-
| `
|
|
228
|
-
| `
|
|
229
|
-
| `
|
|
230
|
-
| `
|
|
231
|
-
| `
|
|
232
|
-
| `
|
|
233
|
-
| `
|
|
234
|
-
| `
|
|
235
|
-
| `
|
|
236
|
-
| `
|
|
237
|
-
| `
|
|
238
|
-
| `
|
|
239
|
-
| `
|
|
222
|
+
| `as()` | (`value`) => [`AsyncResult`](#asyncresult)<`U`, `E`> | Asynchronous `as`. | [packages/core/src/types.ts:398](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L398) |
|
|
223
|
+
| `bind()` | (`name`, `f`) => [`AsyncResult`](#asyncresult)<\{ \[K in string \| number \| symbol\]: (Omit\<T, K\> & \{ readonly \[P in string\]: U \})\[K\] \}, `E` \| `E2`> | Asynchronous `bind` (do-notation). `f` may return a `Result` **or** an `AsyncResult`; its value is bound under `name` in the accumulating scope. | [packages/core/src/types.ts:391](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L391) |
|
|
224
|
+
| `flatMap()` | (`f`) => [`AsyncResult`](#asyncresult)<`U`, `E` \| `E2`> | Asynchronous `flatMap`. `f` may return a `Result` **or** an `AsyncResult` (never a raw `Promise`); a throw becomes a `Defect`. | [packages/core/src/types.ts:376](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L376) |
|
|
225
|
+
| `flatTap()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E` \| `E2`> | Asynchronous `flatTap` — a failable tap that keeps the original value. `f` may return a `Result` **or** an `AsyncResult`; its `Ok` value is discarded, an `Err`/`Defect` short-circuits, and a throw becomes a `Defect`. | [packages/core/src/types.ts:384](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L384) |
|
|
226
|
+
| `flatTapErr()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E` \| `E2`> | Asynchronous `flatTapErr` — a failable tap on the error that keeps the original error. `f` may return a `Result` **or** an `AsyncResult`; its `Ok` value is discarded, an `Err`/`Defect` from `f` threads through, and a throw becomes a `Defect`. | [packages/core/src/types.ts:414](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L414) |
|
|
227
|
+
| `getOrNull()` | () => `Promise`<`T` \| `null`> | Asynchronous `getOrNull`. | [packages/core/src/types.ts:440](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L440) |
|
|
228
|
+
| `getOrUndefined()` | () => `Promise`<`T` \| `undefined`> | Asynchronous `getOrUndefined`. | [packages/core/src/types.ts:442](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L442) |
|
|
229
|
+
| `let()` | (`name`, `f`) => [`AsyncResult`](#asyncresult)<\{ \[K in string \| number \| symbol\]: (Omit\<T, K\> & \{ readonly \[P in string\]: U \})\[K\] \}, `E`> | Asynchronous `let` (do-notation). `f` returns a plain value, bound under `name`. | [packages/core/src/types.ts:396](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L396) |
|
|
230
|
+
| `map()` | (`f`) => [`AsyncResult`](#asyncresult)<`U`, `E`> | Asynchronous `map`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:371](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L371) |
|
|
231
|
+
| `mapErr()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E2`> | Asynchronous `mapErr`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:401](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L401) |
|
|
232
|
+
| `match()` | (`cases`) => `Promise`<`R`> | Asynchronous `match`. Handlers are synchronous; resolves to `R`. | [packages/core/src/types.ts:426](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L426) |
|
|
233
|
+
| `orElse()` | (`f`) => [`AsyncResult`](#asyncresult)<`T` \| `U`, `E2`> | Asynchronous `orElse`. `f` may return a `Result` or an `AsyncResult`. | [packages/core/src/types.ts:403](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L403) |
|
|
234
|
+
| `recover()` | (`f`) => [`AsyncResult`](#asyncresult)<`T` \| `U`, `never`> | Asynchronous `recover`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:405](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L405) |
|
|
235
|
+
| `recoverDefect()` | (`f`) => [`AsyncResult`](#asyncresult)<`T` \| `U`, `E` \| `E2`> | Asynchronous `recoverDefect`. `f` may return a `Result` or an `AsyncResult`. | [packages/core/src/types.ts:419](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L419) |
|
|
236
|
+
| `tap()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E`> | Asynchronous `tap`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:378](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L378) |
|
|
237
|
+
| `tapDefect()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E`> | Asynchronous `tapDefect`. | [packages/core/src/types.ts:423](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L423) |
|
|
238
|
+
| `tapErr()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E`> | Asynchronous `tapErr`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:407](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L407) |
|
|
239
|
+
| `unwrap()` | () => `Promise`<`T`> | Asynchronous `unwrap`. The returned promise rejects on `Err`/`Defect`. | [packages/core/src/types.ts:432](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L432) |
|
|
240
|
+
| `unwrapErr()` | () => `Promise`<`E`> | Asynchronous `unwrapErr`. | [packages/core/src/types.ts:434](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L434) |
|
|
241
|
+
| `unwrapOr()` | (`fallback`) => `Promise`<`T`> | Asynchronous `unwrapOr`. | [packages/core/src/types.ts:436](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L436) |
|
|
242
|
+
| `unwrapOrElse()` | (`f`) => `Promise`<`T`> | Asynchronous `unwrapOrElse`. | [packages/core/src/types.ts:438](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L438) |
|
|
240
243
|
|
|
241
244
|
#### Type Parameters
|
|
242
245
|
|
|
@@ -266,7 +269,7 @@ To pattern-match an `AsyncResult`, `await` it first: `match(await ar)`.
|
|
|
266
269
|
type Awaitable<T> = object;
|
|
267
270
|
```
|
|
268
271
|
|
|
269
|
-
Defined in: [packages/core/src/types.ts:
|
|
272
|
+
Defined in: [packages/core/src/types.ts:346](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L346)
|
|
270
273
|
|
|
271
274
|
A success-only thenable: awaitable, but deliberately **not** a full
|
|
272
275
|
`PromiseLike`.
|
|
@@ -293,7 +296,7 @@ being treated as a raw promise (e.g. dropped into `Promise.all`).
|
|
|
293
296
|
then<R>(onfulfilled?): PromiseLike<R>;
|
|
294
297
|
```
|
|
295
298
|
|
|
296
|
-
Defined in: [packages/core/src/types.ts:
|
|
299
|
+
Defined in: [packages/core/src/types.ts:347](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L347)
|
|
297
300
|
|
|
298
301
|
###### Type Parameters
|
|
299
302
|
|
|
@@ -319,7 +322,7 @@ Defined in: [packages/core/src/types.ts:274](https://github.com/btravstack/unthr
|
|
|
319
322
|
type Defect = object;
|
|
320
323
|
```
|
|
321
324
|
|
|
322
|
-
Defined in: [packages/core/src/defect.ts:
|
|
325
|
+
Defined in: [packages/core/src/defect.ts:36](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/defect.ts#L36)
|
|
323
326
|
|
|
324
327
|
The marker a `qualify` function returns to triage a cause as **unexpected**.
|
|
325
328
|
|
|
@@ -327,7 +330,7 @@ The marker a `qualify` function returns to triage a cause as **unexpected**.
|
|
|
327
330
|
|
|
328
331
|
`qualify` (passed to [fromPromise](#frompromise) / [fromThrowable](#fromthrowable)) returns
|
|
329
332
|
`E | Defect`: either a modeled domain error, or a `Defect` produced by
|
|
330
|
-
[
|
|
333
|
+
[Defect](#defect-2) to say "this failure is not modeled". A `Defect` is opaque —
|
|
331
334
|
it carries the original cause for the boundary to convert into the third
|
|
332
335
|
runtime state of a `Result`.
|
|
333
336
|
|
|
@@ -335,8 +338,8 @@ runtime state of a `Result`.
|
|
|
335
338
|
|
|
336
339
|
| Property | Modifier | Type | Defined in |
|
|
337
340
|
| ------ | ------ | ------ | ------ |
|
|
338
|
-
| <a id="defect-1"></a> `[DEFECT]` | `readonly` | `true` | [packages/core/src/defect.ts:16](https://github.com/btravstack/unthrown/blob/
|
|
339
|
-
| <a id="cause-1"></a> `cause` | `readonly` | `unknown` | [packages/core/src/defect.ts:17](https://github.com/btravstack/unthrown/blob/
|
|
341
|
+
| <a id="defect-1"></a> `[DEFECT]` | `readonly` | `true` | [packages/core/src/defect.ts:16](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/defect.ts#L16) |
|
|
342
|
+
| <a id="cause-1"></a> `cause` | `readonly` | `unknown` | [packages/core/src/defect.ts:17](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/defect.ts#L17) |
|
|
340
343
|
|
|
341
344
|
***
|
|
342
345
|
|
|
@@ -346,7 +349,7 @@ runtime state of a `Result`.
|
|
|
346
349
|
type DefectView<T, E> = ResultMethods<T, E> & object;
|
|
347
350
|
```
|
|
348
351
|
|
|
349
|
-
Defined in: [packages/core/src/types.ts:
|
|
352
|
+
Defined in: [packages/core/src/types.ts:289](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L289)
|
|
350
353
|
|
|
351
354
|
The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `cause`.
|
|
352
355
|
|
|
@@ -354,8 +357,8 @@ The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `ca
|
|
|
354
357
|
|
|
355
358
|
| Name | Type | Defined in |
|
|
356
359
|
| ------ | ------ | ------ |
|
|
357
|
-
| `cause` | `unknown` | [packages/core/src/types.ts:
|
|
358
|
-
| `tag` | `"Defect"` | [packages/core/src/types.ts:
|
|
360
|
+
| `cause` | `unknown` | [packages/core/src/types.ts:291](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L291) |
|
|
361
|
+
| `tag` | `"Defect"` | [packages/core/src/types.ts:290](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L290) |
|
|
359
362
|
|
|
360
363
|
#### Type Parameters
|
|
361
364
|
|
|
@@ -372,7 +375,7 @@ The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `ca
|
|
|
372
375
|
type ErrOf<R> = R extends object ? E : never;
|
|
373
376
|
```
|
|
374
377
|
|
|
375
|
-
Defined in: [packages/core/src/types.ts:
|
|
378
|
+
Defined in: [packages/core/src/types.ts:456](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L456)
|
|
376
379
|
|
|
377
380
|
Extract the error type `E` from a `Result`.
|
|
378
381
|
|
|
@@ -390,7 +393,7 @@ Extract the error type `E` from a `Result`.
|
|
|
390
393
|
type ErrView<E, T> = ResultMethods<T, E> & object;
|
|
391
394
|
```
|
|
392
395
|
|
|
393
|
-
Defined in: [packages/core/src/types.ts:
|
|
396
|
+
Defined in: [packages/core/src/types.ts:284](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L284)
|
|
394
397
|
|
|
395
398
|
The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
|
|
396
399
|
|
|
@@ -398,8 +401,8 @@ The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
|
|
|
398
401
|
|
|
399
402
|
| Name | Type | Defined in |
|
|
400
403
|
| ------ | ------ | ------ |
|
|
401
|
-
| `error` | `E` | [packages/core/src/types.ts:
|
|
402
|
-
| `tag` | `"Err"` | [packages/core/src/types.ts:
|
|
404
|
+
| `error` | `E` | [packages/core/src/types.ts:286](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L286) |
|
|
405
|
+
| `tag` | `"Err"` | [packages/core/src/types.ts:285](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L285) |
|
|
403
406
|
|
|
404
407
|
#### Type Parameters
|
|
405
408
|
|
|
@@ -416,7 +419,7 @@ The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
|
|
|
416
419
|
type OkOf<R> = R extends object ? T : never;
|
|
417
420
|
```
|
|
418
421
|
|
|
419
|
-
Defined in: [packages/core/src/types.ts:
|
|
422
|
+
Defined in: [packages/core/src/types.ts:450](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L450)
|
|
420
423
|
|
|
421
424
|
Extract the success type `T` from a `Result`.
|
|
422
425
|
|
|
@@ -434,7 +437,7 @@ Extract the success type `T` from a `Result`.
|
|
|
434
437
|
type OkView<T, E> = ResultMethods<T, E> & object;
|
|
435
438
|
```
|
|
436
439
|
|
|
437
|
-
Defined in: [packages/core/src/types.ts:
|
|
440
|
+
Defined in: [packages/core/src/types.ts:279](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L279)
|
|
438
441
|
|
|
439
442
|
The `Ok` variant of a [Result](#result): a success carrying a `value`.
|
|
440
443
|
|
|
@@ -442,8 +445,8 @@ The `Ok` variant of a [Result](#result): a success carrying a `value`.
|
|
|
442
445
|
|
|
443
446
|
| Name | Type | Defined in |
|
|
444
447
|
| ------ | ------ | ------ |
|
|
445
|
-
| `tag` | `"Ok"` | [packages/core/src/types.ts:
|
|
446
|
-
| `value` | `T` | [packages/core/src/types.ts:
|
|
448
|
+
| `tag` | `"Ok"` | [packages/core/src/types.ts:280](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L280) |
|
|
449
|
+
| `value` | `T` | [packages/core/src/types.ts:281](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/types.ts#L281) |
|
|
447
450
|
|
|
448
451
|
#### Type Parameters
|
|
449
452
|
|
|
@@ -460,15 +463,15 @@ The `Ok` variant of a [Result](#result): a success carrying a `value`.
|
|
|
460
463
|
type Result<T, E> = ResultType<T, E>;
|
|
461
464
|
```
|
|
462
465
|
|
|
463
|
-
Defined in: [packages/core/src/facade.ts:
|
|
466
|
+
Defined in: [packages/core/src/facade.ts:44](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L44)
|
|
464
467
|
|
|
465
468
|
Companion object grouping the standalone entry points under a single,
|
|
466
|
-
discoverable namespace: [Result.
|
|
467
|
-
[Result.
|
|
469
|
+
discoverable namespace: [Result.Ok](#property-ok), [Result.Err](#property-err),
|
|
470
|
+
[Result.Defect](#property-defect), [Result.fromNullable](#property-fromnullable), [Result.fromThrowable](#property-fromthrowable),
|
|
468
471
|
[Result.fromPromise](#property-frompromise), [Result.fromSafePromise](#property-fromsafepromise), [Result.all](#property-all),
|
|
469
472
|
[Result.allAsync](#property-allasync), [Result.allFromDict](#property-allfromdict),
|
|
470
473
|
[Result.allFromDictAsync](#property-allfromdictasync), [Result.isOk](#property-isok), [Result.isErr](#property-iserr),
|
|
471
|
-
[Result.isDefect](#property-isdefect).
|
|
474
|
+
[Result.isDefect](#property-isdefect), [Result.isResult](#property-isresult).
|
|
472
475
|
|
|
473
476
|
#### Type Parameters
|
|
474
477
|
|
|
@@ -481,14 +484,14 @@ discoverable namespace: [Result.ok](#property-ok), [Result.err](#property-err),
|
|
|
481
484
|
|
|
482
485
|
Purely additive sugar — each member **is** the corresponding free function.
|
|
483
486
|
The free functions remain the primary, tree-shakeable API; importing only
|
|
484
|
-
`{
|
|
487
|
+
`{ Ok }` never pulls this object in. The value `Result` and the type
|
|
485
488
|
[Result](#result-1) share one name (the companion-object pattern).
|
|
486
489
|
|
|
487
490
|
#### Example
|
|
488
491
|
|
|
489
492
|
```ts
|
|
490
493
|
import { Result } from "unthrown";
|
|
491
|
-
Result.
|
|
494
|
+
Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // 2
|
|
492
495
|
```
|
|
493
496
|
|
|
494
497
|
***
|
|
@@ -499,7 +502,7 @@ Result.ok(1).flatMap((n) => Result.ok(n + 1)).unwrap(); // 2
|
|
|
499
502
|
type TaggedErrorConstructor<Tag> = <A>(args) => TaggedErrorInstance<Tag, A>;
|
|
500
503
|
```
|
|
501
504
|
|
|
502
|
-
Defined in: [packages/core/src/tagged.ts:28](https://github.com/btravstack/unthrown/blob/
|
|
505
|
+
Defined in: [packages/core/src/tagged.ts:28](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/tagged.ts#L28)
|
|
503
506
|
|
|
504
507
|
The class constructor returned by [TaggedError](#taggederror). Generic in its payload:
|
|
505
508
|
apply it with an instantiation expression at the `extends` site.
|
|
@@ -533,7 +536,7 @@ When the payload is empty, the constructor takes **no** arguments (the
|
|
|
533
536
|
type TaggedErrorInstance<Tag, A> = Error & Readonly<A> & object;
|
|
534
537
|
```
|
|
535
538
|
|
|
536
|
-
Defined in: [packages/core/src/tagged.ts:15](https://github.com/btravstack/unthrown/blob/
|
|
539
|
+
Defined in: [packages/core/src/tagged.ts:15](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/tagged.ts#L15)
|
|
537
540
|
|
|
538
541
|
The instance shape produced by a [TaggedError](#taggederror) class: an `Error` plus a
|
|
539
542
|
`_tag` discriminant and the (readonly) payload fields.
|
|
@@ -542,7 +545,7 @@ The instance shape produced by a [TaggedError](#taggederror) class: an `Error` p
|
|
|
542
545
|
|
|
543
546
|
| Name | Type | Defined in |
|
|
544
547
|
| ------ | ------ | ------ |
|
|
545
|
-
| `_tag` | `Tag` | [packages/core/src/tagged.ts:16](https://github.com/btravstack/unthrown/blob/
|
|
548
|
+
| `_tag` | `Tag` | [packages/core/src/tagged.ts:16](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/tagged.ts#L16) |
|
|
546
549
|
|
|
547
550
|
#### Type Parameters
|
|
548
551
|
|
|
@@ -559,7 +562,7 @@ The instance shape produced by a [TaggedError](#taggederror) class: an `Error` p
|
|
|
559
562
|
type TagHandlers<T, E, R> = object & { [K in E["_tag"]]: (error: Extract<E, { _tag: K }>) => R };
|
|
560
563
|
```
|
|
561
564
|
|
|
562
|
-
Defined in: [packages/core/src/tagged.ts:103](https://github.com/btravstack/unthrown/blob/
|
|
565
|
+
Defined in: [packages/core/src/tagged.ts:103](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/tagged.ts#L103)
|
|
563
566
|
|
|
564
567
|
The handler object [matchTags](#matchtags) requires: a branch per error tag, plus
|
|
565
568
|
`Ok` and `Defect`. Miss a tag and it will not compile — the exhaustiveness is
|
|
@@ -569,8 +572,8 @@ enforced by the type, with no `.exhaustive()` to forget.
|
|
|
569
572
|
|
|
570
573
|
| Name | Type | Defined in |
|
|
571
574
|
| ------ | ------ | ------ |
|
|
572
|
-
| `Defect()` | (`cause`) => `R` | [packages/core/src/tagged.ts:105](https://github.com/btravstack/unthrown/blob/
|
|
573
|
-
| `Ok()` | (`value`) => `R` | [packages/core/src/tagged.ts:104](https://github.com/btravstack/unthrown/blob/
|
|
575
|
+
| `Defect()` | (`cause`) => `R` | [packages/core/src/tagged.ts:105](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/tagged.ts#L105) |
|
|
576
|
+
| `Ok()` | (`value`) => `R` | [packages/core/src/tagged.ts:104](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/tagged.ts#L104) |
|
|
574
577
|
|
|
575
578
|
#### Type Parameters
|
|
576
579
|
|
|
@@ -588,47 +591,49 @@ enforced by the type, with no `.exhaustive()` to forget.
|
|
|
588
591
|
const Result: object;
|
|
589
592
|
```
|
|
590
593
|
|
|
591
|
-
Defined in: [packages/core/src/facade.ts:
|
|
594
|
+
Defined in: [packages/core/src/facade.ts:44](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L44)
|
|
592
595
|
|
|
593
596
|
Companion object grouping the standalone entry points under a single,
|
|
594
|
-
discoverable namespace: [Result.
|
|
595
|
-
[Result.
|
|
597
|
+
discoverable namespace: [Result.Ok](#property-ok), [Result.Err](#property-err),
|
|
598
|
+
[Result.Defect](#property-defect), [Result.fromNullable](#property-fromnullable), [Result.fromThrowable](#property-fromthrowable),
|
|
596
599
|
[Result.fromPromise](#property-frompromise), [Result.fromSafePromise](#property-fromsafepromise), [Result.all](#property-all),
|
|
597
600
|
[Result.allAsync](#property-allasync), [Result.allFromDict](#property-allfromdict),
|
|
598
601
|
[Result.allFromDictAsync](#property-allfromdictasync), [Result.isOk](#property-isok), [Result.isErr](#property-iserr),
|
|
599
|
-
[Result.isDefect](#property-isdefect).
|
|
602
|
+
[Result.isDefect](#property-isdefect), [Result.isResult](#property-isresult).
|
|
600
603
|
|
|
601
604
|
#### Type Declaration
|
|
602
605
|
|
|
603
606
|
| Name | Type | Defined in |
|
|
604
607
|
| ------ | ------ | ------ |
|
|
605
|
-
| <a id="property-all"></a> `all()` | <`Rs`>(`results`) => `Result`<`AllOk`<`Rs`, \{ \[K in string \| number \| symbol\]: OkOf\<Rs\[K\]\> \}>, [`ErrOf`](#errof)<`Rs`\[`number`\]>> | [packages/core/src/facade.ts:
|
|
606
|
-
| <a id="property-allasync"></a> `allAsync()` | <`Rs`>(`results`) => [`AsyncResult`](#asyncresult)<`AllOk`<`Rs`, \{ \[K in string \| number \| symbol\]: AsyncOkOf\<Rs\[K\]\> \}>, [`AsyncErrOf`](#asyncerrof)<`Rs`\[`number`\]>> | [packages/core/src/facade.ts:
|
|
607
|
-
| <a id="property-allfromdict"></a> `allFromDict()` | <`R`>(`results`) => `Result`<\{ \[K in string \| number \| symbol\]: OkOf\<R\[K\]\> \}, [`ErrOf`](#errof)<`R`\[keyof `R`\]>> | [packages/core/src/facade.ts:
|
|
608
|
-
| <a id="property-allfromdictasync"></a> `allFromDictAsync()` | <`R`>(`results`) => [`AsyncResult`](#asyncresult)<\{ \[K in string \| number \| symbol\]: AsyncOkOf\<R\[K\]\> \}, [`AsyncErrOf`](#asyncerrof)<`R`\[keyof `R`\]>> | [packages/core/src/facade.ts:
|
|
609
|
-
| <a id="property-defect"></a> `
|
|
610
|
-
| <a id="property-
|
|
611
|
-
| <a id="property-
|
|
612
|
-
| <a id="property-
|
|
613
|
-
| <a id="property-
|
|
614
|
-
| <a id="property-
|
|
615
|
-
| <a id="property-
|
|
616
|
-
| <a id="property-
|
|
617
|
-
| <a id="property-
|
|
618
|
-
| <a id="property-
|
|
608
|
+
| <a id="property-all"></a> `all()` | <`Rs`>(`results`) => `Result`<`AllOk`<`Rs`, \{ \[K in string \| number \| symbol\]: OkOf\<Rs\[K\]\> \}>, [`ErrOf`](#errof)<`Rs`\[`number`\]>> | [packages/core/src/facade.ts:53](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L53) |
|
|
609
|
+
| <a id="property-allasync"></a> `allAsync()` | <`Rs`>(`results`) => [`AsyncResult`](#asyncresult)<`AllOk`<`Rs`, \{ \[K in string \| number \| symbol\]: AsyncOkOf\<Rs\[K\]\> \}>, [`AsyncErrOf`](#asyncerrof)<`Rs`\[`number`\]>> | [packages/core/src/facade.ts:54](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L54) |
|
|
610
|
+
| <a id="property-allfromdict"></a> `allFromDict()` | <`R`>(`results`) => `Result`<\{ \[K in string \| number \| symbol\]: OkOf\<R\[K\]\> \}, [`ErrOf`](#errof)<`R`\[keyof `R`\]>> | [packages/core/src/facade.ts:55](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L55) |
|
|
611
|
+
| <a id="property-allfromdictasync"></a> `allFromDictAsync()` | <`R`>(`results`) => [`AsyncResult`](#asyncresult)<\{ \[K in string \| number \| symbol\]: AsyncOkOf\<R\[K\]\> \}, [`AsyncErrOf`](#asyncerrof)<`R`\[keyof `R`\]>> | [packages/core/src/facade.ts:56](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L56) |
|
|
612
|
+
| <a id="property-defect"></a> `Defect()` | (`cause`) => [`Defect`](#defect) | [packages/core/src/facade.ts:47](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L47) |
|
|
613
|
+
| <a id="property-do"></a> `Do()` | () => `Result`<\{ \}, `never`> | [packages/core/src/facade.ts:48](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L48) |
|
|
614
|
+
| <a id="property-err"></a> `Err()` | <`E`>(`error`) => `Result`<`never`, `E`> | [packages/core/src/facade.ts:46](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L46) |
|
|
615
|
+
| <a id="property-fromnullable"></a> `fromNullable()` | <`T`, `E`>(`value`, `onAbsent`) => `Result`<`NonNullable`<`T`>, `E`> | [packages/core/src/facade.ts:49](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L49) |
|
|
616
|
+
| <a id="property-frompromise"></a> `fromPromise()` | <`T`, `R`>(`promise`, `qualify`) => [`AsyncResult`](#asyncresult)<`T`, `Exclude`<`R`, [`Defect`](#defect)>> | [packages/core/src/facade.ts:51](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L51) |
|
|
617
|
+
| <a id="property-fromsafepromise"></a> `fromSafePromise()` | <`T`>(`promise`) => [`AsyncResult`](#asyncresult)<`T`, `never`> | [packages/core/src/facade.ts:52](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L52) |
|
|
618
|
+
| <a id="property-fromthrowable"></a> `fromThrowable()` | <`A`, `T`, `R`>(`fn`, `qualify`) => (...`args`) => `Result`<`T`, `Exclude`<`R`, [`Defect`](#defect)>> | [packages/core/src/facade.ts:50](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L50) |
|
|
619
|
+
| <a id="property-isdefect"></a> `isDefect()` | <`T`, `E`>(`r`) => `r is DefectView<T, E>` | [packages/core/src/facade.ts:59](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L59) |
|
|
620
|
+
| <a id="property-iserr"></a> `isErr()` | <`T`, `E`>(`r`) => `r is ErrView<E, T>` | [packages/core/src/facade.ts:58](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L58) |
|
|
621
|
+
| <a id="property-isok"></a> `isOk()` | <`T`, `E`>(`r`) => `r is OkView<T, E>` | [packages/core/src/facade.ts:57](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L57) |
|
|
622
|
+
| <a id="property-isresult"></a> `isResult()` | (`x`) => `x is Result<unknown, unknown>` | [packages/core/src/facade.ts:60](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L60) |
|
|
623
|
+
| <a id="property-ok"></a> `Ok()` | <`T`>(`value`) => `Result`<`T`, `never`> | [packages/core/src/facade.ts:45](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/facade.ts#L45) |
|
|
619
624
|
|
|
620
625
|
#### Remarks
|
|
621
626
|
|
|
622
627
|
Purely additive sugar — each member **is** the corresponding free function.
|
|
623
628
|
The free functions remain the primary, tree-shakeable API; importing only
|
|
624
|
-
`{
|
|
629
|
+
`{ Ok }` never pulls this object in. The value `Result` and the type
|
|
625
630
|
[Result](#result-1) share one name (the companion-object pattern).
|
|
626
631
|
|
|
627
632
|
#### Example
|
|
628
633
|
|
|
629
634
|
```ts
|
|
630
635
|
import { Result } from "unthrown";
|
|
631
|
-
Result.
|
|
636
|
+
Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // 2
|
|
632
637
|
```
|
|
633
638
|
|
|
634
639
|
## Functions
|
|
@@ -639,7 +644,7 @@ Result.ok(1).flatMap((n) => Result.ok(n + 1)).unwrap(); // 2
|
|
|
639
644
|
function all<Rs>(results): Result<AllOk<Rs, { [K in string | number | symbol]: OkOf<Rs[K]> }>, ErrOf<Rs[number]>>;
|
|
640
645
|
```
|
|
641
646
|
|
|
642
|
-
Defined in: [packages/core/src/interop.ts:249](https://github.com/btravstack/unthrown/blob/
|
|
647
|
+
Defined in: [packages/core/src/interop.ts:249](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/interop.ts#L249)
|
|
643
648
|
|
|
644
649
|
Collect a tuple/array of [Result](#result)s into a single `Result` of all their
|
|
645
650
|
success values.
|
|
@@ -664,7 +669,7 @@ success values.
|
|
|
664
669
|
|
|
665
670
|
Short-circuits on the **first** `Err` (later entries are not inspected for
|
|
666
671
|
their error); any `Defect` present **dominates**, winning even over an earlier
|
|
667
|
-
`Err`. A **fixed tuple** keeps its positional types — `all([
|
|
672
|
+
`Err`. A **fixed tuple** keeps its positional types — `all([Ok(1), Ok("a")])`
|
|
668
673
|
is `Result<[number, string], …>` — while a **dynamic array** `Result<T, E>[]`
|
|
669
674
|
collapses to `Result<T[], E>` with no cast. For a **record** keyed by name,
|
|
670
675
|
use [allFromDict](#allfromdict).
|
|
@@ -672,9 +677,9 @@ use [allFromDict](#allfromdict).
|
|
|
672
677
|
#### Example
|
|
673
678
|
|
|
674
679
|
```ts
|
|
675
|
-
import { all,
|
|
676
|
-
all([
|
|
677
|
-
all([
|
|
680
|
+
import { all, Ok } from "unthrown";
|
|
681
|
+
all([Ok(1), Ok("a"), Ok(true)]).unwrap(); // [1, "a", true] (typed [number, string, boolean])
|
|
682
|
+
all([Ok(1), Ok(2)] as Result<number, never>[]).unwrap(); // number[]
|
|
678
683
|
```
|
|
679
684
|
|
|
680
685
|
***
|
|
@@ -685,7 +690,7 @@ all([ok(1), ok(2)] as Result<number, never>[]).unwrap(); // number[]
|
|
|
685
690
|
function allAsync<Rs>(results): AsyncResult<AllOk<Rs, { [K in string | number | symbol]: AsyncOkOf<Rs[K]> }>, AsyncErrOf<Rs[number]>>;
|
|
686
691
|
```
|
|
687
692
|
|
|
688
|
-
Defined in: [packages/core/src/interop.ts:
|
|
693
|
+
Defined in: [packages/core/src/interop.ts:299](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/interop.ts#L299)
|
|
689
694
|
|
|
690
695
|
The asynchronous counterpart of [all](#all): combine a tuple/array of
|
|
691
696
|
[AsyncResult](#asyncresult)s into one `AsyncResult` of all their success values.
|
|
@@ -728,7 +733,7 @@ await allAsync([fromSafePromise(a()), fromSafePromise(b())]);
|
|
|
728
733
|
function allFromDict<R>(results): Result<{ [K in string | number | symbol]: OkOf<R[K]> }, ErrOf<R[keyof R]>>;
|
|
729
734
|
```
|
|
730
735
|
|
|
731
|
-
Defined in: [packages/core/src/interop.ts:274](https://github.com/btravstack/unthrown/blob/
|
|
736
|
+
Defined in: [packages/core/src/interop.ts:274](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/interop.ts#L274)
|
|
732
737
|
|
|
733
738
|
Collect a **record** of [Result](#result)s into a single `Result` of a record of
|
|
734
739
|
their success values — `allFromDict({ a: Result<A, E>, b: Result<B, E> })` is
|
|
@@ -759,8 +764,8 @@ dominates. This is **not** error accumulation.
|
|
|
759
764
|
#### Example
|
|
760
765
|
|
|
761
766
|
```ts
|
|
762
|
-
import { allFromDict,
|
|
763
|
-
allFromDict({ id:
|
|
767
|
+
import { allFromDict, Ok } from "unthrown";
|
|
768
|
+
allFromDict({ id: Ok(1), name: Ok("ada") }).unwrap(); // { id: 1, name: "ada" }
|
|
764
769
|
```
|
|
765
770
|
|
|
766
771
|
***
|
|
@@ -771,7 +776,7 @@ allFromDict({ id: ok(1), name: ok("ada") }).unwrap(); // { id: 1, name: "ada" }
|
|
|
771
776
|
function allFromDictAsync<R>(results): AsyncResult<{ [K in string | number | symbol]: AsyncOkOf<R[K]> }, AsyncErrOf<R[keyof R]>>;
|
|
772
777
|
```
|
|
773
778
|
|
|
774
|
-
Defined in: [packages/core/src/interop.ts:
|
|
779
|
+
Defined in: [packages/core/src/interop.ts:327](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/interop.ts#L327)
|
|
775
780
|
|
|
776
781
|
The asynchronous counterpart of [allFromDict](#allfromdict): combine a record of
|
|
777
782
|
[AsyncResult](#asyncresult)s into one `AsyncResult` of a record of their values.
|
|
@@ -806,15 +811,15 @@ await allFromDictAsync({ a: fromSafePromise(a()), b: fromSafePromise(b()) });
|
|
|
806
811
|
|
|
807
812
|
***
|
|
808
813
|
|
|
809
|
-
###
|
|
814
|
+
### Defect()
|
|
810
815
|
|
|
811
816
|
```ts
|
|
812
|
-
function
|
|
817
|
+
function Defect(cause): Defect;
|
|
813
818
|
```
|
|
814
819
|
|
|
815
|
-
Defined in: [packages/core/src/defect.ts:36](https://github.com/btravstack/unthrown/blob/
|
|
820
|
+
Defined in: [packages/core/src/defect.ts:36](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/defect.ts#L36)
|
|
816
821
|
|
|
817
|
-
Wrap a cause as a [Defect](#defect) — the value you return from a `qualify`
|
|
822
|
+
Wrap a cause as a [Defect](#defect-2) — the value you return from a `qualify`
|
|
818
823
|
function when a failure is **not** a modeled domain error.
|
|
819
824
|
|
|
820
825
|
#### Parameters
|
|
@@ -827,27 +832,66 @@ function when a failure is **not** a modeled domain error.
|
|
|
827
832
|
|
|
828
833
|
[`Defect`](#defect)
|
|
829
834
|
|
|
830
|
-
an opaque
|
|
835
|
+
an opaque Defect marker carrying `cause`.
|
|
831
836
|
|
|
832
837
|
#### Example
|
|
833
838
|
|
|
834
839
|
```ts
|
|
835
|
-
import { fromPromise,
|
|
840
|
+
import { fromPromise, Defect } from "unthrown";
|
|
836
841
|
|
|
837
842
|
const user = fromPromise(fetchUser(id), (cause) =>
|
|
838
|
-
cause instanceof NotFoundError ? cause :
|
|
843
|
+
cause instanceof NotFoundError ? cause : Defect(cause),
|
|
839
844
|
);
|
|
840
845
|
```
|
|
841
846
|
|
|
842
847
|
***
|
|
843
848
|
|
|
844
|
-
###
|
|
849
|
+
### Do()
|
|
845
850
|
|
|
846
851
|
```ts
|
|
847
|
-
function
|
|
852
|
+
function Do(): Result<{
|
|
853
|
+
}, never>;
|
|
848
854
|
```
|
|
849
855
|
|
|
850
|
-
Defined in: [packages/core/src/
|
|
856
|
+
Defined in: [packages/core/src/do.ts:30](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/do.ts#L30)
|
|
857
|
+
|
|
858
|
+
Start a do-notation chain with an empty object scope, grown step by step with
|
|
859
|
+
`bind` (for `Result`-returning steps) and `let` (for pure values).
|
|
860
|
+
|
|
861
|
+
#### Returns
|
|
862
|
+
|
|
863
|
+
`Result`<\{
|
|
864
|
+
\}, `never`>
|
|
865
|
+
|
|
866
|
+
#### Remarks
|
|
867
|
+
|
|
868
|
+
Capitalised because `do` is a reserved word. Each step receives the scope
|
|
869
|
+
accumulated so far; the error types union across `bind`s, and a throw in any
|
|
870
|
+
step becomes a `Defect`. To go asynchronous, lift the chain with `toAsync()`
|
|
871
|
+
(then a `bind` may return an `AsyncResult`).
|
|
872
|
+
|
|
873
|
+
#### Example
|
|
874
|
+
|
|
875
|
+
```ts
|
|
876
|
+
import { Do, Ok } from "unthrown";
|
|
877
|
+
|
|
878
|
+
const result = Do()
|
|
879
|
+
.bind("user", () => findUser(id)) // Result<User, NotFound>
|
|
880
|
+
.bind("org", ({ user }) => findOrg(user.orgId)) // Result<Org, NotFound>
|
|
881
|
+
.let("label", ({ user, org }) => `${user.name} @ ${org.name}`)
|
|
882
|
+
.map(({ user, org, label }) => render(user, org, label));
|
|
883
|
+
// Result<View, NotFound>
|
|
884
|
+
```
|
|
885
|
+
|
|
886
|
+
***
|
|
887
|
+
|
|
888
|
+
### Err()
|
|
889
|
+
|
|
890
|
+
```ts
|
|
891
|
+
function Err<E>(error): Result<never, E>;
|
|
892
|
+
```
|
|
893
|
+
|
|
894
|
+
Defined in: [packages/core/src/constructors.ts:34](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/constructors.ts#L34)
|
|
851
895
|
|
|
852
896
|
Construct a failed [Result](#result) carrying a **modeled** error.
|
|
853
897
|
|
|
@@ -870,8 +914,8 @@ Construct a failed [Result](#result) carrying a **modeled** error.
|
|
|
870
914
|
#### Example
|
|
871
915
|
|
|
872
916
|
```ts
|
|
873
|
-
import {
|
|
874
|
-
|
|
917
|
+
import { Err } from "unthrown";
|
|
918
|
+
Err("not_found").unwrapErr(); // "not_found"
|
|
875
919
|
```
|
|
876
920
|
|
|
877
921
|
***
|
|
@@ -882,7 +926,7 @@ err("not_found").unwrapErr(); // "not_found"
|
|
|
882
926
|
function fromNullable<T, E>(value, onAbsent): Result<NonNullable<T>, E>;
|
|
883
927
|
```
|
|
884
928
|
|
|
885
|
-
Defined in: [packages/core/src/interop.ts:29](https://github.com/btravstack/unthrown/blob/
|
|
929
|
+
Defined in: [packages/core/src/interop.ts:29](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/interop.ts#L29)
|
|
886
930
|
|
|
887
931
|
Bridge a nullable value into a [Result](#result): absence becomes a **modeled**
|
|
888
932
|
`Err`. The sanctioned alternative to an `Option` type.
|
|
@@ -907,7 +951,7 @@ Bridge a nullable value into a [Result](#result): absence becomes a **modeled**
|
|
|
907
951
|
|
|
908
952
|
#### Remarks
|
|
909
953
|
|
|
910
|
-
`null` and `undefined` map to `
|
|
954
|
+
`null` and `undefined` map to `Err(onAbsent())`; any other value (including
|
|
911
955
|
falsy ones like `0`, `""`, `false`) maps to `Ok`.
|
|
912
956
|
|
|
913
957
|
#### Example
|
|
@@ -925,7 +969,7 @@ fromNullable(map.get(key), () => "missing").unwrap();
|
|
|
925
969
|
function fromPromise<T, R>(promise, qualify): AsyncResult<T, Exclude<R, Defect>>;
|
|
926
970
|
```
|
|
927
971
|
|
|
928
|
-
Defined in: [packages/core/src/interop.ts:110](https://github.com/btravstack/unthrown/blob/
|
|
972
|
+
Defined in: [packages/core/src/interop.ts:110](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/interop.ts#L110)
|
|
929
973
|
|
|
930
974
|
Wrap a `Promise` (or a thunk producing one) as an [AsyncResult](#asyncresult), forcing
|
|
931
975
|
every rejection to be triaged.
|
|
@@ -951,21 +995,21 @@ every rejection to be triaged.
|
|
|
951
995
|
#### Remarks
|
|
952
996
|
|
|
953
997
|
`qualify` **must** map each rejection cause into a modeled error `E` or a
|
|
954
|
-
[Defect](#defect). The returned `AsyncResult`'s internal promise never rejects;
|
|
998
|
+
[Defect](#defect-2). The returned `AsyncResult`'s internal promise never rejects;
|
|
955
999
|
`await`-ing it always yields a `Result`. A throw inside `qualify` is itself a
|
|
956
1000
|
`Defect`.
|
|
957
1001
|
|
|
958
1002
|
The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
|
|
959
1003
|
`qualify`'s return is **subtracted** from `E`, never inferred into it. So a
|
|
960
|
-
`qualify` that returns *only* `
|
|
961
|
-
rejection is a
|
|
1004
|
+
`qualify` that returns *only* `Defect(cause)` yields `E = never`; when every
|
|
1005
|
+
rejection is a Defect, prefer [fromSafePromise](#fromsafepromise).
|
|
962
1006
|
|
|
963
1007
|
#### Example
|
|
964
1008
|
|
|
965
1009
|
```ts
|
|
966
|
-
import { fromPromise,
|
|
1010
|
+
import { fromPromise, Defect } from "unthrown";
|
|
967
1011
|
const user = await fromPromise(fetchUser(id), (cause) =>
|
|
968
|
-
cause instanceof NotFoundError ? ("not_found" as const) :
|
|
1012
|
+
cause instanceof NotFoundError ? ("not_found" as const) : Defect(cause),
|
|
969
1013
|
);
|
|
970
1014
|
```
|
|
971
1015
|
|
|
@@ -977,7 +1021,7 @@ const user = await fromPromise(fetchUser(id), (cause) =>
|
|
|
977
1021
|
function fromSafePromise<T>(promise): AsyncResult<T, never>;
|
|
978
1022
|
```
|
|
979
1023
|
|
|
980
|
-
Defined in: [packages/core/src/interop.ts:136](https://github.com/btravstack/unthrown/blob/
|
|
1024
|
+
Defined in: [packages/core/src/interop.ts:136](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/interop.ts#L136)
|
|
981
1025
|
|
|
982
1026
|
Wrap a `Promise` asserted **not** to fail in any modeled way: any rejection
|
|
983
1027
|
becomes a `Defect`.
|
|
@@ -1012,7 +1056,7 @@ triage. (`await`-ing still yields a `Result`; it never throws.)
|
|
|
1012
1056
|
function fromThrowable<A, T, R>(fn, qualify): (...args) => Result<T, Exclude<R, Defect>>;
|
|
1013
1057
|
```
|
|
1014
1058
|
|
|
1015
|
-
Defined in: [packages/core/src/interop.ts:66](https://github.com/btravstack/unthrown/blob/
|
|
1059
|
+
Defined in: [packages/core/src/interop.ts:66](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/interop.ts#L66)
|
|
1016
1060
|
|
|
1017
1061
|
Wrap a throwing synchronous function so it returns a [Result](#result) instead of
|
|
1018
1062
|
throwing.
|
|
@@ -1041,20 +1085,20 @@ a function with the same arguments returning `Result<T, E>`.
|
|
|
1041
1085
|
#### Remarks
|
|
1042
1086
|
|
|
1043
1087
|
`qualify` **must** triage every thrown cause into a modeled error `E` or a
|
|
1044
|
-
[Defect](#defect) (via [
|
|
1088
|
+
[Defect](#defect-2) (via [Defect](#defect-2)) — there is no path that leaves `unknown`
|
|
1045
1089
|
in `E`. A throw inside `qualify` itself is treated as a `Defect`.
|
|
1046
1090
|
|
|
1047
1091
|
The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
|
|
1048
1092
|
`qualify`'s return is **subtracted** from `E`, never inferred into it. So a
|
|
1049
|
-
`qualify` that returns *only* `
|
|
1093
|
+
`qualify` that returns *only* `Defect(cause)` yields `E = never` (a Defect is
|
|
1050
1094
|
out-of-band and must not pollute the error channel); reach for
|
|
1051
|
-
[fromSafePromise](#fromsafepromise) when every failure is a
|
|
1095
|
+
[fromSafePromise](#fromsafepromise) when every failure is a Defect.
|
|
1052
1096
|
|
|
1053
1097
|
#### Example
|
|
1054
1098
|
|
|
1055
1099
|
```ts
|
|
1056
|
-
import { fromThrowable,
|
|
1057
|
-
const parse = fromThrowable(JSON.parse, (cause) =>
|
|
1100
|
+
import { fromThrowable, Defect } from "unthrown";
|
|
1101
|
+
const parse = fromThrowable(JSON.parse, (cause) => Defect(cause));
|
|
1058
1102
|
parse("{}").unwrap();
|
|
1059
1103
|
```
|
|
1060
1104
|
|
|
@@ -1066,7 +1110,7 @@ parse("{}").unwrap();
|
|
|
1066
1110
|
function isDefect<T, E>(r): r is DefectView<T, E>;
|
|
1067
1111
|
```
|
|
1068
1112
|
|
|
1069
|
-
Defined in: [packages/core/src/constructors.ts:66](https://github.com/btravstack/unthrown/blob/
|
|
1113
|
+
Defined in: [packages/core/src/constructors.ts:66](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/constructors.ts#L66)
|
|
1070
1114
|
|
|
1071
1115
|
Type guard: narrow a [Result](#result) to its `Defect` variant, exposing `.cause`.
|
|
1072
1116
|
|
|
@@ -1097,7 +1141,7 @@ Type guard: narrow a [Result](#result) to its `Defect` variant, exposing `.cause
|
|
|
1097
1141
|
function isErr<T, E>(r): r is ErrView<E, T>;
|
|
1098
1142
|
```
|
|
1099
1143
|
|
|
1100
|
-
Defined in: [packages/core/src/constructors.ts:58](https://github.com/btravstack/unthrown/blob/
|
|
1144
|
+
Defined in: [packages/core/src/constructors.ts:58](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/constructors.ts#L58)
|
|
1101
1145
|
|
|
1102
1146
|
Type guard: narrow a [Result](#result) to its `Err` variant, exposing `.error`.
|
|
1103
1147
|
|
|
@@ -1128,7 +1172,7 @@ Type guard: narrow a [Result](#result) to its `Err` variant, exposing `.error`.
|
|
|
1128
1172
|
function isOk<T, E>(r): r is OkView<T, E>;
|
|
1129
1173
|
```
|
|
1130
1174
|
|
|
1131
|
-
Defined in: [packages/core/src/constructors.ts:50](https://github.com/btravstack/unthrown/blob/
|
|
1175
|
+
Defined in: [packages/core/src/constructors.ts:50](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/constructors.ts#L50)
|
|
1132
1176
|
|
|
1133
1177
|
Type guard: narrow a [Result](#result) to its `Ok` variant, exposing `.value`.
|
|
1134
1178
|
|
|
@@ -1161,6 +1205,38 @@ if (isOk(r)) r.value; // number, narrowed
|
|
|
1161
1205
|
|
|
1162
1206
|
***
|
|
1163
1207
|
|
|
1208
|
+
### isResult()
|
|
1209
|
+
|
|
1210
|
+
```ts
|
|
1211
|
+
function isResult(x): x is Result<unknown, unknown>;
|
|
1212
|
+
```
|
|
1213
|
+
|
|
1214
|
+
Defined in: [packages/core/src/core.ts:333](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/core.ts#L333)
|
|
1215
|
+
|
|
1216
|
+
Type guard: is `x` a [Result](#result) (any of `Ok` / `Err` / `Defect`)?
|
|
1217
|
+
|
|
1218
|
+
#### Parameters
|
|
1219
|
+
|
|
1220
|
+
| Parameter | Type |
|
|
1221
|
+
| ------ | ------ |
|
|
1222
|
+
| `x` | `unknown` |
|
|
1223
|
+
|
|
1224
|
+
#### Returns
|
|
1225
|
+
|
|
1226
|
+
`x is Result<unknown, unknown>`
|
|
1227
|
+
|
|
1228
|
+
`true` when `x` is a `Result` produced by this library.
|
|
1229
|
+
|
|
1230
|
+
#### Remarks
|
|
1231
|
+
|
|
1232
|
+
Unlike [isOk](#isok) / [isErr](#iserr) / [isDefect](#isdefect), which narrow a value
|
|
1233
|
+
already known to be a `Result`, this narrows from `unknown` — useful at an
|
|
1234
|
+
untyped boundary. It checks the value carries the `Result` prototype, so a
|
|
1235
|
+
look-alike plain object (`{ tag: "Ok" }`) is **not** matched. An `AsyncResult`
|
|
1236
|
+
is not a `Result` and returns `false`.
|
|
1237
|
+
|
|
1238
|
+
***
|
|
1239
|
+
|
|
1164
1240
|
### matchTags()
|
|
1165
1241
|
|
|
1166
1242
|
#### Call Signature
|
|
@@ -1169,7 +1245,7 @@ if (isOk(r)) r.value; // number, narrowed
|
|
|
1169
1245
|
function matchTags<T, E, R>(result, handlers): R;
|
|
1170
1246
|
```
|
|
1171
1247
|
|
|
1172
|
-
Defined in: [packages/core/src/tagged.ts:138](https://github.com/btravstack/unthrown/blob/
|
|
1248
|
+
Defined in: [packages/core/src/tagged.ts:138](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/tagged.ts#L138)
|
|
1173
1249
|
|
|
1174
1250
|
Exhaustively fold a [Result](#result) (or [AsyncResult](#asyncresult)) whose error type is
|
|
1175
1251
|
a tagged union, dispatching each error to the handler matching its `_tag`.
|
|
@@ -1221,7 +1297,7 @@ matchTags(r, {
|
|
|
1221
1297
|
function matchTags<T, E, R>(result, handlers): Promise<R>;
|
|
1222
1298
|
```
|
|
1223
1299
|
|
|
1224
|
-
Defined in: [packages/core/src/tagged.ts:142](https://github.com/btravstack/unthrown/blob/
|
|
1300
|
+
Defined in: [packages/core/src/tagged.ts:142](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/tagged.ts#L142)
|
|
1225
1301
|
|
|
1226
1302
|
Exhaustively fold a [Result](#result) (or [AsyncResult](#asyncresult)) whose error type is
|
|
1227
1303
|
a tagged union, dispatching each error to the handler matching its `_tag`.
|
|
@@ -1269,13 +1345,13 @@ matchTags(r, {
|
|
|
1269
1345
|
|
|
1270
1346
|
***
|
|
1271
1347
|
|
|
1272
|
-
###
|
|
1348
|
+
### Ok()
|
|
1273
1349
|
|
|
1274
1350
|
```ts
|
|
1275
|
-
function
|
|
1351
|
+
function Ok<T>(value): Result<T, never>;
|
|
1276
1352
|
```
|
|
1277
1353
|
|
|
1278
|
-
Defined in: [packages/core/src/constructors.ts:18](https://github.com/btravstack/unthrown/blob/
|
|
1354
|
+
Defined in: [packages/core/src/constructors.ts:18](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/constructors.ts#L18)
|
|
1279
1355
|
|
|
1280
1356
|
Construct a successful [Result](#result).
|
|
1281
1357
|
|
|
@@ -1298,8 +1374,8 @@ Construct a successful [Result](#result).
|
|
|
1298
1374
|
#### Example
|
|
1299
1375
|
|
|
1300
1376
|
```ts
|
|
1301
|
-
import {
|
|
1302
|
-
|
|
1377
|
+
import { Ok } from "unthrown";
|
|
1378
|
+
Ok(42).unwrap(); // 42
|
|
1303
1379
|
```
|
|
1304
1380
|
|
|
1305
1381
|
***
|
|
@@ -1310,7 +1386,7 @@ ok(42).unwrap(); // 42
|
|
|
1310
1386
|
function TaggedError<Tag>(tag, options?): TaggedErrorConstructor<Tag>;
|
|
1311
1387
|
```
|
|
1312
1388
|
|
|
1313
|
-
Defined in: [packages/core/src/tagged.ts:72](https://github.com/btravstack/unthrown/blob/
|
|
1389
|
+
Defined in: [packages/core/src/tagged.ts:72](https://github.com/btravstack/unthrown/blob/8424c0f1e5d5b49a3cb6853d52fb8d5085bd4701/packages/core/src/tagged.ts#L72)
|
|
1314
1390
|
|
|
1315
1391
|
Build a base class for a tagged error — a class extending `Error` with a
|
|
1316
1392
|
`_tag` string discriminant, in the style of Effect's `Data.TaggedError`.
|