unthrown 0.1.0 → 0.3.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/dist/index.cjs +176 -24
- package/dist/index.d.cts +167 -22
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.mts +167 -22
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +174 -25
- package/dist/index.mjs.map +1 -1
- package/docs/index.md +299 -95
- package/package.json +1 -1
package/docs/index.md
CHANGED
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
|
|
9
9
|
### UnwrapError
|
|
10
10
|
|
|
11
|
-
Defined in: [packages/core/src/core.ts:29](https://github.com/btravstack/unthrown/blob/
|
|
11
|
+
Defined in: [packages/core/src/core.ts:29](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/core.ts#L29)
|
|
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:35](https://github.com/btravstack/unthrown/blob/
|
|
40
|
+
Defined in: [packages/core/src/core.ts:35](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/core.ts#L35)
|
|
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:34](https://github.com/btravstack/unthrown/blob/
|
|
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:34](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/core.ts#L34) |
|
|
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 |
|
|
@@ -168,13 +168,49 @@ Error.prepareStackTrace
|
|
|
168
168
|
|
|
169
169
|
## Type Aliases
|
|
170
170
|
|
|
171
|
+
### AsyncErrOf
|
|
172
|
+
|
|
173
|
+
```ts
|
|
174
|
+
type AsyncErrOf<R> = R extends AsyncResult<unknown, infer E> ? E : never;
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
Defined in: [packages/core/src/types.ts:376](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L376)
|
|
178
|
+
|
|
179
|
+
Extract the error type `E` from an [AsyncResult](#asyncresult).
|
|
180
|
+
|
|
181
|
+
#### Type Parameters
|
|
182
|
+
|
|
183
|
+
| Type Parameter | Description |
|
|
184
|
+
| ------ | ------ |
|
|
185
|
+
| `R` | the `AsyncResult` type to inspect. |
|
|
186
|
+
|
|
187
|
+
***
|
|
188
|
+
|
|
189
|
+
### AsyncOkOf
|
|
190
|
+
|
|
191
|
+
```ts
|
|
192
|
+
type AsyncOkOf<R> = R extends AsyncResult<infer T, unknown> ? T : never;
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
Defined in: [packages/core/src/types.ts:370](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L370)
|
|
196
|
+
|
|
197
|
+
Extract the success type `T` from an [AsyncResult](#asyncresult).
|
|
198
|
+
|
|
199
|
+
#### Type Parameters
|
|
200
|
+
|
|
201
|
+
| Type Parameter | Description |
|
|
202
|
+
| ------ | ------ |
|
|
203
|
+
| `R` | the `AsyncResult` type to inspect. |
|
|
204
|
+
|
|
205
|
+
***
|
|
206
|
+
|
|
171
207
|
### AsyncResult
|
|
172
208
|
|
|
173
209
|
```ts
|
|
174
210
|
type AsyncResult<T, E> = Awaitable<Result<T, E>> & object;
|
|
175
211
|
```
|
|
176
212
|
|
|
177
|
-
Defined in: [packages/core/src/types.ts:
|
|
213
|
+
Defined in: [packages/core/src/types.ts:296](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L296)
|
|
178
214
|
|
|
179
215
|
The asynchronous counterpart of [Result](#result): an awaitable wrapper with the
|
|
180
216
|
same method surface, collapsing to a `Result<T, E>` when `await`-ed.
|
|
@@ -183,23 +219,24 @@ same method surface, collapsing to a `Result<T, E>` when `await`-ed.
|
|
|
183
219
|
|
|
184
220
|
| Name | Type | Description | Defined in |
|
|
185
221
|
| ------ | ------ | ------ | ------ |
|
|
186
|
-
| `as()` | (`value`) => [`AsyncResult`](#asyncresult)<`U`, `E`> | Asynchronous `as`. | [packages/core/src/types.ts:
|
|
187
|
-
| `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:
|
|
188
|
-
| `
|
|
189
|
-
| `
|
|
190
|
-
| `
|
|
191
|
-
| `
|
|
192
|
-
| `
|
|
193
|
-
| `
|
|
194
|
-
| `
|
|
195
|
-
| `
|
|
196
|
-
| `
|
|
197
|
-
| `
|
|
198
|
-
| `
|
|
199
|
-
| `
|
|
200
|
-
| `
|
|
201
|
-
| `
|
|
202
|
-
| `
|
|
222
|
+
| `as()` | (`value`) => [`AsyncResult`](#asyncresult)<`U`, `E`> | Asynchronous `as`. | [packages/core/src/types.ts:315](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L315) |
|
|
223
|
+
| `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:303](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L303) |
|
|
224
|
+
| `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:311](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L311) |
|
|
225
|
+
| `getOrNull()` | () => `Promise`<`T` \| `null`> | Asynchronous `getOrNull`. | [packages/core/src/types.ts:348](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L348) |
|
|
226
|
+
| `getOrUndefined()` | () => `Promise`<`T` \| `undefined`> | Asynchronous `getOrUndefined`. | [packages/core/src/types.ts:350](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L350) |
|
|
227
|
+
| `map()` | (`f`) => [`AsyncResult`](#asyncresult)<`U`, `E`> | Asynchronous `map`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:298](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L298) |
|
|
228
|
+
| `mapErr()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E2`> | Asynchronous `mapErr`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:318](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L318) |
|
|
229
|
+
| `match()` | (`cases`) => `Promise`<`R`> | Asynchronous `match`. Handlers are synchronous; resolves to `R`. | [packages/core/src/types.ts:334](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L334) |
|
|
230
|
+
| `orElse()` | (`f`) => [`AsyncResult`](#asyncresult)<`T` \| `U`, `E2`> | Asynchronous `orElse`. `f` may return a `Result` or an `AsyncResult`. | [packages/core/src/types.ts:320](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L320) |
|
|
231
|
+
| `recover()` | (`f`) => [`AsyncResult`](#asyncresult)<`T` \| `U`, `never`> | Asynchronous `recover`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:322](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L322) |
|
|
232
|
+
| `recoverDefect()` | (`f`) => [`AsyncResult`](#asyncresult)<`T` \| `U`, `E` \| `E2`> | Asynchronous `recoverDefect`. `f` may return a `Result` or an `AsyncResult`. | [packages/core/src/types.ts:327](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L327) |
|
|
233
|
+
| `tap()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E`> | Asynchronous `tap`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:305](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L305) |
|
|
234
|
+
| `tapDefect()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E`> | Asynchronous `tapDefect`. | [packages/core/src/types.ts:331](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L331) |
|
|
235
|
+
| `tapErr()` | (`f`) => [`AsyncResult`](#asyncresult)<`T`, `E`> | Asynchronous `tapErr`. `f` is synchronous; a throw becomes a `Defect`. | [packages/core/src/types.ts:324](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L324) |
|
|
236
|
+
| `unwrap()` | () => `Promise`<`T`> | Asynchronous `unwrap`. The returned promise rejects on `Err`/`Defect`. | [packages/core/src/types.ts:340](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L340) |
|
|
237
|
+
| `unwrapErr()` | () => `Promise`<`E`> | Asynchronous `unwrapErr`. | [packages/core/src/types.ts:342](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L342) |
|
|
238
|
+
| `unwrapOr()` | (`fallback`) => `Promise`<`T`> | Asynchronous `unwrapOr`. | [packages/core/src/types.ts:344](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L344) |
|
|
239
|
+
| `unwrapOrElse()` | (`f`) => `Promise`<`T`> | Asynchronous `unwrapOrElse`. | [packages/core/src/types.ts:346](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L346) |
|
|
203
240
|
|
|
204
241
|
#### Type Parameters
|
|
205
242
|
|
|
@@ -216,7 +253,8 @@ rejection would silently become a `Defect`, skipping the triage that
|
|
|
216
253
|
[fromPromise](#frompromise) forces. To do further async work, re-enter through a
|
|
217
254
|
qualified boundary and compose it: `ar.flatMap((v) => fromPromise(work(v),
|
|
218
255
|
qualify))`. The eliminators (`unwrap`, …) return promises; the binds
|
|
219
|
-
(`flatMap`, `orElse`, `recoverDefect`) additionally accept an
|
|
256
|
+
(`flatMap`, `flatTap`, `orElse`, `recoverDefect`) additionally accept an
|
|
257
|
+
`AsyncResult`.
|
|
220
258
|
|
|
221
259
|
To pattern-match an `AsyncResult`, `await` it first: `match(await ar)`.
|
|
222
260
|
|
|
@@ -228,7 +266,7 @@ To pattern-match an `AsyncResult`, `await` it first: `match(await ar)`.
|
|
|
228
266
|
type Awaitable<T> = object;
|
|
229
267
|
```
|
|
230
268
|
|
|
231
|
-
Defined in: [packages/core/src/types.ts:
|
|
269
|
+
Defined in: [packages/core/src/types.ts:273](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L273)
|
|
232
270
|
|
|
233
271
|
A success-only thenable: awaitable, but deliberately **not** a full
|
|
234
272
|
`PromiseLike`.
|
|
@@ -255,7 +293,7 @@ being treated as a raw promise (e.g. dropped into `Promise.all`).
|
|
|
255
293
|
then<R>(onfulfilled?): PromiseLike<R>;
|
|
256
294
|
```
|
|
257
295
|
|
|
258
|
-
Defined in: [packages/core/src/types.ts:
|
|
296
|
+
Defined in: [packages/core/src/types.ts:274](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L274)
|
|
259
297
|
|
|
260
298
|
###### Type Parameters
|
|
261
299
|
|
|
@@ -281,7 +319,7 @@ Defined in: [packages/core/src/types.ts:257](https://github.com/btravstack/unthr
|
|
|
281
319
|
type Defect = object;
|
|
282
320
|
```
|
|
283
321
|
|
|
284
|
-
Defined in: [packages/core/src/defect.ts:15](https://github.com/btravstack/unthrown/blob/
|
|
322
|
+
Defined in: [packages/core/src/defect.ts:15](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/defect.ts#L15)
|
|
285
323
|
|
|
286
324
|
The marker a `qualify` function returns to triage a cause as **unexpected**.
|
|
287
325
|
|
|
@@ -297,8 +335,8 @@ runtime state of a `Result`.
|
|
|
297
335
|
|
|
298
336
|
| Property | Modifier | Type | Defined in |
|
|
299
337
|
| ------ | ------ | ------ | ------ |
|
|
300
|
-
| <a id="defect-1"></a> `[DEFECT]` | `readonly` | `true` | [packages/core/src/defect.ts:16](https://github.com/btravstack/unthrown/blob/
|
|
301
|
-
| <a id="cause-1"></a> `cause` | `readonly` | `unknown` | [packages/core/src/defect.ts:17](https://github.com/btravstack/unthrown/blob/
|
|
338
|
+
| <a id="defect-1"></a> `[DEFECT]` | `readonly` | `true` | [packages/core/src/defect.ts:16](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/defect.ts#L16) |
|
|
339
|
+
| <a id="cause-1"></a> `cause` | `readonly` | `unknown` | [packages/core/src/defect.ts:17](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/defect.ts#L17) |
|
|
302
340
|
|
|
303
341
|
***
|
|
304
342
|
|
|
@@ -308,7 +346,7 @@ runtime state of a `Result`.
|
|
|
308
346
|
type DefectView<T, E> = ResultMethods<T, E> & object;
|
|
309
347
|
```
|
|
310
348
|
|
|
311
|
-
Defined in: [packages/core/src/types.ts:
|
|
349
|
+
Defined in: [packages/core/src/types.ts:216](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L216)
|
|
312
350
|
|
|
313
351
|
The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `cause`.
|
|
314
352
|
|
|
@@ -316,8 +354,8 @@ The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `ca
|
|
|
316
354
|
|
|
317
355
|
| Name | Type | Defined in |
|
|
318
356
|
| ------ | ------ | ------ |
|
|
319
|
-
| `cause` | `unknown` | [packages/core/src/types.ts:
|
|
320
|
-
| `tag` | `"Defect"` | [packages/core/src/types.ts:
|
|
357
|
+
| `cause` | `unknown` | [packages/core/src/types.ts:218](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L218) |
|
|
358
|
+
| `tag` | `"Defect"` | [packages/core/src/types.ts:217](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L217) |
|
|
321
359
|
|
|
322
360
|
#### Type Parameters
|
|
323
361
|
|
|
@@ -334,7 +372,7 @@ The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `ca
|
|
|
334
372
|
type ErrOf<R> = R extends object ? E : never;
|
|
335
373
|
```
|
|
336
374
|
|
|
337
|
-
Defined in: [packages/core/src/types.ts:
|
|
375
|
+
Defined in: [packages/core/src/types.ts:364](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L364)
|
|
338
376
|
|
|
339
377
|
Extract the error type `E` from a `Result`.
|
|
340
378
|
|
|
@@ -352,7 +390,7 @@ Extract the error type `E` from a `Result`.
|
|
|
352
390
|
type ErrView<E, T> = ResultMethods<T, E> & object;
|
|
353
391
|
```
|
|
354
392
|
|
|
355
|
-
Defined in: [packages/core/src/types.ts:
|
|
393
|
+
Defined in: [packages/core/src/types.ts:211](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L211)
|
|
356
394
|
|
|
357
395
|
The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
|
|
358
396
|
|
|
@@ -360,8 +398,8 @@ The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
|
|
|
360
398
|
|
|
361
399
|
| Name | Type | Defined in |
|
|
362
400
|
| ------ | ------ | ------ |
|
|
363
|
-
| `error` | `E` | [packages/core/src/types.ts:
|
|
364
|
-
| `tag` | `"Err"` | [packages/core/src/types.ts:
|
|
401
|
+
| `error` | `E` | [packages/core/src/types.ts:213](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L213) |
|
|
402
|
+
| `tag` | `"Err"` | [packages/core/src/types.ts:212](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L212) |
|
|
365
403
|
|
|
366
404
|
#### Type Parameters
|
|
367
405
|
|
|
@@ -378,7 +416,7 @@ The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
|
|
|
378
416
|
type OkOf<R> = R extends object ? T : never;
|
|
379
417
|
```
|
|
380
418
|
|
|
381
|
-
Defined in: [packages/core/src/types.ts:
|
|
419
|
+
Defined in: [packages/core/src/types.ts:358](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L358)
|
|
382
420
|
|
|
383
421
|
Extract the success type `T` from a `Result`.
|
|
384
422
|
|
|
@@ -396,7 +434,7 @@ Extract the success type `T` from a `Result`.
|
|
|
396
434
|
type OkView<T, E> = ResultMethods<T, E> & object;
|
|
397
435
|
```
|
|
398
436
|
|
|
399
|
-
Defined in: [packages/core/src/types.ts:
|
|
437
|
+
Defined in: [packages/core/src/types.ts:206](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L206)
|
|
400
438
|
|
|
401
439
|
The `Ok` variant of a [Result](#result): a success carrying a `value`.
|
|
402
440
|
|
|
@@ -404,8 +442,8 @@ The `Ok` variant of a [Result](#result): a success carrying a `value`.
|
|
|
404
442
|
|
|
405
443
|
| Name | Type | Defined in |
|
|
406
444
|
| ------ | ------ | ------ |
|
|
407
|
-
| `tag` | `"Ok"` | [packages/core/src/types.ts:
|
|
408
|
-
| `value` | `T` | [packages/core/src/types.ts:
|
|
445
|
+
| `tag` | `"Ok"` | [packages/core/src/types.ts:207](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L207) |
|
|
446
|
+
| `value` | `T` | [packages/core/src/types.ts:208](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/types.ts#L208) |
|
|
409
447
|
|
|
410
448
|
#### Type Parameters
|
|
411
449
|
|
|
@@ -422,13 +460,15 @@ The `Ok` variant of a [Result](#result): a success carrying a `value`.
|
|
|
422
460
|
type Result<T, E> = ResultType<T, E>;
|
|
423
461
|
```
|
|
424
462
|
|
|
425
|
-
Defined in: [packages/core/src/facade.ts:
|
|
463
|
+
Defined in: [packages/core/src/facade.ts:42](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L42)
|
|
426
464
|
|
|
427
465
|
Companion object grouping the standalone entry points under a single,
|
|
428
466
|
discoverable namespace: [Result.ok](#property-ok), [Result.err](#property-err),
|
|
429
467
|
[Result.defect](#property-defect), [Result.fromNullable](#property-fromnullable), [Result.fromThrowable](#property-fromthrowable),
|
|
430
468
|
[Result.fromPromise](#property-frompromise), [Result.fromSafePromise](#property-fromsafepromise), [Result.all](#property-all),
|
|
431
|
-
[Result.
|
|
469
|
+
[Result.allAsync](#property-allasync), [Result.allFromDict](#property-allfromdict),
|
|
470
|
+
[Result.allFromDictAsync](#property-allfromdictasync), [Result.isOk](#property-isok), [Result.isErr](#property-iserr),
|
|
471
|
+
[Result.isDefect](#property-isdefect).
|
|
432
472
|
|
|
433
473
|
#### Type Parameters
|
|
434
474
|
|
|
@@ -459,7 +499,7 @@ Result.ok(1).flatMap((n) => Result.ok(n + 1)).unwrap(); // 2
|
|
|
459
499
|
type TaggedErrorConstructor<Tag> = <A>(args) => TaggedErrorInstance<Tag, A>;
|
|
460
500
|
```
|
|
461
501
|
|
|
462
|
-
Defined in: [packages/core/src/tagged.ts:28](https://github.com/btravstack/unthrown/blob/
|
|
502
|
+
Defined in: [packages/core/src/tagged.ts:28](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/tagged.ts#L28)
|
|
463
503
|
|
|
464
504
|
The class constructor returned by [TaggedError](#taggederror). Generic in its payload:
|
|
465
505
|
apply it with an instantiation expression at the `extends` site.
|
|
@@ -493,7 +533,7 @@ When the payload is empty, the constructor takes **no** arguments (the
|
|
|
493
533
|
type TaggedErrorInstance<Tag, A> = Error & Readonly<A> & object;
|
|
494
534
|
```
|
|
495
535
|
|
|
496
|
-
Defined in: [packages/core/src/tagged.ts:15](https://github.com/btravstack/unthrown/blob/
|
|
536
|
+
Defined in: [packages/core/src/tagged.ts:15](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/tagged.ts#L15)
|
|
497
537
|
|
|
498
538
|
The instance shape produced by a [TaggedError](#taggederror) class: an `Error` plus a
|
|
499
539
|
`_tag` discriminant and the (readonly) payload fields.
|
|
@@ -502,7 +542,7 @@ The instance shape produced by a [TaggedError](#taggederror) class: an `Error` p
|
|
|
502
542
|
|
|
503
543
|
| Name | Type | Defined in |
|
|
504
544
|
| ------ | ------ | ------ |
|
|
505
|
-
| `_tag` | `Tag` | [packages/core/src/tagged.ts:16](https://github.com/btravstack/unthrown/blob/
|
|
545
|
+
| `_tag` | `Tag` | [packages/core/src/tagged.ts:16](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/tagged.ts#L16) |
|
|
506
546
|
|
|
507
547
|
#### Type Parameters
|
|
508
548
|
|
|
@@ -519,7 +559,7 @@ The instance shape produced by a [TaggedError](#taggederror) class: an `Error` p
|
|
|
519
559
|
type TagHandlers<T, E, R> = object & { [K in E["_tag"]]: (error: Extract<E, { _tag: K }>) => R };
|
|
520
560
|
```
|
|
521
561
|
|
|
522
|
-
Defined in: [packages/core/src/tagged.ts:
|
|
562
|
+
Defined in: [packages/core/src/tagged.ts:103](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/tagged.ts#L103)
|
|
523
563
|
|
|
524
564
|
The handler object [matchTags](#matchtags) requires: a branch per error tag, plus
|
|
525
565
|
`Ok` and `Defect`. Miss a tag and it will not compile — the exhaustiveness is
|
|
@@ -529,8 +569,8 @@ enforced by the type, with no `.exhaustive()` to forget.
|
|
|
529
569
|
|
|
530
570
|
| Name | Type | Defined in |
|
|
531
571
|
| ------ | ------ | ------ |
|
|
532
|
-
| `Defect()` | (`cause`) => `R` | [packages/core/src/tagged.ts:
|
|
533
|
-
| `Ok()` | (`value`) => `R` | [packages/core/src/tagged.ts:
|
|
572
|
+
| `Defect()` | (`cause`) => `R` | [packages/core/src/tagged.ts:105](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/tagged.ts#L105) |
|
|
573
|
+
| `Ok()` | (`value`) => `R` | [packages/core/src/tagged.ts:104](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/tagged.ts#L104) |
|
|
534
574
|
|
|
535
575
|
#### Type Parameters
|
|
536
576
|
|
|
@@ -548,29 +588,34 @@ enforced by the type, with no `.exhaustive()` to forget.
|
|
|
548
588
|
const Result: object;
|
|
549
589
|
```
|
|
550
590
|
|
|
551
|
-
Defined in: [packages/core/src/facade.ts:
|
|
591
|
+
Defined in: [packages/core/src/facade.ts:42](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L42)
|
|
552
592
|
|
|
553
593
|
Companion object grouping the standalone entry points under a single,
|
|
554
594
|
discoverable namespace: [Result.ok](#property-ok), [Result.err](#property-err),
|
|
555
595
|
[Result.defect](#property-defect), [Result.fromNullable](#property-fromnullable), [Result.fromThrowable](#property-fromthrowable),
|
|
556
596
|
[Result.fromPromise](#property-frompromise), [Result.fromSafePromise](#property-fromsafepromise), [Result.all](#property-all),
|
|
557
|
-
[Result.
|
|
597
|
+
[Result.allAsync](#property-allasync), [Result.allFromDict](#property-allfromdict),
|
|
598
|
+
[Result.allFromDictAsync](#property-allfromdictasync), [Result.isOk](#property-isok), [Result.isErr](#property-iserr),
|
|
599
|
+
[Result.isDefect](#property-isdefect).
|
|
558
600
|
|
|
559
601
|
#### Type Declaration
|
|
560
602
|
|
|
561
603
|
| Name | Type | Defined in |
|
|
562
604
|
| ------ | ------ | ------ |
|
|
563
|
-
| <a id="property-all"></a> `all()` | <`Rs`>(`results`) => `Result`<
|
|
564
|
-
| <a id="property-
|
|
565
|
-
| <a id="property-
|
|
566
|
-
| <a id="property-
|
|
567
|
-
| <a id="property-
|
|
568
|
-
| <a id="property-
|
|
569
|
-
| <a id="property-
|
|
570
|
-
| <a id="property-
|
|
571
|
-
| <a id="property-
|
|
572
|
-
| <a id="property-
|
|
573
|
-
| <a id="property-
|
|
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:50](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L50) |
|
|
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:51](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L51) |
|
|
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:52](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L52) |
|
|
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:53](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L53) |
|
|
609
|
+
| <a id="property-defect"></a> `defect()` | (`cause`) => [`Defect`](#defect) | [packages/core/src/facade.ts:45](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L45) |
|
|
610
|
+
| <a id="property-err"></a> `err()` | <`E`>(`error`) => `Result`<`never`, `E`> | [packages/core/src/facade.ts:44](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L44) |
|
|
611
|
+
| <a id="property-fromnullable"></a> `fromNullable()` | <`T`, `E`>(`value`, `onAbsent`) => `Result`<`NonNullable`<`T`>, `E`> | [packages/core/src/facade.ts:46](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L46) |
|
|
612
|
+
| <a id="property-frompromise"></a> `fromPromise()` | <`T`, `R`>(`promise`, `qualify`) => [`AsyncResult`](#asyncresult)<`T`, `Exclude`<`R`, [`Defect`](#defect)>> | [packages/core/src/facade.ts:48](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L48) |
|
|
613
|
+
| <a id="property-fromsafepromise"></a> `fromSafePromise()` | <`T`>(`promise`) => [`AsyncResult`](#asyncresult)<`T`, `never`> | [packages/core/src/facade.ts:49](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L49) |
|
|
614
|
+
| <a id="property-fromthrowable"></a> `fromThrowable()` | <`A`, `T`, `R`>(`fn`, `qualify`) => (...`args`) => `Result`<`T`, `Exclude`<`R`, [`Defect`](#defect)>> | [packages/core/src/facade.ts:47](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L47) |
|
|
615
|
+
| <a id="property-isdefect"></a> `isDefect()` | <`T`, `E`>(`r`) => `r is DefectView<T, E>` | [packages/core/src/facade.ts:56](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L56) |
|
|
616
|
+
| <a id="property-iserr"></a> `isErr()` | <`T`, `E`>(`r`) => `r is ErrView<E, T>` | [packages/core/src/facade.ts:55](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L55) |
|
|
617
|
+
| <a id="property-isok"></a> `isOk()` | <`T`, `E`>(`r`) => `r is OkView<T, E>` | [packages/core/src/facade.ts:54](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L54) |
|
|
618
|
+
| <a id="property-ok"></a> `ok()` | <`T`>(`value`) => `Result`<`T`, `never`> | [packages/core/src/facade.ts:43](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/facade.ts#L43) |
|
|
574
619
|
|
|
575
620
|
#### Remarks
|
|
576
621
|
|
|
@@ -591,42 +636,172 @@ Result.ok(1).flatMap((n) => Result.ok(n + 1)).unwrap(); // 2
|
|
|
591
636
|
### all()
|
|
592
637
|
|
|
593
638
|
```ts
|
|
594
|
-
function all<Rs>(results): Result<{ [K in string | number | symbol]: OkOf<Rs[K]> }
|
|
639
|
+
function all<Rs>(results): Result<AllOk<Rs, { [K in string | number | symbol]: OkOf<Rs[K]> }>, ErrOf<Rs[number]>>;
|
|
595
640
|
```
|
|
596
641
|
|
|
597
|
-
Defined in: [packages/core/src/interop.ts:
|
|
642
|
+
Defined in: [packages/core/src/interop.ts:249](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/interop.ts#L249)
|
|
598
643
|
|
|
599
|
-
Collect a tuple of [Result](#result)s into a single `Result` of
|
|
644
|
+
Collect a tuple/array of [Result](#result)s into a single `Result` of all their
|
|
600
645
|
success values.
|
|
601
646
|
|
|
602
647
|
#### Type Parameters
|
|
603
648
|
|
|
604
|
-
| Type Parameter |
|
|
605
|
-
| ------ |
|
|
606
|
-
| `Rs` *extends* readonly `Result`<`unknown`, `unknown`>[] |
|
|
649
|
+
| Type Parameter |
|
|
650
|
+
| ------ |
|
|
651
|
+
| `Rs` *extends* readonly `Result`<`unknown`, `unknown`>[] |
|
|
607
652
|
|
|
608
653
|
#### Parameters
|
|
609
654
|
|
|
610
|
-
| Parameter | Type |
|
|
611
|
-
| ------ | ------ |
|
|
612
|
-
| `results` | readonly \[`Rs`\] |
|
|
655
|
+
| Parameter | Type |
|
|
656
|
+
| ------ | ------ |
|
|
657
|
+
| `results` | readonly \[`Rs`\] |
|
|
613
658
|
|
|
614
659
|
#### Returns
|
|
615
660
|
|
|
616
|
-
`Result`<
|
|
661
|
+
`Result`<`AllOk`<`Rs`, \{ \[K in string \| number \| symbol\]: OkOf\<Rs\[K\]\> \}>, [`ErrOf`](#errof)<`Rs`\[`number`\]>>
|
|
617
662
|
|
|
618
663
|
#### Remarks
|
|
619
664
|
|
|
620
665
|
Short-circuits on the **first** `Err` (later entries are not inspected for
|
|
621
666
|
their error); any `Defect` present **dominates**, winning even over an earlier
|
|
622
|
-
`Err`.
|
|
623
|
-
`Result<[number, string],
|
|
667
|
+
`Err`. A **fixed tuple** keeps its positional types — `all([ok(1), ok("a")])`
|
|
668
|
+
is `Result<[number, string], …>` — while a **dynamic array** `Result<T, E>[]`
|
|
669
|
+
collapses to `Result<T[], E>` with no cast. For a **record** keyed by name,
|
|
670
|
+
use [allFromDict](#allfromdict).
|
|
624
671
|
|
|
625
672
|
#### Example
|
|
626
673
|
|
|
627
674
|
```ts
|
|
628
675
|
import { all, ok } from "unthrown";
|
|
629
|
-
all([ok(1), ok("a"), ok(true)]).unwrap(); // [1, "a", true]
|
|
676
|
+
all([ok(1), ok("a"), ok(true)]).unwrap(); // [1, "a", true] (typed [number, string, boolean])
|
|
677
|
+
all([ok(1), ok(2)] as Result<number, never>[]).unwrap(); // number[]
|
|
678
|
+
```
|
|
679
|
+
|
|
680
|
+
***
|
|
681
|
+
|
|
682
|
+
### allAsync()
|
|
683
|
+
|
|
684
|
+
```ts
|
|
685
|
+
function allAsync<Rs>(results): AsyncResult<AllOk<Rs, { [K in string | number | symbol]: AsyncOkOf<Rs[K]> }>, AsyncErrOf<Rs[number]>>;
|
|
686
|
+
```
|
|
687
|
+
|
|
688
|
+
Defined in: [packages/core/src/interop.ts:296](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/interop.ts#L296)
|
|
689
|
+
|
|
690
|
+
The asynchronous counterpart of [all](#all): combine a tuple/array of
|
|
691
|
+
[AsyncResult](#asyncresult)s into one `AsyncResult` of all their success values.
|
|
692
|
+
|
|
693
|
+
#### Type Parameters
|
|
694
|
+
|
|
695
|
+
| Type Parameter |
|
|
696
|
+
| ------ |
|
|
697
|
+
| `Rs` *extends* readonly [`AsyncResult`](#asyncresult)<`unknown`, `unknown`>[] |
|
|
698
|
+
|
|
699
|
+
#### Parameters
|
|
700
|
+
|
|
701
|
+
| Parameter | Type |
|
|
702
|
+
| ------ | ------ |
|
|
703
|
+
| `results` | readonly \[`Rs`\] |
|
|
704
|
+
|
|
705
|
+
#### Returns
|
|
706
|
+
|
|
707
|
+
[`AsyncResult`](#asyncresult)<`AllOk`<`Rs`, \{ \[K in string \| number \| symbol\]: AsyncOkOf\<Rs\[K\]\> \}>, [`AsyncErrOf`](#asyncerrof)<`Rs`\[`number`\]>>
|
|
708
|
+
|
|
709
|
+
#### Remarks
|
|
710
|
+
|
|
711
|
+
The inputs are resolved **concurrently** (order preserved); the resolved
|
|
712
|
+
`Result`s are then folded with the same rules as [all](#all) — first `Err`
|
|
713
|
+
short-circuits, any `Defect` dominates. As ever, the returned `AsyncResult`'s
|
|
714
|
+
internal promise never rejects. For a **record**, use [allFromDictAsync](#allfromdictasync).
|
|
715
|
+
|
|
716
|
+
#### Example
|
|
717
|
+
|
|
718
|
+
```ts
|
|
719
|
+
import { allAsync, fromSafePromise } from "unthrown";
|
|
720
|
+
await allAsync([fromSafePromise(a()), fromSafePromise(b())]);
|
|
721
|
+
```
|
|
722
|
+
|
|
723
|
+
***
|
|
724
|
+
|
|
725
|
+
### allFromDict()
|
|
726
|
+
|
|
727
|
+
```ts
|
|
728
|
+
function allFromDict<R>(results): Result<{ [K in string | number | symbol]: OkOf<R[K]> }, ErrOf<R[keyof R]>>;
|
|
729
|
+
```
|
|
730
|
+
|
|
731
|
+
Defined in: [packages/core/src/interop.ts:274](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/interop.ts#L274)
|
|
732
|
+
|
|
733
|
+
Collect a **record** of [Result](#result)s into a single `Result` of a record of
|
|
734
|
+
their success values — `allFromDict({ a: Result<A, E>, b: Result<B, E> })` is
|
|
735
|
+
`Result<{ a: A; b: B }, E>`. The named counterpart of [all](#all), for
|
|
736
|
+
parallel work you'd rather not tuple.
|
|
737
|
+
|
|
738
|
+
#### Type Parameters
|
|
739
|
+
|
|
740
|
+
| Type Parameter |
|
|
741
|
+
| ------ |
|
|
742
|
+
| `R` *extends* `ResultRecord` |
|
|
743
|
+
|
|
744
|
+
#### Parameters
|
|
745
|
+
|
|
746
|
+
| Parameter | Type |
|
|
747
|
+
| ------ | ------ |
|
|
748
|
+
| `results` | `R` |
|
|
749
|
+
|
|
750
|
+
#### Returns
|
|
751
|
+
|
|
752
|
+
`Result`<\{ \[K in string \| number \| symbol\]: OkOf\<R\[K\]\> \}, [`ErrOf`](#errof)<`R`\[keyof `R`\]>>
|
|
753
|
+
|
|
754
|
+
#### Remarks
|
|
755
|
+
|
|
756
|
+
Same folding rules as [all](#all): first `Err` short-circuits, any `Defect`
|
|
757
|
+
dominates. This is **not** error accumulation.
|
|
758
|
+
|
|
759
|
+
#### Example
|
|
760
|
+
|
|
761
|
+
```ts
|
|
762
|
+
import { allFromDict, ok } from "unthrown";
|
|
763
|
+
allFromDict({ id: ok(1), name: ok("ada") }).unwrap(); // { id: 1, name: "ada" }
|
|
764
|
+
```
|
|
765
|
+
|
|
766
|
+
***
|
|
767
|
+
|
|
768
|
+
### allFromDictAsync()
|
|
769
|
+
|
|
770
|
+
```ts
|
|
771
|
+
function allFromDictAsync<R>(results): AsyncResult<{ [K in string | number | symbol]: AsyncOkOf<R[K]> }, AsyncErrOf<R[keyof R]>>;
|
|
772
|
+
```
|
|
773
|
+
|
|
774
|
+
Defined in: [packages/core/src/interop.ts:324](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/interop.ts#L324)
|
|
775
|
+
|
|
776
|
+
The asynchronous counterpart of [allFromDict](#allfromdict): combine a record of
|
|
777
|
+
[AsyncResult](#asyncresult)s into one `AsyncResult` of a record of their values.
|
|
778
|
+
|
|
779
|
+
#### Type Parameters
|
|
780
|
+
|
|
781
|
+
| Type Parameter |
|
|
782
|
+
| ------ |
|
|
783
|
+
| `R` *extends* `AsyncResultRecord` |
|
|
784
|
+
|
|
785
|
+
#### Parameters
|
|
786
|
+
|
|
787
|
+
| Parameter | Type |
|
|
788
|
+
| ------ | ------ |
|
|
789
|
+
| `results` | `R` |
|
|
790
|
+
|
|
791
|
+
#### Returns
|
|
792
|
+
|
|
793
|
+
[`AsyncResult`](#asyncresult)<\{ \[K in string \| number \| symbol\]: AsyncOkOf\<R\[K\]\> \}, [`AsyncErrOf`](#asyncerrof)<`R`\[keyof `R`\]>>
|
|
794
|
+
|
|
795
|
+
#### Remarks
|
|
796
|
+
|
|
797
|
+
Resolved concurrently (order preserved), folded with the [all](#all) rules,
|
|
798
|
+
and the internal promise never rejects.
|
|
799
|
+
|
|
800
|
+
#### Example
|
|
801
|
+
|
|
802
|
+
```ts
|
|
803
|
+
import { allFromDictAsync, fromSafePromise } from "unthrown";
|
|
804
|
+
await allFromDictAsync({ a: fromSafePromise(a()), b: fromSafePromise(b()) });
|
|
630
805
|
```
|
|
631
806
|
|
|
632
807
|
***
|
|
@@ -637,7 +812,7 @@ all([ok(1), ok("a"), ok(true)]).unwrap(); // [1, "a", true]
|
|
|
637
812
|
function defect(cause): Defect;
|
|
638
813
|
```
|
|
639
814
|
|
|
640
|
-
Defined in: [packages/core/src/defect.ts:36](https://github.com/btravstack/unthrown/blob/
|
|
815
|
+
Defined in: [packages/core/src/defect.ts:36](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/defect.ts#L36)
|
|
641
816
|
|
|
642
817
|
Wrap a cause as a [Defect](#defect) — the value you return from a `qualify`
|
|
643
818
|
function when a failure is **not** a modeled domain error.
|
|
@@ -672,7 +847,7 @@ const user = fromPromise(fetchUser(id), (cause) =>
|
|
|
672
847
|
function err<E>(error): Result<never, E>;
|
|
673
848
|
```
|
|
674
849
|
|
|
675
|
-
Defined in: [packages/core/src/constructors.ts:34](https://github.com/btravstack/unthrown/blob/
|
|
850
|
+
Defined in: [packages/core/src/constructors.ts:34](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/constructors.ts#L34)
|
|
676
851
|
|
|
677
852
|
Construct a failed [Result](#result) carrying a **modeled** error.
|
|
678
853
|
|
|
@@ -707,7 +882,7 @@ err("not_found").unwrapErr(); // "not_found"
|
|
|
707
882
|
function fromNullable<T, E>(value, onAbsent): Result<NonNullable<T>, E>;
|
|
708
883
|
```
|
|
709
884
|
|
|
710
|
-
Defined in: [packages/core/src/interop.ts:29](https://github.com/btravstack/unthrown/blob/
|
|
885
|
+
Defined in: [packages/core/src/interop.ts:29](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/interop.ts#L29)
|
|
711
886
|
|
|
712
887
|
Bridge a nullable value into a [Result](#result): absence becomes a **modeled**
|
|
713
888
|
`Err`. The sanctioned alternative to an `Option` type.
|
|
@@ -747,10 +922,10 @@ fromNullable(map.get(key), () => "missing").unwrap();
|
|
|
747
922
|
### fromPromise()
|
|
748
923
|
|
|
749
924
|
```ts
|
|
750
|
-
function fromPromise<T,
|
|
925
|
+
function fromPromise<T, R>(promise, qualify): AsyncResult<T, Exclude<R, Defect>>;
|
|
751
926
|
```
|
|
752
927
|
|
|
753
|
-
Defined in: [packages/core/src/interop.ts:
|
|
928
|
+
Defined in: [packages/core/src/interop.ts:110](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/interop.ts#L110)
|
|
754
929
|
|
|
755
930
|
Wrap a `Promise` (or a thunk producing one) as an [AsyncResult](#asyncresult), forcing
|
|
756
931
|
every rejection to be triaged.
|
|
@@ -760,18 +935,18 @@ every rejection to be triaged.
|
|
|
760
935
|
| Type Parameter | Description |
|
|
761
936
|
| ------ | ------ |
|
|
762
937
|
| `T` | the resolved value type. |
|
|
763
|
-
| `
|
|
938
|
+
| `R` | `qualify`'s return type; the modeled error `E` is `Exclude<R, Defect>` (its `Defect` arm, if any, is subtracted). |
|
|
764
939
|
|
|
765
940
|
#### Parameters
|
|
766
941
|
|
|
767
942
|
| Parameter | Type | Description |
|
|
768
943
|
| ------ | ------ | ------ |
|
|
769
944
|
| `promise` | `Promise`<`T`> \| (() => `Promise`<`T`>) | the promise, or a thunk returning one. |
|
|
770
|
-
| `qualify` | (`cause`) =>
|
|
945
|
+
| `qualify` | (`cause`) => `R` | triages a rejection cause into `E` or a `Defect`. |
|
|
771
946
|
|
|
772
947
|
#### Returns
|
|
773
948
|
|
|
774
|
-
[`AsyncResult`](#asyncresult)<`T`, `
|
|
949
|
+
[`AsyncResult`](#asyncresult)<`T`, `Exclude`<`R`, [`Defect`](#defect)>>
|
|
775
950
|
|
|
776
951
|
#### Remarks
|
|
777
952
|
|
|
@@ -780,6 +955,11 @@ every rejection to be triaged.
|
|
|
780
955
|
`await`-ing it always yields a `Result`. A throw inside `qualify` is itself a
|
|
781
956
|
`Defect`.
|
|
782
957
|
|
|
958
|
+
The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
|
|
959
|
+
`qualify`'s return is **subtracted** from `E`, never inferred into it. So a
|
|
960
|
+
`qualify` that returns *only* `defect(cause)` yields `E = never`; when every
|
|
961
|
+
rejection is a defect, prefer [fromSafePromise](#fromsafepromise).
|
|
962
|
+
|
|
783
963
|
#### Example
|
|
784
964
|
|
|
785
965
|
```ts
|
|
@@ -797,7 +977,7 @@ const user = await fromPromise(fetchUser(id), (cause) =>
|
|
|
797
977
|
function fromSafePromise<T>(promise): AsyncResult<T, never>;
|
|
798
978
|
```
|
|
799
979
|
|
|
800
|
-
Defined in: [packages/core/src/interop.ts:
|
|
980
|
+
Defined in: [packages/core/src/interop.ts:136](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/interop.ts#L136)
|
|
801
981
|
|
|
802
982
|
Wrap a `Promise` asserted **not** to fail in any modeled way: any rejection
|
|
803
983
|
becomes a `Defect`.
|
|
@@ -829,10 +1009,10 @@ triage. (`await`-ing still yields a `Result`; it never throws.)
|
|
|
829
1009
|
### fromThrowable()
|
|
830
1010
|
|
|
831
1011
|
```ts
|
|
832
|
-
function fromThrowable<A, T,
|
|
1012
|
+
function fromThrowable<A, T, R>(fn, qualify): (...args) => Result<T, Exclude<R, Defect>>;
|
|
833
1013
|
```
|
|
834
1014
|
|
|
835
|
-
Defined in: [packages/core/src/interop.ts:
|
|
1015
|
+
Defined in: [packages/core/src/interop.ts:66](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/interop.ts#L66)
|
|
836
1016
|
|
|
837
1017
|
Wrap a throwing synchronous function so it returns a [Result](#result) instead of
|
|
838
1018
|
throwing.
|
|
@@ -843,20 +1023,20 @@ throwing.
|
|
|
843
1023
|
| ------ | ------ |
|
|
844
1024
|
| `A` *extends* `unknown`[] | the wrapped function's argument tuple. |
|
|
845
1025
|
| `T` | the wrapped function's return type. |
|
|
846
|
-
| `
|
|
1026
|
+
| `R` | `qualify`'s return type; the modeled error `E` is `Exclude<R, Defect>` (its `Defect` arm, if any, is subtracted). |
|
|
847
1027
|
|
|
848
1028
|
#### Parameters
|
|
849
1029
|
|
|
850
1030
|
| Parameter | Type | Description |
|
|
851
1031
|
| ------ | ------ | ------ |
|
|
852
1032
|
| `fn` | (...`args`) => `T` | the throwing function to wrap. |
|
|
853
|
-
| `qualify` | (`cause`) =>
|
|
1033
|
+
| `qualify` | (`cause`) => `R` | triages a thrown cause into `E` or a `Defect`. |
|
|
854
1034
|
|
|
855
1035
|
#### Returns
|
|
856
1036
|
|
|
857
1037
|
a function with the same arguments returning `Result<T, E>`.
|
|
858
1038
|
|
|
859
|
-
(...`args`) => `Result`<`T`, `
|
|
1039
|
+
(...`args`) => `Result`<`T`, `Exclude`<`R`, [`Defect`](#defect)>>
|
|
860
1040
|
|
|
861
1041
|
#### Remarks
|
|
862
1042
|
|
|
@@ -864,6 +1044,12 @@ a function with the same arguments returning `Result<T, E>`.
|
|
|
864
1044
|
[Defect](#defect) (via [defect](#defect-2)) — there is no path that leaves `unknown`
|
|
865
1045
|
in `E`. A throw inside `qualify` itself is treated as a `Defect`.
|
|
866
1046
|
|
|
1047
|
+
The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
|
|
1048
|
+
`qualify`'s return is **subtracted** from `E`, never inferred into it. So a
|
|
1049
|
+
`qualify` that returns *only* `defect(cause)` yields `E = never` (a defect is
|
|
1050
|
+
out-of-band and must not pollute the error channel); reach for
|
|
1051
|
+
[fromSafePromise](#fromsafepromise) when every failure is a defect.
|
|
1052
|
+
|
|
867
1053
|
#### Example
|
|
868
1054
|
|
|
869
1055
|
```ts
|
|
@@ -880,7 +1066,7 @@ parse("{}").unwrap();
|
|
|
880
1066
|
function isDefect<T, E>(r): r is DefectView<T, E>;
|
|
881
1067
|
```
|
|
882
1068
|
|
|
883
|
-
Defined in: [packages/core/src/constructors.ts:66](https://github.com/btravstack/unthrown/blob/
|
|
1069
|
+
Defined in: [packages/core/src/constructors.ts:66](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/constructors.ts#L66)
|
|
884
1070
|
|
|
885
1071
|
Type guard: narrow a [Result](#result) to its `Defect` variant, exposing `.cause`.
|
|
886
1072
|
|
|
@@ -911,7 +1097,7 @@ Type guard: narrow a [Result](#result) to its `Defect` variant, exposing `.cause
|
|
|
911
1097
|
function isErr<T, E>(r): r is ErrView<E, T>;
|
|
912
1098
|
```
|
|
913
1099
|
|
|
914
|
-
Defined in: [packages/core/src/constructors.ts:58](https://github.com/btravstack/unthrown/blob/
|
|
1100
|
+
Defined in: [packages/core/src/constructors.ts:58](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/constructors.ts#L58)
|
|
915
1101
|
|
|
916
1102
|
Type guard: narrow a [Result](#result) to its `Err` variant, exposing `.error`.
|
|
917
1103
|
|
|
@@ -942,7 +1128,7 @@ Type guard: narrow a [Result](#result) to its `Err` variant, exposing `.error`.
|
|
|
942
1128
|
function isOk<T, E>(r): r is OkView<T, E>;
|
|
943
1129
|
```
|
|
944
1130
|
|
|
945
|
-
Defined in: [packages/core/src/constructors.ts:50](https://github.com/btravstack/unthrown/blob/
|
|
1131
|
+
Defined in: [packages/core/src/constructors.ts:50](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/constructors.ts#L50)
|
|
946
1132
|
|
|
947
1133
|
Type guard: narrow a [Result](#result) to its `Ok` variant, exposing `.value`.
|
|
948
1134
|
|
|
@@ -983,7 +1169,7 @@ if (isOk(r)) r.value; // number, narrowed
|
|
|
983
1169
|
function matchTags<T, E, R>(result, handlers): R;
|
|
984
1170
|
```
|
|
985
1171
|
|
|
986
|
-
Defined in: [packages/core/src/tagged.ts:
|
|
1172
|
+
Defined in: [packages/core/src/tagged.ts:138](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/tagged.ts#L138)
|
|
987
1173
|
|
|
988
1174
|
Exhaustively fold a [Result](#result) (or [AsyncResult](#asyncresult)) whose error type is
|
|
989
1175
|
a tagged union, dispatching each error to the handler matching its `_tag`.
|
|
@@ -1035,7 +1221,7 @@ matchTags(r, {
|
|
|
1035
1221
|
function matchTags<T, E, R>(result, handlers): Promise<R>;
|
|
1036
1222
|
```
|
|
1037
1223
|
|
|
1038
|
-
Defined in: [packages/core/src/tagged.ts:
|
|
1224
|
+
Defined in: [packages/core/src/tagged.ts:142](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/tagged.ts#L142)
|
|
1039
1225
|
|
|
1040
1226
|
Exhaustively fold a [Result](#result) (or [AsyncResult](#asyncresult)) whose error type is
|
|
1041
1227
|
a tagged union, dispatching each error to the handler matching its `_tag`.
|
|
@@ -1089,7 +1275,7 @@ matchTags(r, {
|
|
|
1089
1275
|
function ok<T>(value): Result<T, never>;
|
|
1090
1276
|
```
|
|
1091
1277
|
|
|
1092
|
-
Defined in: [packages/core/src/constructors.ts:18](https://github.com/btravstack/unthrown/blob/
|
|
1278
|
+
Defined in: [packages/core/src/constructors.ts:18](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/constructors.ts#L18)
|
|
1093
1279
|
|
|
1094
1280
|
Construct a successful [Result](#result).
|
|
1095
1281
|
|
|
@@ -1121,10 +1307,10 @@ ok(42).unwrap(); // 42
|
|
|
1121
1307
|
### TaggedError()
|
|
1122
1308
|
|
|
1123
1309
|
```ts
|
|
1124
|
-
function TaggedError<Tag>(tag): TaggedErrorConstructor<Tag>;
|
|
1310
|
+
function TaggedError<Tag>(tag, options?): TaggedErrorConstructor<Tag>;
|
|
1125
1311
|
```
|
|
1126
1312
|
|
|
1127
|
-
Defined in: [packages/core/src/tagged.ts:
|
|
1313
|
+
Defined in: [packages/core/src/tagged.ts:72](https://github.com/btravstack/unthrown/blob/1e34025e0177665dde9c50faca313fd1b95e5545/packages/core/src/tagged.ts#L72)
|
|
1128
1314
|
|
|
1129
1315
|
Build a base class for a tagged error — a class extending `Error` with a
|
|
1130
1316
|
`_tag` string discriminant, in the style of Effect's `Data.TaggedError`.
|
|
@@ -1139,7 +1325,9 @@ Build a base class for a tagged error — a class extending `Error` with a
|
|
|
1139
1325
|
|
|
1140
1326
|
| Parameter | Type | Description |
|
|
1141
1327
|
| ------ | ------ | ------ |
|
|
1142
|
-
| `tag` | `Tag` | the discriminant value
|
|
1328
|
+
| `tag` | `Tag` | the discriminant value; also the default error `name`. |
|
|
1329
|
+
| `options?` | \{ `name?`: `string`; \} | optional overrides. `options.name` sets `Error.name` independently of `tag` (defaults to `tag`). |
|
|
1330
|
+
| `options.name?` | `string` | - |
|
|
1143
1331
|
|
|
1144
1332
|
#### Returns
|
|
1145
1333
|
|
|
@@ -1152,6 +1340,22 @@ an instantiation expression; omit it for a payload-less error. A `message`
|
|
|
1152
1340
|
field in the payload is forwarded to `Error`. The `_tag` always reflects
|
|
1153
1341
|
`tag` and cannot be overridden by the payload.
|
|
1154
1342
|
|
|
1343
|
+
`_tag` is the discriminant used by [matchTags](#matchtags); `Error.name` is the
|
|
1344
|
+
human-facing label in stack traces and logs. By default they coincide, but
|
|
1345
|
+
they can be **decoupled** with `options.name` — so a tag can be namespaced for
|
|
1346
|
+
collision-safety (`"@my-lib/RetryableError"`) without that slash-prefixed
|
|
1347
|
+
string leaking into `Error.name`:
|
|
1348
|
+
|
|
1349
|
+
```ts
|
|
1350
|
+
class RetryableError extends TaggedError("@my-lib/RetryableError", {
|
|
1351
|
+
name: "RetryableError",
|
|
1352
|
+
})<{ message: string }> {}
|
|
1353
|
+
|
|
1354
|
+
const e = new RetryableError({ message: "boom" });
|
|
1355
|
+
e._tag; // "@my-lib/RetryableError" — namespaced discriminant
|
|
1356
|
+
e.name; // "RetryableError" — clean display name
|
|
1357
|
+
```
|
|
1358
|
+
|
|
1155
1359
|
#### Example
|
|
1156
1360
|
|
|
1157
1361
|
```ts
|