unthrown 0.3.0 → 1.0.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 +172 -56
- package/dist/index.d.cts +128 -45
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.mts +128 -45
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +169 -54
- package/dist/index.mjs.map +1 -1
- package/docs/index.md +161 -119
- 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/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/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/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/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/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/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:442](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L442)
|
|
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:436](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L436)
|
|
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:352](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L352)
|
|
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,26 @@ 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:381](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L381) |
|
|
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:374](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L374) |
|
|
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:359](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L359) |
|
|
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:367](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L367) |
|
|
226
|
+
| `getOrNull()` | () => `Promise`<`T` \| `null`> | Asynchronous `getOrNull`. | [packages/core/src/types.ts:414](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L414) |
|
|
227
|
+
| `getOrUndefined()` | () => `Promise`<`T` \| `undefined`> | Asynchronous `getOrUndefined`. | [packages/core/src/types.ts:416](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L416) |
|
|
228
|
+
| `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:379](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L379) |
|
|
229
|
+
| `map()` | (`f`) => [`AsyncResult`](#asyncresult)<`U`, `E`> | Asynchronous `map`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:354](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L354) |
|
|
230
|
+
| `mapErr()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E2`> | Asynchronous `mapErr`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:384](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L384) |
|
|
231
|
+
| `match()` | (`cases`) => `Promise`<`R`> | Asynchronous `match`. Handlers are synchronous; resolves to `R`. | [packages/core/src/types.ts:400](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L400) |
|
|
232
|
+
| `orElse()` | (`f`) => [`AsyncResult`](#asyncresult)<`T` \| `U`, `E2`> | Asynchronous `orElse`. `f` may return a `Result` or an `AsyncResult`. | [packages/core/src/types.ts:386](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L386) |
|
|
233
|
+
| `recover()` | (`f`) => [`AsyncResult`](#asyncresult)<`T` \| `U`, `never`> | Asynchronous `recover`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:388](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L388) |
|
|
234
|
+
| `recoverDefect()` | (`f`) => [`AsyncResult`](#asyncresult)<`T` \| `U`, `E` \| `E2`> | Asynchronous `recoverDefect`. `f` may return a `Result` or an `AsyncResult`. | [packages/core/src/types.ts:393](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L393) |
|
|
235
|
+
| `tap()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E`> | Asynchronous `tap`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:361](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L361) |
|
|
236
|
+
| `tapDefect()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E`> | Asynchronous `tapDefect`. | [packages/core/src/types.ts:397](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L397) |
|
|
237
|
+
| `tapErr()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E`> | Asynchronous `tapErr`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:390](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L390) |
|
|
238
|
+
| `unwrap()` | () => `Promise`<`T`> | Asynchronous `unwrap`. The returned promise rejects on `Err`/`Defect`. | [packages/core/src/types.ts:406](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L406) |
|
|
239
|
+
| `unwrapErr()` | () => `Promise`<`E`> | Asynchronous `unwrapErr`. | [packages/core/src/types.ts:408](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L408) |
|
|
240
|
+
| `unwrapOr()` | (`fallback`) => `Promise`<`T`> | Asynchronous `unwrapOr`. | [packages/core/src/types.ts:410](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L410) |
|
|
241
|
+
| `unwrapOrElse()` | (`f`) => `Promise`<`T`> | Asynchronous `unwrapOrElse`. | [packages/core/src/types.ts:412](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L412) |
|
|
240
242
|
|
|
241
243
|
#### Type Parameters
|
|
242
244
|
|
|
@@ -266,7 +268,7 @@ To pattern-match an `AsyncResult`, `await` it first: `match(await ar)`.
|
|
|
266
268
|
type Awaitable<T> = object;
|
|
267
269
|
```
|
|
268
270
|
|
|
269
|
-
Defined in: [packages/core/src/types.ts:
|
|
271
|
+
Defined in: [packages/core/src/types.ts:329](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L329)
|
|
270
272
|
|
|
271
273
|
A success-only thenable: awaitable, but deliberately **not** a full
|
|
272
274
|
`PromiseLike`.
|
|
@@ -293,7 +295,7 @@ being treated as a raw promise (e.g. dropped into `Promise.all`).
|
|
|
293
295
|
then<R>(onfulfilled?): PromiseLike<R>;
|
|
294
296
|
```
|
|
295
297
|
|
|
296
|
-
Defined in: [packages/core/src/types.ts:
|
|
298
|
+
Defined in: [packages/core/src/types.ts:330](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L330)
|
|
297
299
|
|
|
298
300
|
###### Type Parameters
|
|
299
301
|
|
|
@@ -319,7 +321,7 @@ Defined in: [packages/core/src/types.ts:274](https://github.com/btravstack/unthr
|
|
|
319
321
|
type Defect = object;
|
|
320
322
|
```
|
|
321
323
|
|
|
322
|
-
Defined in: [packages/core/src/defect.ts:
|
|
324
|
+
Defined in: [packages/core/src/defect.ts:36](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/defect.ts#L36)
|
|
323
325
|
|
|
324
326
|
The marker a `qualify` function returns to triage a cause as **unexpected**.
|
|
325
327
|
|
|
@@ -327,7 +329,7 @@ The marker a `qualify` function returns to triage a cause as **unexpected**.
|
|
|
327
329
|
|
|
328
330
|
`qualify` (passed to [fromPromise](#frompromise) / [fromThrowable](#fromthrowable)) returns
|
|
329
331
|
`E | Defect`: either a modeled domain error, or a `Defect` produced by
|
|
330
|
-
[
|
|
332
|
+
[Defect](#defect-2) to say "this failure is not modeled". A `Defect` is opaque —
|
|
331
333
|
it carries the original cause for the boundary to convert into the third
|
|
332
334
|
runtime state of a `Result`.
|
|
333
335
|
|
|
@@ -335,8 +337,8 @@ runtime state of a `Result`.
|
|
|
335
337
|
|
|
336
338
|
| Property | Modifier | Type | Defined in |
|
|
337
339
|
| ------ | ------ | ------ | ------ |
|
|
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/
|
|
340
|
+
| <a id="defect-1"></a> `[DEFECT]` | `readonly` | `true` | [packages/core/src/defect.ts:16](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/defect.ts#L16) |
|
|
341
|
+
| <a id="cause-1"></a> `cause` | `readonly` | `unknown` | [packages/core/src/defect.ts:17](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/defect.ts#L17) |
|
|
340
342
|
|
|
341
343
|
***
|
|
342
344
|
|
|
@@ -346,7 +348,7 @@ runtime state of a `Result`.
|
|
|
346
348
|
type DefectView<T, E> = ResultMethods<T, E> & object;
|
|
347
349
|
```
|
|
348
350
|
|
|
349
|
-
Defined in: [packages/core/src/types.ts:
|
|
351
|
+
Defined in: [packages/core/src/types.ts:272](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L272)
|
|
350
352
|
|
|
351
353
|
The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `cause`.
|
|
352
354
|
|
|
@@ -354,8 +356,8 @@ The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `ca
|
|
|
354
356
|
|
|
355
357
|
| Name | Type | Defined in |
|
|
356
358
|
| ------ | ------ | ------ |
|
|
357
|
-
| `cause` | `unknown` | [packages/core/src/types.ts:
|
|
358
|
-
| `tag` | `"Defect"` | [packages/core/src/types.ts:
|
|
359
|
+
| `cause` | `unknown` | [packages/core/src/types.ts:274](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L274) |
|
|
360
|
+
| `tag` | `"Defect"` | [packages/core/src/types.ts:273](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L273) |
|
|
359
361
|
|
|
360
362
|
#### Type Parameters
|
|
361
363
|
|
|
@@ -372,7 +374,7 @@ The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `ca
|
|
|
372
374
|
type ErrOf<R> = R extends object ? E : never;
|
|
373
375
|
```
|
|
374
376
|
|
|
375
|
-
Defined in: [packages/core/src/types.ts:
|
|
377
|
+
Defined in: [packages/core/src/types.ts:430](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L430)
|
|
376
378
|
|
|
377
379
|
Extract the error type `E` from a `Result`.
|
|
378
380
|
|
|
@@ -390,7 +392,7 @@ Extract the error type `E` from a `Result`.
|
|
|
390
392
|
type ErrView<E, T> = ResultMethods<T, E> & object;
|
|
391
393
|
```
|
|
392
394
|
|
|
393
|
-
Defined in: [packages/core/src/types.ts:
|
|
395
|
+
Defined in: [packages/core/src/types.ts:267](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L267)
|
|
394
396
|
|
|
395
397
|
The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
|
|
396
398
|
|
|
@@ -398,8 +400,8 @@ The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
|
|
|
398
400
|
|
|
399
401
|
| Name | Type | Defined in |
|
|
400
402
|
| ------ | ------ | ------ |
|
|
401
|
-
| `error` | `E` | [packages/core/src/types.ts:
|
|
402
|
-
| `tag` | `"Err"` | [packages/core/src/types.ts:
|
|
403
|
+
| `error` | `E` | [packages/core/src/types.ts:269](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L269) |
|
|
404
|
+
| `tag` | `"Err"` | [packages/core/src/types.ts:268](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L268) |
|
|
403
405
|
|
|
404
406
|
#### Type Parameters
|
|
405
407
|
|
|
@@ -416,7 +418,7 @@ The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
|
|
|
416
418
|
type OkOf<R> = R extends object ? T : never;
|
|
417
419
|
```
|
|
418
420
|
|
|
419
|
-
Defined in: [packages/core/src/types.ts:
|
|
421
|
+
Defined in: [packages/core/src/types.ts:424](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L424)
|
|
420
422
|
|
|
421
423
|
Extract the success type `T` from a `Result`.
|
|
422
424
|
|
|
@@ -434,7 +436,7 @@ Extract the success type `T` from a `Result`.
|
|
|
434
436
|
type OkView<T, E> = ResultMethods<T, E> & object;
|
|
435
437
|
```
|
|
436
438
|
|
|
437
|
-
Defined in: [packages/core/src/types.ts:
|
|
439
|
+
Defined in: [packages/core/src/types.ts:262](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L262)
|
|
438
440
|
|
|
439
441
|
The `Ok` variant of a [Result](#result): a success carrying a `value`.
|
|
440
442
|
|
|
@@ -442,8 +444,8 @@ The `Ok` variant of a [Result](#result): a success carrying a `value`.
|
|
|
442
444
|
|
|
443
445
|
| Name | Type | Defined in |
|
|
444
446
|
| ------ | ------ | ------ |
|
|
445
|
-
| `tag` | `"Ok"` | [packages/core/src/types.ts:
|
|
446
|
-
| `value` | `T` | [packages/core/src/types.ts:
|
|
447
|
+
| `tag` | `"Ok"` | [packages/core/src/types.ts:263](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L263) |
|
|
448
|
+
| `value` | `T` | [packages/core/src/types.ts:264](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/types.ts#L264) |
|
|
447
449
|
|
|
448
450
|
#### Type Parameters
|
|
449
451
|
|
|
@@ -460,11 +462,11 @@ The `Ok` variant of a [Result](#result): a success carrying a `value`.
|
|
|
460
462
|
type Result<T, E> = ResultType<T, E>;
|
|
461
463
|
```
|
|
462
464
|
|
|
463
|
-
Defined in: [packages/core/src/facade.ts:
|
|
465
|
+
Defined in: [packages/core/src/facade.ts:43](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L43)
|
|
464
466
|
|
|
465
467
|
Companion object grouping the standalone entry points under a single,
|
|
466
|
-
discoverable namespace: [Result.
|
|
467
|
-
[Result.
|
|
468
|
+
discoverable namespace: [Result.Ok](#property-ok), [Result.Err](#property-err),
|
|
469
|
+
[Result.Defect](#property-defect), [Result.fromNullable](#property-fromnullable), [Result.fromThrowable](#property-fromthrowable),
|
|
468
470
|
[Result.fromPromise](#property-frompromise), [Result.fromSafePromise](#property-fromsafepromise), [Result.all](#property-all),
|
|
469
471
|
[Result.allAsync](#property-allasync), [Result.allFromDict](#property-allfromdict),
|
|
470
472
|
[Result.allFromDictAsync](#property-allfromdictasync), [Result.isOk](#property-isok), [Result.isErr](#property-iserr),
|
|
@@ -481,14 +483,14 @@ discoverable namespace: [Result.ok](#property-ok), [Result.err](#property-err),
|
|
|
481
483
|
|
|
482
484
|
Purely additive sugar — each member **is** the corresponding free function.
|
|
483
485
|
The free functions remain the primary, tree-shakeable API; importing only
|
|
484
|
-
`{
|
|
486
|
+
`{ Ok }` never pulls this object in. The value `Result` and the type
|
|
485
487
|
[Result](#result-1) share one name (the companion-object pattern).
|
|
486
488
|
|
|
487
489
|
#### Example
|
|
488
490
|
|
|
489
491
|
```ts
|
|
490
492
|
import { Result } from "unthrown";
|
|
491
|
-
Result.
|
|
493
|
+
Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // 2
|
|
492
494
|
```
|
|
493
495
|
|
|
494
496
|
***
|
|
@@ -499,7 +501,7 @@ Result.ok(1).flatMap((n) => Result.ok(n + 1)).unwrap(); // 2
|
|
|
499
501
|
type TaggedErrorConstructor<Tag> = <A>(args) => TaggedErrorInstance<Tag, A>;
|
|
500
502
|
```
|
|
501
503
|
|
|
502
|
-
Defined in: [packages/core/src/tagged.ts:28](https://github.com/btravstack/unthrown/blob/
|
|
504
|
+
Defined in: [packages/core/src/tagged.ts:28](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/tagged.ts#L28)
|
|
503
505
|
|
|
504
506
|
The class constructor returned by [TaggedError](#taggederror). Generic in its payload:
|
|
505
507
|
apply it with an instantiation expression at the `extends` site.
|
|
@@ -533,7 +535,7 @@ When the payload is empty, the constructor takes **no** arguments (the
|
|
|
533
535
|
type TaggedErrorInstance<Tag, A> = Error & Readonly<A> & object;
|
|
534
536
|
```
|
|
535
537
|
|
|
536
|
-
Defined in: [packages/core/src/tagged.ts:15](https://github.com/btravstack/unthrown/blob/
|
|
538
|
+
Defined in: [packages/core/src/tagged.ts:15](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/tagged.ts#L15)
|
|
537
539
|
|
|
538
540
|
The instance shape produced by a [TaggedError](#taggederror) class: an `Error` plus a
|
|
539
541
|
`_tag` discriminant and the (readonly) payload fields.
|
|
@@ -542,7 +544,7 @@ The instance shape produced by a [TaggedError](#taggederror) class: an `Error` p
|
|
|
542
544
|
|
|
543
545
|
| Name | Type | Defined in |
|
|
544
546
|
| ------ | ------ | ------ |
|
|
545
|
-
| `_tag` | `Tag` | [packages/core/src/tagged.ts:16](https://github.com/btravstack/unthrown/blob/
|
|
547
|
+
| `_tag` | `Tag` | [packages/core/src/tagged.ts:16](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/tagged.ts#L16) |
|
|
546
548
|
|
|
547
549
|
#### Type Parameters
|
|
548
550
|
|
|
@@ -559,7 +561,7 @@ The instance shape produced by a [TaggedError](#taggederror) class: an `Error` p
|
|
|
559
561
|
type TagHandlers<T, E, R> = object & { [K in E["_tag"]]: (error: Extract<E, { _tag: K }>) => R };
|
|
560
562
|
```
|
|
561
563
|
|
|
562
|
-
Defined in: [packages/core/src/tagged.ts:103](https://github.com/btravstack/unthrown/blob/
|
|
564
|
+
Defined in: [packages/core/src/tagged.ts:103](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/tagged.ts#L103)
|
|
563
565
|
|
|
564
566
|
The handler object [matchTags](#matchtags) requires: a branch per error tag, plus
|
|
565
567
|
`Ok` and `Defect`. Miss a tag and it will not compile — the exhaustiveness is
|
|
@@ -569,8 +571,8 @@ enforced by the type, with no `.exhaustive()` to forget.
|
|
|
569
571
|
|
|
570
572
|
| Name | Type | Defined in |
|
|
571
573
|
| ------ | ------ | ------ |
|
|
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/
|
|
574
|
+
| `Defect()` | (`cause`) => `R` | [packages/core/src/tagged.ts:105](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/tagged.ts#L105) |
|
|
575
|
+
| `Ok()` | (`value`) => `R` | [packages/core/src/tagged.ts:104](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/tagged.ts#L104) |
|
|
574
576
|
|
|
575
577
|
#### Type Parameters
|
|
576
578
|
|
|
@@ -588,11 +590,11 @@ enforced by the type, with no `.exhaustive()` to forget.
|
|
|
588
590
|
const Result: object;
|
|
589
591
|
```
|
|
590
592
|
|
|
591
|
-
Defined in: [packages/core/src/facade.ts:
|
|
593
|
+
Defined in: [packages/core/src/facade.ts:43](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L43)
|
|
592
594
|
|
|
593
595
|
Companion object grouping the standalone entry points under a single,
|
|
594
|
-
discoverable namespace: [Result.
|
|
595
|
-
[Result.
|
|
596
|
+
discoverable namespace: [Result.Ok](#property-ok), [Result.Err](#property-err),
|
|
597
|
+
[Result.Defect](#property-defect), [Result.fromNullable](#property-fromnullable), [Result.fromThrowable](#property-fromthrowable),
|
|
596
598
|
[Result.fromPromise](#property-frompromise), [Result.fromSafePromise](#property-fromsafepromise), [Result.all](#property-all),
|
|
597
599
|
[Result.allAsync](#property-allasync), [Result.allFromDict](#property-allfromdict),
|
|
598
600
|
[Result.allFromDictAsync](#property-allfromdictasync), [Result.isOk](#property-isok), [Result.isErr](#property-iserr),
|
|
@@ -602,33 +604,34 @@ discoverable namespace: [Result.ok](#property-ok), [Result.err](#property-err),
|
|
|
602
604
|
|
|
603
605
|
| Name | Type | Defined in |
|
|
604
606
|
| ------ | ------ | ------ |
|
|
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-
|
|
607
|
+
| <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:52](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L52) |
|
|
608
|
+
| <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:53](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L53) |
|
|
609
|
+
| <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:54](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L54) |
|
|
610
|
+
| <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:55](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L55) |
|
|
611
|
+
| <a id="property-defect"></a> `Defect()` | (`cause`) => [`Defect`](#defect) | [packages/core/src/facade.ts:46](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L46) |
|
|
612
|
+
| <a id="property-do"></a> `Do()` | () => `Result`<\{ \}, `never`> | [packages/core/src/facade.ts:47](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L47) |
|
|
613
|
+
| <a id="property-err"></a> `Err()` | <`E`>(`error`) => `Result`<`never`, `E`> | [packages/core/src/facade.ts:45](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L45) |
|
|
614
|
+
| <a id="property-fromnullable"></a> `fromNullable()` | <`T`, `E`>(`value`, `onAbsent`) => `Result`<`NonNullable`<`T`>, `E`> | [packages/core/src/facade.ts:48](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L48) |
|
|
615
|
+
| <a id="property-frompromise"></a> `fromPromise()` | <`T`, `R`>(`promise`, `qualify`) => [`AsyncResult`](#asyncresult)<`T`, `Exclude`<`R`, [`Defect`](#defect)>> | [packages/core/src/facade.ts:50](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L50) |
|
|
616
|
+
| <a id="property-fromsafepromise"></a> `fromSafePromise()` | <`T`>(`promise`) => [`AsyncResult`](#asyncresult)<`T`, `never`> | [packages/core/src/facade.ts:51](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L51) |
|
|
617
|
+
| <a id="property-fromthrowable"></a> `fromThrowable()` | <`A`, `T`, `R`>(`fn`, `qualify`) => (...`args`) => `Result`<`T`, `Exclude`<`R`, [`Defect`](#defect)>> | [packages/core/src/facade.ts:49](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L49) |
|
|
618
|
+
| <a id="property-isdefect"></a> `isDefect()` | <`T`, `E`>(`r`) => `r is DefectView<T, E>` | [packages/core/src/facade.ts:58](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L58) |
|
|
619
|
+
| <a id="property-iserr"></a> `isErr()` | <`T`, `E`>(`r`) => `r is ErrView<E, T>` | [packages/core/src/facade.ts:57](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L57) |
|
|
620
|
+
| <a id="property-isok"></a> `isOk()` | <`T`, `E`>(`r`) => `r is OkView<T, E>` | [packages/core/src/facade.ts:56](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L56) |
|
|
621
|
+
| <a id="property-ok"></a> `Ok()` | <`T`>(`value`) => `Result`<`T`, `never`> | [packages/core/src/facade.ts:44](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/facade.ts#L44) |
|
|
619
622
|
|
|
620
623
|
#### Remarks
|
|
621
624
|
|
|
622
625
|
Purely additive sugar — each member **is** the corresponding free function.
|
|
623
626
|
The free functions remain the primary, tree-shakeable API; importing only
|
|
624
|
-
`{
|
|
627
|
+
`{ Ok }` never pulls this object in. The value `Result` and the type
|
|
625
628
|
[Result](#result-1) share one name (the companion-object pattern).
|
|
626
629
|
|
|
627
630
|
#### Example
|
|
628
631
|
|
|
629
632
|
```ts
|
|
630
633
|
import { Result } from "unthrown";
|
|
631
|
-
Result.
|
|
634
|
+
Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // 2
|
|
632
635
|
```
|
|
633
636
|
|
|
634
637
|
## Functions
|
|
@@ -639,7 +642,7 @@ Result.ok(1).flatMap((n) => Result.ok(n + 1)).unwrap(); // 2
|
|
|
639
642
|
function all<Rs>(results): Result<AllOk<Rs, { [K in string | number | symbol]: OkOf<Rs[K]> }>, ErrOf<Rs[number]>>;
|
|
640
643
|
```
|
|
641
644
|
|
|
642
|
-
Defined in: [packages/core/src/interop.ts:249](https://github.com/btravstack/unthrown/blob/
|
|
645
|
+
Defined in: [packages/core/src/interop.ts:249](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/interop.ts#L249)
|
|
643
646
|
|
|
644
647
|
Collect a tuple/array of [Result](#result)s into a single `Result` of all their
|
|
645
648
|
success values.
|
|
@@ -664,7 +667,7 @@ success values.
|
|
|
664
667
|
|
|
665
668
|
Short-circuits on the **first** `Err` (later entries are not inspected for
|
|
666
669
|
their error); any `Defect` present **dominates**, winning even over an earlier
|
|
667
|
-
`Err`. A **fixed tuple** keeps its positional types — `all([
|
|
670
|
+
`Err`. A **fixed tuple** keeps its positional types — `all([Ok(1), Ok("a")])`
|
|
668
671
|
is `Result<[number, string], …>` — while a **dynamic array** `Result<T, E>[]`
|
|
669
672
|
collapses to `Result<T[], E>` with no cast. For a **record** keyed by name,
|
|
670
673
|
use [allFromDict](#allfromdict).
|
|
@@ -672,9 +675,9 @@ use [allFromDict](#allfromdict).
|
|
|
672
675
|
#### Example
|
|
673
676
|
|
|
674
677
|
```ts
|
|
675
|
-
import { all,
|
|
676
|
-
all([
|
|
677
|
-
all([
|
|
678
|
+
import { all, Ok } from "unthrown";
|
|
679
|
+
all([Ok(1), Ok("a"), Ok(true)]).unwrap(); // [1, "a", true] (typed [number, string, boolean])
|
|
680
|
+
all([Ok(1), Ok(2)] as Result<number, never>[]).unwrap(); // number[]
|
|
678
681
|
```
|
|
679
682
|
|
|
680
683
|
***
|
|
@@ -685,7 +688,7 @@ all([ok(1), ok(2)] as Result<number, never>[]).unwrap(); // number[]
|
|
|
685
688
|
function allAsync<Rs>(results): AsyncResult<AllOk<Rs, { [K in string | number | symbol]: AsyncOkOf<Rs[K]> }>, AsyncErrOf<Rs[number]>>;
|
|
686
689
|
```
|
|
687
690
|
|
|
688
|
-
Defined in: [packages/core/src/interop.ts:
|
|
691
|
+
Defined in: [packages/core/src/interop.ts:299](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/interop.ts#L299)
|
|
689
692
|
|
|
690
693
|
The asynchronous counterpart of [all](#all): combine a tuple/array of
|
|
691
694
|
[AsyncResult](#asyncresult)s into one `AsyncResult` of all their success values.
|
|
@@ -728,7 +731,7 @@ await allAsync([fromSafePromise(a()), fromSafePromise(b())]);
|
|
|
728
731
|
function allFromDict<R>(results): Result<{ [K in string | number | symbol]: OkOf<R[K]> }, ErrOf<R[keyof R]>>;
|
|
729
732
|
```
|
|
730
733
|
|
|
731
|
-
Defined in: [packages/core/src/interop.ts:274](https://github.com/btravstack/unthrown/blob/
|
|
734
|
+
Defined in: [packages/core/src/interop.ts:274](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/interop.ts#L274)
|
|
732
735
|
|
|
733
736
|
Collect a **record** of [Result](#result)s into a single `Result` of a record of
|
|
734
737
|
their success values — `allFromDict({ a: Result<A, E>, b: Result<B, E> })` is
|
|
@@ -759,8 +762,8 @@ dominates. This is **not** error accumulation.
|
|
|
759
762
|
#### Example
|
|
760
763
|
|
|
761
764
|
```ts
|
|
762
|
-
import { allFromDict,
|
|
763
|
-
allFromDict({ id:
|
|
765
|
+
import { allFromDict, Ok } from "unthrown";
|
|
766
|
+
allFromDict({ id: Ok(1), name: Ok("ada") }).unwrap(); // { id: 1, name: "ada" }
|
|
764
767
|
```
|
|
765
768
|
|
|
766
769
|
***
|
|
@@ -771,7 +774,7 @@ allFromDict({ id: ok(1), name: ok("ada") }).unwrap(); // { id: 1, name: "ada" }
|
|
|
771
774
|
function allFromDictAsync<R>(results): AsyncResult<{ [K in string | number | symbol]: AsyncOkOf<R[K]> }, AsyncErrOf<R[keyof R]>>;
|
|
772
775
|
```
|
|
773
776
|
|
|
774
|
-
Defined in: [packages/core/src/interop.ts:
|
|
777
|
+
Defined in: [packages/core/src/interop.ts:327](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/interop.ts#L327)
|
|
775
778
|
|
|
776
779
|
The asynchronous counterpart of [allFromDict](#allfromdict): combine a record of
|
|
777
780
|
[AsyncResult](#asyncresult)s into one `AsyncResult` of a record of their values.
|
|
@@ -806,15 +809,15 @@ await allFromDictAsync({ a: fromSafePromise(a()), b: fromSafePromise(b()) });
|
|
|
806
809
|
|
|
807
810
|
***
|
|
808
811
|
|
|
809
|
-
###
|
|
812
|
+
### Defect()
|
|
810
813
|
|
|
811
814
|
```ts
|
|
812
|
-
function
|
|
815
|
+
function Defect(cause): Defect;
|
|
813
816
|
```
|
|
814
817
|
|
|
815
|
-
Defined in: [packages/core/src/defect.ts:36](https://github.com/btravstack/unthrown/blob/
|
|
818
|
+
Defined in: [packages/core/src/defect.ts:36](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/defect.ts#L36)
|
|
816
819
|
|
|
817
|
-
Wrap a cause as a [Defect](#defect) — the value you return from a `qualify`
|
|
820
|
+
Wrap a cause as a [Defect](#defect-2) — the value you return from a `qualify`
|
|
818
821
|
function when a failure is **not** a modeled domain error.
|
|
819
822
|
|
|
820
823
|
#### Parameters
|
|
@@ -827,27 +830,66 @@ function when a failure is **not** a modeled domain error.
|
|
|
827
830
|
|
|
828
831
|
[`Defect`](#defect)
|
|
829
832
|
|
|
830
|
-
an opaque
|
|
833
|
+
an opaque Defect marker carrying `cause`.
|
|
831
834
|
|
|
832
835
|
#### Example
|
|
833
836
|
|
|
834
837
|
```ts
|
|
835
|
-
import { fromPromise,
|
|
838
|
+
import { fromPromise, Defect } from "unthrown";
|
|
836
839
|
|
|
837
840
|
const user = fromPromise(fetchUser(id), (cause) =>
|
|
838
|
-
cause instanceof NotFoundError ? cause :
|
|
841
|
+
cause instanceof NotFoundError ? cause : Defect(cause),
|
|
839
842
|
);
|
|
840
843
|
```
|
|
841
844
|
|
|
842
845
|
***
|
|
843
846
|
|
|
844
|
-
###
|
|
847
|
+
### Do()
|
|
845
848
|
|
|
846
849
|
```ts
|
|
847
|
-
function
|
|
850
|
+
function Do(): Result<{
|
|
851
|
+
}, never>;
|
|
848
852
|
```
|
|
849
853
|
|
|
850
|
-
Defined in: [packages/core/src/
|
|
854
|
+
Defined in: [packages/core/src/do.ts:30](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/do.ts#L30)
|
|
855
|
+
|
|
856
|
+
Start a do-notation chain with an empty object scope, grown step by step with
|
|
857
|
+
`bind` (for `Result`-returning steps) and `let` (for pure values).
|
|
858
|
+
|
|
859
|
+
#### Returns
|
|
860
|
+
|
|
861
|
+
`Result`<\{
|
|
862
|
+
\}, `never`>
|
|
863
|
+
|
|
864
|
+
#### Remarks
|
|
865
|
+
|
|
866
|
+
Capitalised because `do` is a reserved word. Each step receives the scope
|
|
867
|
+
accumulated so far; the error types union across `bind`s, and a throw in any
|
|
868
|
+
step becomes a `Defect`. To go asynchronous, lift the chain with `toAsync()`
|
|
869
|
+
(then a `bind` may return an `AsyncResult`).
|
|
870
|
+
|
|
871
|
+
#### Example
|
|
872
|
+
|
|
873
|
+
```ts
|
|
874
|
+
import { Do, Ok } from "unthrown";
|
|
875
|
+
|
|
876
|
+
const result = Do()
|
|
877
|
+
.bind("user", () => findUser(id)) // Result<User, NotFound>
|
|
878
|
+
.bind("org", ({ user }) => findOrg(user.orgId)) // Result<Org, NotFound>
|
|
879
|
+
.let("label", ({ user, org }) => `${user.name} @ ${org.name}`)
|
|
880
|
+
.map(({ user, org, label }) => render(user, org, label));
|
|
881
|
+
// Result<View, NotFound>
|
|
882
|
+
```
|
|
883
|
+
|
|
884
|
+
***
|
|
885
|
+
|
|
886
|
+
### Err()
|
|
887
|
+
|
|
888
|
+
```ts
|
|
889
|
+
function Err<E>(error): Result<never, E>;
|
|
890
|
+
```
|
|
891
|
+
|
|
892
|
+
Defined in: [packages/core/src/constructors.ts:34](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/constructors.ts#L34)
|
|
851
893
|
|
|
852
894
|
Construct a failed [Result](#result) carrying a **modeled** error.
|
|
853
895
|
|
|
@@ -870,8 +912,8 @@ Construct a failed [Result](#result) carrying a **modeled** error.
|
|
|
870
912
|
#### Example
|
|
871
913
|
|
|
872
914
|
```ts
|
|
873
|
-
import {
|
|
874
|
-
|
|
915
|
+
import { Err } from "unthrown";
|
|
916
|
+
Err("not_found").unwrapErr(); // "not_found"
|
|
875
917
|
```
|
|
876
918
|
|
|
877
919
|
***
|
|
@@ -882,7 +924,7 @@ err("not_found").unwrapErr(); // "not_found"
|
|
|
882
924
|
function fromNullable<T, E>(value, onAbsent): Result<NonNullable<T>, E>;
|
|
883
925
|
```
|
|
884
926
|
|
|
885
|
-
Defined in: [packages/core/src/interop.ts:29](https://github.com/btravstack/unthrown/blob/
|
|
927
|
+
Defined in: [packages/core/src/interop.ts:29](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/interop.ts#L29)
|
|
886
928
|
|
|
887
929
|
Bridge a nullable value into a [Result](#result): absence becomes a **modeled**
|
|
888
930
|
`Err`. The sanctioned alternative to an `Option` type.
|
|
@@ -907,7 +949,7 @@ Bridge a nullable value into a [Result](#result): absence becomes a **modeled**
|
|
|
907
949
|
|
|
908
950
|
#### Remarks
|
|
909
951
|
|
|
910
|
-
`null` and `undefined` map to `
|
|
952
|
+
`null` and `undefined` map to `Err(onAbsent())`; any other value (including
|
|
911
953
|
falsy ones like `0`, `""`, `false`) maps to `Ok`.
|
|
912
954
|
|
|
913
955
|
#### Example
|
|
@@ -925,7 +967,7 @@ fromNullable(map.get(key), () => "missing").unwrap();
|
|
|
925
967
|
function fromPromise<T, R>(promise, qualify): AsyncResult<T, Exclude<R, Defect>>;
|
|
926
968
|
```
|
|
927
969
|
|
|
928
|
-
Defined in: [packages/core/src/interop.ts:110](https://github.com/btravstack/unthrown/blob/
|
|
970
|
+
Defined in: [packages/core/src/interop.ts:110](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/interop.ts#L110)
|
|
929
971
|
|
|
930
972
|
Wrap a `Promise` (or a thunk producing one) as an [AsyncResult](#asyncresult), forcing
|
|
931
973
|
every rejection to be triaged.
|
|
@@ -951,21 +993,21 @@ every rejection to be triaged.
|
|
|
951
993
|
#### Remarks
|
|
952
994
|
|
|
953
995
|
`qualify` **must** map each rejection cause into a modeled error `E` or a
|
|
954
|
-
[Defect](#defect). The returned `AsyncResult`'s internal promise never rejects;
|
|
996
|
+
[Defect](#defect-2). The returned `AsyncResult`'s internal promise never rejects;
|
|
955
997
|
`await`-ing it always yields a `Result`. A throw inside `qualify` is itself a
|
|
956
998
|
`Defect`.
|
|
957
999
|
|
|
958
1000
|
The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
|
|
959
1001
|
`qualify`'s return is **subtracted** from `E`, never inferred into it. So a
|
|
960
|
-
`qualify` that returns *only* `
|
|
961
|
-
rejection is a
|
|
1002
|
+
`qualify` that returns *only* `Defect(cause)` yields `E = never`; when every
|
|
1003
|
+
rejection is a Defect, prefer [fromSafePromise](#fromsafepromise).
|
|
962
1004
|
|
|
963
1005
|
#### Example
|
|
964
1006
|
|
|
965
1007
|
```ts
|
|
966
|
-
import { fromPromise,
|
|
1008
|
+
import { fromPromise, Defect } from "unthrown";
|
|
967
1009
|
const user = await fromPromise(fetchUser(id), (cause) =>
|
|
968
|
-
cause instanceof NotFoundError ? ("not_found" as const) :
|
|
1010
|
+
cause instanceof NotFoundError ? ("not_found" as const) : Defect(cause),
|
|
969
1011
|
);
|
|
970
1012
|
```
|
|
971
1013
|
|
|
@@ -977,7 +1019,7 @@ const user = await fromPromise(fetchUser(id), (cause) =>
|
|
|
977
1019
|
function fromSafePromise<T>(promise): AsyncResult<T, never>;
|
|
978
1020
|
```
|
|
979
1021
|
|
|
980
|
-
Defined in: [packages/core/src/interop.ts:136](https://github.com/btravstack/unthrown/blob/
|
|
1022
|
+
Defined in: [packages/core/src/interop.ts:136](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/interop.ts#L136)
|
|
981
1023
|
|
|
982
1024
|
Wrap a `Promise` asserted **not** to fail in any modeled way: any rejection
|
|
983
1025
|
becomes a `Defect`.
|
|
@@ -1012,7 +1054,7 @@ triage. (`await`-ing still yields a `Result`; it never throws.)
|
|
|
1012
1054
|
function fromThrowable<A, T, R>(fn, qualify): (...args) => Result<T, Exclude<R, Defect>>;
|
|
1013
1055
|
```
|
|
1014
1056
|
|
|
1015
|
-
Defined in: [packages/core/src/interop.ts:66](https://github.com/btravstack/unthrown/blob/
|
|
1057
|
+
Defined in: [packages/core/src/interop.ts:66](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/interop.ts#L66)
|
|
1016
1058
|
|
|
1017
1059
|
Wrap a throwing synchronous function so it returns a [Result](#result) instead of
|
|
1018
1060
|
throwing.
|
|
@@ -1041,20 +1083,20 @@ a function with the same arguments returning `Result<T, E>`.
|
|
|
1041
1083
|
#### Remarks
|
|
1042
1084
|
|
|
1043
1085
|
`qualify` **must** triage every thrown cause into a modeled error `E` or a
|
|
1044
|
-
[Defect](#defect) (via [
|
|
1086
|
+
[Defect](#defect-2) (via [Defect](#defect-2)) — there is no path that leaves `unknown`
|
|
1045
1087
|
in `E`. A throw inside `qualify` itself is treated as a `Defect`.
|
|
1046
1088
|
|
|
1047
1089
|
The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
|
|
1048
1090
|
`qualify`'s return is **subtracted** from `E`, never inferred into it. So a
|
|
1049
|
-
`qualify` that returns *only* `
|
|
1091
|
+
`qualify` that returns *only* `Defect(cause)` yields `E = never` (a Defect is
|
|
1050
1092
|
out-of-band and must not pollute the error channel); reach for
|
|
1051
|
-
[fromSafePromise](#fromsafepromise) when every failure is a
|
|
1093
|
+
[fromSafePromise](#fromsafepromise) when every failure is a Defect.
|
|
1052
1094
|
|
|
1053
1095
|
#### Example
|
|
1054
1096
|
|
|
1055
1097
|
```ts
|
|
1056
|
-
import { fromThrowable,
|
|
1057
|
-
const parse = fromThrowable(JSON.parse, (cause) =>
|
|
1098
|
+
import { fromThrowable, Defect } from "unthrown";
|
|
1099
|
+
const parse = fromThrowable(JSON.parse, (cause) => Defect(cause));
|
|
1058
1100
|
parse("{}").unwrap();
|
|
1059
1101
|
```
|
|
1060
1102
|
|
|
@@ -1066,7 +1108,7 @@ parse("{}").unwrap();
|
|
|
1066
1108
|
function isDefect<T, E>(r): r is DefectView<T, E>;
|
|
1067
1109
|
```
|
|
1068
1110
|
|
|
1069
|
-
Defined in: [packages/core/src/constructors.ts:66](https://github.com/btravstack/unthrown/blob/
|
|
1111
|
+
Defined in: [packages/core/src/constructors.ts:66](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/constructors.ts#L66)
|
|
1070
1112
|
|
|
1071
1113
|
Type guard: narrow a [Result](#result) to its `Defect` variant, exposing `.cause`.
|
|
1072
1114
|
|
|
@@ -1097,7 +1139,7 @@ Type guard: narrow a [Result](#result) to its `Defect` variant, exposing `.cause
|
|
|
1097
1139
|
function isErr<T, E>(r): r is ErrView<E, T>;
|
|
1098
1140
|
```
|
|
1099
1141
|
|
|
1100
|
-
Defined in: [packages/core/src/constructors.ts:58](https://github.com/btravstack/unthrown/blob/
|
|
1142
|
+
Defined in: [packages/core/src/constructors.ts:58](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/constructors.ts#L58)
|
|
1101
1143
|
|
|
1102
1144
|
Type guard: narrow a [Result](#result) to its `Err` variant, exposing `.error`.
|
|
1103
1145
|
|
|
@@ -1128,7 +1170,7 @@ Type guard: narrow a [Result](#result) to its `Err` variant, exposing `.error`.
|
|
|
1128
1170
|
function isOk<T, E>(r): r is OkView<T, E>;
|
|
1129
1171
|
```
|
|
1130
1172
|
|
|
1131
|
-
Defined in: [packages/core/src/constructors.ts:50](https://github.com/btravstack/unthrown/blob/
|
|
1173
|
+
Defined in: [packages/core/src/constructors.ts:50](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/constructors.ts#L50)
|
|
1132
1174
|
|
|
1133
1175
|
Type guard: narrow a [Result](#result) to its `Ok` variant, exposing `.value`.
|
|
1134
1176
|
|
|
@@ -1169,7 +1211,7 @@ if (isOk(r)) r.value; // number, narrowed
|
|
|
1169
1211
|
function matchTags<T, E, R>(result, handlers): R;
|
|
1170
1212
|
```
|
|
1171
1213
|
|
|
1172
|
-
Defined in: [packages/core/src/tagged.ts:138](https://github.com/btravstack/unthrown/blob/
|
|
1214
|
+
Defined in: [packages/core/src/tagged.ts:138](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/tagged.ts#L138)
|
|
1173
1215
|
|
|
1174
1216
|
Exhaustively fold a [Result](#result) (or [AsyncResult](#asyncresult)) whose error type is
|
|
1175
1217
|
a tagged union, dispatching each error to the handler matching its `_tag`.
|
|
@@ -1221,7 +1263,7 @@ matchTags(r, {
|
|
|
1221
1263
|
function matchTags<T, E, R>(result, handlers): Promise<R>;
|
|
1222
1264
|
```
|
|
1223
1265
|
|
|
1224
|
-
Defined in: [packages/core/src/tagged.ts:142](https://github.com/btravstack/unthrown/blob/
|
|
1266
|
+
Defined in: [packages/core/src/tagged.ts:142](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/tagged.ts#L142)
|
|
1225
1267
|
|
|
1226
1268
|
Exhaustively fold a [Result](#result) (or [AsyncResult](#asyncresult)) whose error type is
|
|
1227
1269
|
a tagged union, dispatching each error to the handler matching its `_tag`.
|
|
@@ -1269,13 +1311,13 @@ matchTags(r, {
|
|
|
1269
1311
|
|
|
1270
1312
|
***
|
|
1271
1313
|
|
|
1272
|
-
###
|
|
1314
|
+
### Ok()
|
|
1273
1315
|
|
|
1274
1316
|
```ts
|
|
1275
|
-
function
|
|
1317
|
+
function Ok<T>(value): Result<T, never>;
|
|
1276
1318
|
```
|
|
1277
1319
|
|
|
1278
|
-
Defined in: [packages/core/src/constructors.ts:18](https://github.com/btravstack/unthrown/blob/
|
|
1320
|
+
Defined in: [packages/core/src/constructors.ts:18](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/constructors.ts#L18)
|
|
1279
1321
|
|
|
1280
1322
|
Construct a successful [Result](#result).
|
|
1281
1323
|
|
|
@@ -1298,8 +1340,8 @@ Construct a successful [Result](#result).
|
|
|
1298
1340
|
#### Example
|
|
1299
1341
|
|
|
1300
1342
|
```ts
|
|
1301
|
-
import {
|
|
1302
|
-
|
|
1343
|
+
import { Ok } from "unthrown";
|
|
1344
|
+
Ok(42).unwrap(); // 42
|
|
1303
1345
|
```
|
|
1304
1346
|
|
|
1305
1347
|
***
|
|
@@ -1310,7 +1352,7 @@ ok(42).unwrap(); // 42
|
|
|
1310
1352
|
function TaggedError<Tag>(tag, options?): TaggedErrorConstructor<Tag>;
|
|
1311
1353
|
```
|
|
1312
1354
|
|
|
1313
|
-
Defined in: [packages/core/src/tagged.ts:72](https://github.com/btravstack/unthrown/blob/
|
|
1355
|
+
Defined in: [packages/core/src/tagged.ts:72](https://github.com/btravstack/unthrown/blob/fa4c17ddc81bb2075e8f48dfcc49e5e04d951dd1/packages/core/src/tagged.ts#L72)
|
|
1314
1356
|
|
|
1315
1357
|
Build a base class for a tagged error — a class extending `Error` with a
|
|
1316
1358
|
`_tag` string discriminant, in the style of Effect's `Data.TaggedError`.
|