unthrown 2.0.0 → 3.0.1

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.
Files changed (10) hide show
  1. package/README.md +3 -3
  2. package/dist/index.cjs +65 -67
  3. package/dist/index.d.cts +52 -59
  4. package/dist/index.d.cts.map +1 -1
  5. package/dist/index.d.mts +52 -59
  6. package/dist/index.d.mts.map +1 -1
  7. package/dist/index.mjs +66 -67
  8. package/dist/index.mjs.map +1 -1
  9. package/docs/index.md +93 -152
  10. 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:30](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/core.ts#L30)
11
+ Defined in: [packages/core/src/core.ts:35](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/core.ts#L35)
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
@@ -16,6 +16,11 @@ wrong on a *modeled* result — `unwrap()` on an `Err`, or `unwrapErr()` on an
16
16
 
17
17
  #### Remarks
18
18
 
19
+ The offending value is exposed two ways: the typed [UnwrapError.error](#error)
20
+ property for programmatic access, and the standard `Error.cause` for the
21
+ runtime and devtools to chain — when `E` is an `Error` (e.g. a `TaggedError`)
22
+ its original stack is printed under "caused by".
23
+
19
24
  A `Defect` is never wrapped in an `UnwrapError`: its original cause is
20
25
  re-thrown (with its original stack) instead.
21
26
 
@@ -37,7 +42,7 @@ re-thrown (with its original stack) instead.
37
42
  new UnwrapError<E>(error): UnwrapError<E>;
38
43
  ```
39
44
 
40
- Defined in: [packages/core/src/core.ts:36](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/core.ts#L36)
45
+ Defined in: [packages/core/src/core.ts:41](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/core.ts#L41)
41
46
 
42
47
  ###### Parameters
43
48
 
@@ -60,7 +65,7 @@ Error.constructor
60
65
  | Property | Modifier | Type | Description | Inherited from | Defined in |
61
66
  | ------ | ------ | ------ | ------ | ------ | ------ |
62
67
  | <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:35](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/core.ts#L35) |
68
+ | <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:40](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/core.ts#L40) |
64
69
  | <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
70
  | <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
71
  | <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 +179,7 @@ Error.prepareStackTrace
174
179
  type AsyncErrOf<R> = R extends AsyncResult<unknown, infer E> ? E : never;
175
180
  ```
176
181
 
177
- Defined in: [packages/core/src/types.ts:468](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L468)
182
+ Defined in: [packages/core/src/types.ts:468](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L468)
178
183
 
179
184
  Extract the error type `E` from an [AsyncResult](#asyncresult).
180
185
 
@@ -192,7 +197,7 @@ Extract the error type `E` from an [AsyncResult](#asyncresult).
192
197
  type AsyncOkOf<R> = R extends AsyncResult<infer T, unknown> ? T : never;
193
198
  ```
194
199
 
195
- Defined in: [packages/core/src/types.ts:462](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L462)
200
+ Defined in: [packages/core/src/types.ts:462](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L462)
196
201
 
197
202
  Extract the success type `T` from an [AsyncResult](#asyncresult).
198
203
 
@@ -210,7 +215,7 @@ Extract the success type `T` from an [AsyncResult](#asyncresult).
210
215
  type AsyncResult<T, E> = AsyncResultType<T, E>;
211
216
  ```
212
217
 
213
- Defined in: [packages/core/src/facade.ts:88](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L88)
218
+ Defined in: [packages/core/src/facade.ts:85](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L85)
214
219
 
215
220
  Companion object grouping the **`AsyncResult`-producing** entry points under
216
221
  the matching namespace: [AsyncResult.fromPromise](#property-frompromise),
@@ -237,8 +242,8 @@ value `AsyncResult` and the type [AsyncResult](#asyncresult-1) share one name.
237
242
  #### Example
238
243
 
239
244
  ```ts
240
- import { AsyncResult, Defect } from "unthrown";
241
- const user = await AsyncResult.fromPromise(fetchUser(id), (c) => Defect(c));
245
+ import { AsyncResult } from "unthrown";
246
+ const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
242
247
  ```
243
248
 
244
249
  ***
@@ -249,7 +254,7 @@ const user = await AsyncResult.fromPromise(fetchUser(id), (c) => Defect(c));
249
254
  type Awaitable<T> = object;
250
255
  ```
251
256
 
252
- Defined in: [packages/core/src/types.ts:346](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L346)
257
+ Defined in: [packages/core/src/types.ts:346](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L346)
253
258
 
254
259
  A success-only thenable: awaitable, but deliberately **not** a full
255
260
  `PromiseLike`.
@@ -276,7 +281,7 @@ being treated as a raw promise (e.g. dropped into `Promise.all`).
276
281
  then<R>(onfulfilled?): PromiseLike<R>;
277
282
  ```
278
283
 
279
- Defined in: [packages/core/src/types.ts:347](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L347)
284
+ Defined in: [packages/core/src/types.ts:347](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L347)
280
285
 
281
286
  ###### Type Parameters
282
287
 
@@ -296,40 +301,13 @@ Defined in: [packages/core/src/types.ts:347](https://github.com/btravstack/unthr
296
301
 
297
302
  ***
298
303
 
299
- ### Defect
300
-
301
- ```ts
302
- type Defect = object;
303
- ```
304
-
305
- Defined in: [packages/core/src/defect.ts:36](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/defect.ts#L36)
306
-
307
- The marker a `qualify` function returns to triage a cause as **unexpected**.
308
-
309
- #### Remarks
310
-
311
- `qualify` (passed to [fromPromise](#frompromise) / [fromThrowable](#fromthrowable)) returns
312
- `E | Defect`: either a modeled domain error, or a `Defect` produced by
313
- [Defect](#defect-2) to say "this failure is not modeled". A `Defect` is opaque —
314
- it carries the original cause for the boundary to convert into the third
315
- runtime state of a `Result`.
316
-
317
- #### Properties
318
-
319
- | Property | Modifier | Type | Defined in |
320
- | ------ | ------ | ------ | ------ |
321
- | <a id="defect-1"></a> `[DEFECT]` | `readonly` | `true` | [packages/core/src/defect.ts:16](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/defect.ts#L16) |
322
- | <a id="cause-1"></a> `cause` | `readonly` | `unknown` | [packages/core/src/defect.ts:17](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/defect.ts#L17) |
323
-
324
- ***
325
-
326
304
  ### DefectView
327
305
 
328
306
  ```ts
329
307
  type DefectView<T, E> = ResultMethods<T, E> & object;
330
308
  ```
331
309
 
332
- Defined in: [packages/core/src/types.ts:289](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L289)
310
+ Defined in: [packages/core/src/types.ts:289](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L289)
333
311
 
334
312
  The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `cause`.
335
313
 
@@ -337,8 +315,8 @@ The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `ca
337
315
 
338
316
  | Name | Type | Defined in |
339
317
  | ------ | ------ | ------ |
340
- | `cause` | `unknown` | [packages/core/src/types.ts:291](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L291) |
341
- | `tag` | `"Defect"` | [packages/core/src/types.ts:290](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L290) |
318
+ | `cause` | `unknown` | [packages/core/src/types.ts:291](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L291) |
319
+ | `tag` | `"Defect"` | [packages/core/src/types.ts:290](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L290) |
342
320
 
343
321
  #### Type Parameters
344
322
 
@@ -355,7 +333,7 @@ The `Defect` variant of a [Result](#result): an unmodeled failure carrying a `ca
355
333
  type ErrOf<R> = R extends object ? E : never;
356
334
  ```
357
335
 
358
- Defined in: [packages/core/src/types.ts:456](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L456)
336
+ Defined in: [packages/core/src/types.ts:456](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L456)
359
337
 
360
338
  Extract the error type `E` from a `Result`.
361
339
 
@@ -373,7 +351,7 @@ Extract the error type `E` from a `Result`.
373
351
  type ErrView<E, T> = ResultMethods<T, E> & object;
374
352
  ```
375
353
 
376
- Defined in: [packages/core/src/types.ts:284](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L284)
354
+ Defined in: [packages/core/src/types.ts:284](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L284)
377
355
 
378
356
  The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
379
357
 
@@ -381,8 +359,8 @@ The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
381
359
 
382
360
  | Name | Type | Defined in |
383
361
  | ------ | ------ | ------ |
384
- | `error` | `E` | [packages/core/src/types.ts:286](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L286) |
385
- | `tag` | `"Err"` | [packages/core/src/types.ts:285](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L285) |
362
+ | `error` | `E` | [packages/core/src/types.ts:286](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L286) |
363
+ | `tag` | `"Err"` | [packages/core/src/types.ts:285](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L285) |
386
364
 
387
365
  #### Type Parameters
388
366
 
@@ -399,7 +377,7 @@ The `Err` variant of a [Result](#result): a modeled failure carrying an `error`.
399
377
  type OkOf<R> = R extends object ? T : never;
400
378
  ```
401
379
 
402
- Defined in: [packages/core/src/types.ts:450](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L450)
380
+ Defined in: [packages/core/src/types.ts:450](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L450)
403
381
 
404
382
  Extract the success type `T` from a `Result`.
405
383
 
@@ -417,7 +395,7 @@ Extract the success type `T` from a `Result`.
417
395
  type OkView<T, E> = ResultMethods<T, E> & object;
418
396
  ```
419
397
 
420
- Defined in: [packages/core/src/types.ts:279](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L279)
398
+ Defined in: [packages/core/src/types.ts:279](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L279)
421
399
 
422
400
  The `Ok` variant of a [Result](#result): a success carrying a `value`.
423
401
 
@@ -425,8 +403,8 @@ The `Ok` variant of a [Result](#result): a success carrying a `value`.
425
403
 
426
404
  | Name | Type | Defined in |
427
405
  | ------ | ------ | ------ |
428
- | `tag` | `"Ok"` | [packages/core/src/types.ts:280](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L280) |
429
- | `value` | `T` | [packages/core/src/types.ts:281](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/types.ts#L281) |
406
+ | `tag` | `"Ok"` | [packages/core/src/types.ts:280](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L280) |
407
+ | `value` | `T` | [packages/core/src/types.ts:281](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/types.ts#L281) |
430
408
 
431
409
  #### Type Parameters
432
410
 
@@ -443,14 +421,13 @@ The `Ok` variant of a [Result](#result): a success carrying a `value`.
443
421
  type Result<T, E> = ResultType<T, E>;
444
422
  ```
445
423
 
446
- Defined in: [packages/core/src/facade.ts:47](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L47)
424
+ Defined in: [packages/core/src/facade.ts:45](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L45)
447
425
 
448
426
  Companion object grouping the **`Result`-producing** entry points under a
449
427
  single, discoverable namespace: [Result.Ok](#property-ok), [Result.Err](#property-err),
450
- [Result.Defect](#property-defect), [Result.Do](#property-do), [Result.fromNullable](#property-fromnullable),
451
- [Result.fromThrowable](#property-fromthrowable), [Result.all](#property-all-1), [Result.allFromDict](#property-allfromdict-1),
452
- [Result.isOk](#property-isok), [Result.isErr](#property-iserr), [Result.isDefect](#property-isdefect),
453
- [Result.isResult](#property-isresult).
428
+ [Result.Do](#property-do), [Result.fromNullable](#property-fromnullable), [Result.fromThrowable](#property-fromthrowable),
429
+ [Result.all](#property-all-1), [Result.allFromDict](#property-allfromdict-1), [Result.isOk](#property-isok),
430
+ [Result.isErr](#property-iserr), [Result.isDefect](#property-isdefect), [Result.isResult](#property-isresult).
454
431
 
455
432
  #### Type Parameters
456
433
 
@@ -485,7 +462,7 @@ Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // 2
485
462
  type TaggedErrorConstructor<Tag> = <A>(args) => TaggedErrorInstance<Tag, A>;
486
463
  ```
487
464
 
488
- Defined in: [packages/core/src/tagged.ts:28](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/tagged.ts#L28)
465
+ Defined in: [packages/core/src/tagged.ts:28](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/tagged.ts#L28)
489
466
 
490
467
  The class constructor returned by [TaggedError](#taggederror). Generic in its payload:
491
468
  apply it with an instantiation expression at the `extends` site.
@@ -519,7 +496,7 @@ When the payload is empty, the constructor takes **no** arguments (the
519
496
  type TaggedErrorInstance<Tag, A> = Error & Readonly<A> & object;
520
497
  ```
521
498
 
522
- Defined in: [packages/core/src/tagged.ts:15](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/tagged.ts#L15)
499
+ Defined in: [packages/core/src/tagged.ts:15](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/tagged.ts#L15)
523
500
 
524
501
  The instance shape produced by a [TaggedError](#taggederror) class: an `Error` plus a
525
502
  `_tag` discriminant and the (readonly) payload fields.
@@ -528,7 +505,7 @@ The instance shape produced by a [TaggedError](#taggederror) class: an `Error` p
528
505
 
529
506
  | Name | Type | Defined in |
530
507
  | ------ | ------ | ------ |
531
- | `_tag` | `Tag` | [packages/core/src/tagged.ts:16](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/tagged.ts#L16) |
508
+ | `_tag` | `Tag` | [packages/core/src/tagged.ts:16](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/tagged.ts#L16) |
532
509
 
533
510
  #### Type Parameters
534
511
 
@@ -545,7 +522,7 @@ The instance shape produced by a [TaggedError](#taggederror) class: an `Error` p
545
522
  type TagHandlers<T, E, R> = object & { [K in E["_tag"]]: (error: Extract<E, { _tag: K }>) => R };
546
523
  ```
547
524
 
548
- Defined in: [packages/core/src/tagged.ts:103](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/tagged.ts#L103)
525
+ Defined in: [packages/core/src/tagged.ts:103](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/tagged.ts#L103)
549
526
 
550
527
  The handler object [matchTags](#matchtags) requires: a branch per error tag, plus
551
528
  `Ok` and `Defect`. Miss a tag and it will not compile — the exhaustiveness is
@@ -555,8 +532,8 @@ enforced by the type, with no `.exhaustive()` to forget.
555
532
 
556
533
  | Name | Type | Defined in |
557
534
  | ------ | ------ | ------ |
558
- | `Defect()` | (`cause`) => `R` | [packages/core/src/tagged.ts:105](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/tagged.ts#L105) |
559
- | `Ok()` | (`value`) => `R` | [packages/core/src/tagged.ts:104](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/tagged.ts#L104) |
535
+ | `Defect()` | (`cause`) => `R` | [packages/core/src/tagged.ts:105](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/tagged.ts#L105) |
536
+ | `Ok()` | (`value`) => `R` | [packages/core/src/tagged.ts:104](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/tagged.ts#L104) |
560
537
 
561
538
  #### Type Parameters
562
539
 
@@ -574,7 +551,7 @@ enforced by the type, with no `.exhaustive()` to forget.
574
551
  const AsyncResult: object;
575
552
  ```
576
553
 
577
- Defined in: [packages/core/src/facade.ts:88](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L88)
554
+ Defined in: [packages/core/src/facade.ts:85](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L85)
578
555
 
579
556
  Companion object grouping the **`AsyncResult`-producing** entry points under
580
557
  the matching namespace: [AsyncResult.fromPromise](#property-frompromise),
@@ -585,10 +562,10 @@ the matching namespace: [AsyncResult.fromPromise](#property-frompromise),
585
562
 
586
563
  | Name | Type | Default value | Defined in |
587
564
  | ------ | ------ | ------ | ------ |
588
- | <a id="property-all"></a> `all()` | &lt;`Rs`&gt;(`results`) => `AsyncResult`&lt;`AllOk`&lt;`Rs`, \{ \[K in string \| number \| symbol\]: AsyncOkOf\<Rs\[K\]\> \}&gt;, [`AsyncErrOf`](#asyncerrof)&lt;`Rs`\[`number`\]&gt;&gt; | `allAsync` | [packages/core/src/facade.ts:91](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L91) |
589
- | <a id="property-allfromdict"></a> `allFromDict()` | &lt;`R`&gt;(`results`) => `AsyncResult`&lt;\{ \[K in string \| number \| symbol\]: AsyncOkOf\<R\[K\]\> \}, [`AsyncErrOf`](#asyncerrof)&lt;`R`\[keyof `R`\]&gt;&gt; | `allFromDictAsync` | [packages/core/src/facade.ts:92](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L92) |
590
- | <a id="property-frompromise"></a> `fromPromise()` | &lt;`T`, `R`&gt;(`promise`, `qualify`) => `AsyncResult`&lt;`T`, `Exclude`&lt;`R`, [`Defect`](#defect)&gt;&gt; | - | [packages/core/src/facade.ts:89](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L89) |
591
- | <a id="property-fromsafepromise"></a> `fromSafePromise()` | &lt;`T`&gt;(`promise`) => `AsyncResult`&lt;`T`, `never`&gt; | - | [packages/core/src/facade.ts:90](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L90) |
565
+ | <a id="property-all"></a> `all()` | &lt;`Rs`&gt;(`results`) => `AsyncResult`&lt;`AllOk`&lt;`Rs`, \{ \[K in string \| number \| symbol\]: AsyncOkOf\<Rs\[K\]\> \}&gt;, [`AsyncErrOf`](#asyncerrof)&lt;`Rs`\[`number`\]&gt;&gt; | `allAsync` | [packages/core/src/facade.ts:88](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L88) |
566
+ | <a id="property-allfromdict"></a> `allFromDict()` | &lt;`R`&gt;(`results`) => `AsyncResult`&lt;\{ \[K in string \| number \| symbol\]: AsyncOkOf\<R\[K\]\> \}, [`AsyncErrOf`](#asyncerrof)&lt;`R`\[keyof `R`\]&gt;&gt; | `allFromDictAsync` | [packages/core/src/facade.ts:89](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L89) |
567
+ | <a id="property-frompromise"></a> `fromPromise()` | &lt;`T`, `R`&gt;(`promise`, `qualify`) => `AsyncResult`&lt;`T`, `Exclude`&lt;`R`, `Defect`&gt;&gt; | - | [packages/core/src/facade.ts:86](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L86) |
568
+ | <a id="property-fromsafepromise"></a> `fromSafePromise()` | &lt;`T`&gt;(`promise`) => `AsyncResult`&lt;`T`, `never`&gt; | - | [packages/core/src/facade.ts:87](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L87) |
592
569
 
593
570
  #### Remarks
594
571
 
@@ -603,8 +580,8 @@ value `AsyncResult` and the type [AsyncResult](#asyncresult-1) share one name.
603
580
  #### Example
604
581
 
605
582
  ```ts
606
- import { AsyncResult, Defect } from "unthrown";
607
- const user = await AsyncResult.fromPromise(fetchUser(id), (c) => Defect(c));
583
+ import { AsyncResult } from "unthrown";
584
+ const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
608
585
  ```
609
586
 
610
587
  ***
@@ -615,31 +592,29 @@ const user = await AsyncResult.fromPromise(fetchUser(id), (c) => Defect(c));
615
592
  const Result: object;
616
593
  ```
617
594
 
618
- Defined in: [packages/core/src/facade.ts:47](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L47)
595
+ Defined in: [packages/core/src/facade.ts:45](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L45)
619
596
 
620
597
  Companion object grouping the **`Result`-producing** entry points under a
621
598
  single, discoverable namespace: [Result.Ok](#property-ok), [Result.Err](#property-err),
622
- [Result.Defect](#property-defect), [Result.Do](#property-do), [Result.fromNullable](#property-fromnullable),
623
- [Result.fromThrowable](#property-fromthrowable), [Result.all](#property-all-1), [Result.allFromDict](#property-allfromdict-1),
624
- [Result.isOk](#property-isok), [Result.isErr](#property-iserr), [Result.isDefect](#property-isdefect),
625
- [Result.isResult](#property-isresult).
599
+ [Result.Do](#property-do), [Result.fromNullable](#property-fromnullable), [Result.fromThrowable](#property-fromthrowable),
600
+ [Result.all](#property-all-1), [Result.allFromDict](#property-allfromdict-1), [Result.isOk](#property-isok),
601
+ [Result.isErr](#property-iserr), [Result.isDefect](#property-isdefect), [Result.isResult](#property-isresult).
626
602
 
627
603
  #### Type Declaration
628
604
 
629
605
  | Name | Type | Defined in |
630
606
  | ------ | ------ | ------ |
631
- | <a id="property-all-1"></a> `all()` | &lt;`Rs`&gt;(`results`) => `Result`&lt;`AllOk`&lt;`Rs`, \{ \[K in string \| number \| symbol\]: OkOf\<Rs\[K\]\> \}&gt;, [`ErrOf`](#errof)&lt;`Rs`\[`number`\]&gt;&gt; | [packages/core/src/facade.ts:54](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L54) |
632
- | <a id="property-allfromdict-1"></a> `allFromDict()` | &lt;`R`&gt;(`results`) => `Result`&lt;\{ \[K in string \| number \| symbol\]: OkOf\<R\[K\]\> \}, [`ErrOf`](#errof)&lt;`R`\[keyof `R`\]&gt;&gt; | [packages/core/src/facade.ts:55](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L55) |
633
- | <a id="property-defect"></a> `Defect()` | (`cause`) => [`Defect`](#defect) | [packages/core/src/facade.ts:50](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L50) |
634
- | <a id="property-do"></a> `Do()` | () => `Result`&lt;\{ \}, `never`&gt; | [packages/core/src/facade.ts:51](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L51) |
635
- | <a id="property-err"></a> `Err()` | &lt;`E`&gt;(`error`) => `Result`&lt;`never`, `E`&gt; | [packages/core/src/facade.ts:49](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L49) |
636
- | <a id="property-fromnullable"></a> `fromNullable()` | &lt;`T`, `E`&gt;(`value`, `onAbsent`) => `Result`&lt;`NonNullable`&lt;`T`&gt;, `E`&gt; | [packages/core/src/facade.ts:52](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L52) |
637
- | <a id="property-fromthrowable"></a> `fromThrowable()` | &lt;`A`, `T`, `R`&gt;(`fn`, `qualify`) => (...`args`) => `Result`&lt;`T`, `Exclude`&lt;`R`, [`Defect`](#defect)&gt;&gt; | [packages/core/src/facade.ts:53](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L53) |
638
- | <a id="property-isdefect"></a> `isDefect()` | &lt;`T`, `E`&gt;(`r`) => `r is DefectView<T, E>` | [packages/core/src/facade.ts:58](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L58) |
639
- | <a id="property-iserr"></a> `isErr()` | &lt;`T`, `E`&gt;(`r`) => `r is ErrView<E, T>` | [packages/core/src/facade.ts:57](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L57) |
640
- | <a id="property-isok"></a> `isOk()` | &lt;`T`, `E`&gt;(`r`) => `r is OkView<T, E>` | [packages/core/src/facade.ts:56](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L56) |
641
- | <a id="property-isresult"></a> `isResult()` | (`x`) => `x is Result<unknown, unknown>` | [packages/core/src/facade.ts:59](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L59) |
642
- | <a id="property-ok"></a> `Ok()` | &lt;`T`&gt;(`value`) => `Result`&lt;`T`, `never`&gt; | [packages/core/src/facade.ts:48](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/facade.ts#L48) |
607
+ | <a id="property-all-1"></a> `all()` | &lt;`Rs`&gt;(`results`) => `Result`&lt;`AllOk`&lt;`Rs`, \{ \[K in string \| number \| symbol\]: OkOf\<Rs\[K\]\> \}&gt;, [`ErrOf`](#errof)&lt;`Rs`\[`number`\]&gt;&gt; | [packages/core/src/facade.ts:51](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L51) |
608
+ | <a id="property-allfromdict-1"></a> `allFromDict()` | &lt;`R`&gt;(`results`) => `Result`&lt;\{ \[K in string \| number \| symbol\]: OkOf\<R\[K\]\> \}, [`ErrOf`](#errof)&lt;`R`\[keyof `R`\]&gt;&gt; | [packages/core/src/facade.ts:52](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L52) |
609
+ | <a id="property-do"></a> `Do()` | () => `Result`&lt;\{ \}, `never`&gt; | [packages/core/src/facade.ts:48](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L48) |
610
+ | <a id="property-err"></a> `Err()` | &lt;`E`&gt;(`error`) => `Result`&lt;`never`, `E`&gt; | [packages/core/src/facade.ts:47](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L47) |
611
+ | <a id="property-fromnullable"></a> `fromNullable()` | &lt;`T`, `E`&gt;(`value`, `onAbsent`) => `Result`&lt;`NonNullable`&lt;`T`&gt;, `E`&gt; | [packages/core/src/facade.ts:49](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L49) |
612
+ | <a id="property-fromthrowable"></a> `fromThrowable()` | &lt;`A`, `T`, `R`&gt;(`fn`, `qualify`) => (...`args`) => `Result`&lt;`T`, `Exclude`&lt;`R`, `Defect`&gt;&gt; | [packages/core/src/facade.ts:50](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L50) |
613
+ | <a id="property-isdefect"></a> `isDefect()` | &lt;`T`, `E`&gt;(`r`) => `r is DefectView<T, E>` | [packages/core/src/facade.ts:55](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L55) |
614
+ | <a id="property-iserr"></a> `isErr()` | &lt;`T`, `E`&gt;(`r`) => `r is ErrView<E, T>` | [packages/core/src/facade.ts:54](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L54) |
615
+ | <a id="property-isok"></a> `isOk()` | &lt;`T`, `E`&gt;(`r`) => `r is OkView<T, E>` | [packages/core/src/facade.ts:53](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L53) |
616
+ | <a id="property-isresult"></a> `isResult()` | (`x`) => `x is Result<unknown, unknown>` | [packages/core/src/facade.ts:56](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L56) |
617
+ | <a id="property-ok"></a> `Ok()` | &lt;`T`&gt;(`value`) => `Result`&lt;`T`, `never`&gt; | [packages/core/src/facade.ts:46](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/facade.ts#L46) |
643
618
 
644
619
  #### Remarks
645
620
 
@@ -667,7 +642,7 @@ Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // 2
667
642
  function all<Rs>(results): Result<AllOk<Rs, { [K in string | number | symbol]: OkOf<Rs[K]> }>, ErrOf<Rs[number]>>;
668
643
  ```
669
644
 
670
- Defined in: [packages/core/src/interop.ts:249](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/interop.ts#L249)
645
+ Defined in: [packages/core/src/interop.ts:254](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/interop.ts#L254)
671
646
 
672
647
  Collect a tuple/array of [Result](#result)s into a single `Result` of all their
673
648
  success values.
@@ -713,7 +688,7 @@ all([Ok(1), Ok(2)] as Result<number, never>[]).unwrap(); // number[]
713
688
  function allAsync<Rs>(results): AsyncResult<AllOk<Rs, { [K in string | number | symbol]: AsyncOkOf<Rs[K]> }>, AsyncErrOf<Rs[number]>>;
714
689
  ```
715
690
 
716
- Defined in: [packages/core/src/interop.ts:299](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/interop.ts#L299)
691
+ Defined in: [packages/core/src/interop.ts:304](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/interop.ts#L304)
717
692
 
718
693
  The asynchronous counterpart of [all](#all): combine a tuple/array of
719
694
  [AsyncResult](#asyncresult)s into one `AsyncResult` of all their success values.
@@ -756,7 +731,7 @@ await allAsync([fromSafePromise(a()), fromSafePromise(b())]);
756
731
  function allFromDict<R>(results): Result<{ [K in string | number | symbol]: OkOf<R[K]> }, ErrOf<R[keyof R]>>;
757
732
  ```
758
733
 
759
- Defined in: [packages/core/src/interop.ts:274](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/interop.ts#L274)
734
+ Defined in: [packages/core/src/interop.ts:279](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/interop.ts#L279)
760
735
 
761
736
  Collect a **record** of [Result](#result)s into a single `Result` of a record of
762
737
  their success values — `allFromDict({ a: Result<A, E>, b: Result<B, E> })` is
@@ -799,7 +774,7 @@ allFromDict({ id: Ok(1), name: Ok("ada") }).unwrap(); // { id: 1, name: "ada" }
799
774
  function allFromDictAsync<R>(results): AsyncResult<{ [K in string | number | symbol]: AsyncOkOf<R[K]> }, AsyncErrOf<R[keyof R]>>;
800
775
  ```
801
776
 
802
- Defined in: [packages/core/src/interop.ts:327](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/interop.ts#L327)
777
+ Defined in: [packages/core/src/interop.ts:332](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/interop.ts#L332)
803
778
 
804
779
  The asynchronous counterpart of [allFromDict](#allfromdict): combine a record of
805
780
  [AsyncResult](#asyncresult)s into one `AsyncResult` of a record of their values.
@@ -834,41 +809,6 @@ await allFromDictAsync({ a: fromSafePromise(a()), b: fromSafePromise(b()) });
834
809
 
835
810
  ***
836
811
 
837
- ### Defect()
838
-
839
- ```ts
840
- function Defect(cause): Defect;
841
- ```
842
-
843
- Defined in: [packages/core/src/defect.ts:36](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/defect.ts#L36)
844
-
845
- Wrap a cause as a [Defect](#defect-2) — the value you return from a `qualify`
846
- function when a failure is **not** a modeled domain error.
847
-
848
- #### Parameters
849
-
850
- | Parameter | Type | Description |
851
- | ------ | ------ | ------ |
852
- | `cause` | `unknown` | the original thrown/rejected value. |
853
-
854
- #### Returns
855
-
856
- [`Defect`](#defect)
857
-
858
- an opaque Defect marker carrying `cause`.
859
-
860
- #### Example
861
-
862
- ```ts
863
- import { fromPromise, Defect } from "unthrown";
864
-
865
- const user = fromPromise(fetchUser(id), (cause) =>
866
- cause instanceof NotFoundError ? cause : Defect(cause),
867
- );
868
- ```
869
-
870
- ***
871
-
872
812
  ### Do()
873
813
 
874
814
  ```ts
@@ -876,7 +816,7 @@ function Do(): Result<{
876
816
  }, never>;
877
817
  ```
878
818
 
879
- Defined in: [packages/core/src/do.ts:30](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/do.ts#L30)
819
+ Defined in: [packages/core/src/do.ts:30](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/do.ts#L30)
880
820
 
881
821
  Start a do-notation chain with an empty object scope, grown step by step with
882
822
  `bind` (for `Result`-returning steps) and `let` (for pure values).
@@ -914,7 +854,7 @@ const result = Do()
914
854
  function Err<E>(error): Result<never, E>;
915
855
  ```
916
856
 
917
- Defined in: [packages/core/src/constructors.ts:34](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/constructors.ts#L34)
857
+ Defined in: [packages/core/src/constructors.ts:34](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/constructors.ts#L34)
918
858
 
919
859
  Construct a failed [Result](#result) carrying a **modeled** error.
920
860
 
@@ -949,7 +889,7 @@ Err("not_found").unwrapErr(); // "not_found"
949
889
  function fromNullable<T, E>(value, onAbsent): Result<NonNullable<T>, E>;
950
890
  ```
951
891
 
952
- Defined in: [packages/core/src/interop.ts:29](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/interop.ts#L29)
892
+ Defined in: [packages/core/src/interop.ts:29](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/interop.ts#L29)
953
893
 
954
894
  Bridge a nullable value into a [Result](#result): absence becomes a **modeled**
955
895
  `Err`. The sanctioned alternative to an `Option` type.
@@ -992,7 +932,7 @@ fromNullable(map.get(key), () => "missing").unwrap();
992
932
  function fromPromise<T, R>(promise, qualify): AsyncResult<T, Exclude<R, Defect>>;
993
933
  ```
994
934
 
995
- Defined in: [packages/core/src/interop.ts:110](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/interop.ts#L110)
935
+ Defined in: [packages/core/src/interop.ts:113](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/interop.ts#L113)
996
936
 
997
937
  Wrap a `Promise` (or a thunk producing one) as an [AsyncResult](#asyncresult), forcing
998
938
  every rejection to be triaged.
@@ -1009,30 +949,30 @@ every rejection to be triaged.
1009
949
  | Parameter | Type | Description |
1010
950
  | ------ | ------ | ------ |
1011
951
  | `promise` | `Promise`&lt;`T`&gt; \| (() => `Promise`&lt;`T`&gt;) | the promise, or a thunk returning one. |
1012
- | `qualify` | (`cause`) => `R` | triages a rejection cause into `E` or a `Defect`. |
952
+ | `qualify` | (`cause`, `defect`) => `R` | triages a rejection `cause` into a modeled `E`, or marks it unmodeled by returning `defect(cause)` (the helper passed as its second arg). |
1013
953
 
1014
954
  #### Returns
1015
955
 
1016
- `AsyncResult`&lt;`T`, `Exclude`&lt;`R`, [`Defect`](#defect)&gt;&gt;
956
+ `AsyncResult`&lt;`T`, `Exclude`&lt;`R`, `Defect`&gt;&gt;
1017
957
 
1018
958
  #### Remarks
1019
959
 
1020
960
  `qualify` **must** map each rejection cause into a modeled error `E` or a
1021
- [Defect](#defect-2). The returned `AsyncResult`'s internal promise never rejects;
1022
- `await`-ing it always yields a `Result`. A throw inside `qualify` is itself a
1023
- `Defect`.
961
+ `Defect` (via the injected `defect` helper, its second argument). The returned
962
+ `AsyncResult`'s internal promise never rejects; `await`-ing it always yields a
963
+ `Result`. A throw inside `qualify` is itself a `Defect`.
1024
964
 
1025
965
  The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
1026
966
  `qualify`'s return is **subtracted** from `E`, never inferred into it. So a
1027
- `qualify` that returns *only* `Defect(cause)` yields `E = never`; when every
967
+ `qualify` that returns *only* `defect(cause)` yields `E = never`; when every
1028
968
  rejection is a Defect, prefer [fromSafePromise](#fromsafepromise).
1029
969
 
1030
970
  #### Example
1031
971
 
1032
972
  ```ts
1033
- import { fromPromise, Defect } from "unthrown";
1034
- const user = await fromPromise(fetchUser(id), (cause) =>
1035
- cause instanceof NotFoundError ? ("not_found" as const) : Defect(cause),
973
+ import { fromPromise } from "unthrown";
974
+ const user = await fromPromise(fetchUser(id), (cause, defect) =>
975
+ cause instanceof NotFoundError ? ("not_found" as const) : defect(cause),
1036
976
  );
1037
977
  ```
1038
978
 
@@ -1044,7 +984,7 @@ const user = await fromPromise(fetchUser(id), (cause) =>
1044
984
  function fromSafePromise<T>(promise): AsyncResult<T, never>;
1045
985
  ```
1046
986
 
1047
- Defined in: [packages/core/src/interop.ts:136](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/interop.ts#L136)
987
+ Defined in: [packages/core/src/interop.ts:139](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/interop.ts#L139)
1048
988
 
1049
989
  Wrap a `Promise` asserted **not** to fail in any modeled way: any rejection
1050
990
  becomes a `Defect`.
@@ -1079,7 +1019,7 @@ triage. (`await`-ing still yields a `Result`; it never throws.)
1079
1019
  function fromThrowable<A, T, R>(fn, qualify): (...args) => Result<T, Exclude<R, Defect>>;
1080
1020
  ```
1081
1021
 
1082
- Defined in: [packages/core/src/interop.ts:66](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/interop.ts#L66)
1022
+ Defined in: [packages/core/src/interop.ts:68](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/interop.ts#L68)
1083
1023
 
1084
1024
  Wrap a throwing synchronous function so it returns a [Result](#result) instead of
1085
1025
  throwing.
@@ -1097,31 +1037,32 @@ throwing.
1097
1037
  | Parameter | Type | Description |
1098
1038
  | ------ | ------ | ------ |
1099
1039
  | `fn` | (...`args`) => `T` | the throwing function to wrap. |
1100
- | `qualify` | (`cause`) => `R` | triages a thrown cause into `E` or a `Defect`. |
1040
+ | `qualify` | (`cause`, `defect`) => `R` | triages a thrown `cause` into a modeled `E`, or marks it unmodeled by returning `defect(cause)` (the helper passed as its second arg). |
1101
1041
 
1102
1042
  #### Returns
1103
1043
 
1104
1044
  a function with the same arguments returning `Result<T, E>`.
1105
1045
 
1106
- (...`args`) => `Result`&lt;`T`, `Exclude`&lt;`R`, [`Defect`](#defect)&gt;&gt;
1046
+ (...`args`) => `Result`&lt;`T`, `Exclude`&lt;`R`, `Defect`&gt;&gt;
1107
1047
 
1108
1048
  #### Remarks
1109
1049
 
1110
1050
  `qualify` **must** triage every thrown cause into a modeled error `E` or a
1111
- [Defect](#defect-2) (via [Defect](#defect-2)) — there is no path that leaves `unknown`
1112
- in `E`. A throw inside `qualify` itself is treated as a `Defect`.
1051
+ `Defect` (via the injected `defect` helper, its second argument) — there is no
1052
+ path that leaves `unknown` in `E`. A throw inside `qualify` itself is treated
1053
+ as a `Defect`.
1113
1054
 
1114
1055
  The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
1115
1056
  `qualify`'s return is **subtracted** from `E`, never inferred into it. So a
1116
- `qualify` that returns *only* `Defect(cause)` yields `E = never` (a Defect is
1057
+ `qualify` that returns *only* `defect(cause)` yields `E = never` (a Defect is
1117
1058
  out-of-band and must not pollute the error channel); reach for
1118
1059
  [fromSafePromise](#fromsafepromise) when every failure is a Defect.
1119
1060
 
1120
1061
  #### Example
1121
1062
 
1122
1063
  ```ts
1123
- import { fromThrowable, Defect } from "unthrown";
1124
- const parse = fromThrowable(JSON.parse, (cause) => Defect(cause));
1064
+ import { fromThrowable } from "unthrown";
1065
+ const parse = fromThrowable(JSON.parse, (cause, defect) => defect(cause));
1125
1066
  parse("{}").unwrap();
1126
1067
  ```
1127
1068
 
@@ -1133,7 +1074,7 @@ parse("{}").unwrap();
1133
1074
  function isDefect<T, E>(r): r is DefectView<T, E>;
1134
1075
  ```
1135
1076
 
1136
- Defined in: [packages/core/src/constructors.ts:66](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/constructors.ts#L66)
1077
+ Defined in: [packages/core/src/constructors.ts:66](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/constructors.ts#L66)
1137
1078
 
1138
1079
  Type guard: narrow a [Result](#result) to its `Defect` variant, exposing `.cause`.
1139
1080
 
@@ -1164,7 +1105,7 @@ Type guard: narrow a [Result](#result) to its `Defect` variant, exposing `.cause
1164
1105
  function isErr<T, E>(r): r is ErrView<E, T>;
1165
1106
  ```
1166
1107
 
1167
- Defined in: [packages/core/src/constructors.ts:58](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/constructors.ts#L58)
1108
+ Defined in: [packages/core/src/constructors.ts:58](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/constructors.ts#L58)
1168
1109
 
1169
1110
  Type guard: narrow a [Result](#result) to its `Err` variant, exposing `.error`.
1170
1111
 
@@ -1195,7 +1136,7 @@ Type guard: narrow a [Result](#result) to its `Err` variant, exposing `.error`.
1195
1136
  function isOk<T, E>(r): r is OkView<T, E>;
1196
1137
  ```
1197
1138
 
1198
- Defined in: [packages/core/src/constructors.ts:50](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/constructors.ts#L50)
1139
+ Defined in: [packages/core/src/constructors.ts:50](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/constructors.ts#L50)
1199
1140
 
1200
1141
  Type guard: narrow a [Result](#result) to its `Ok` variant, exposing `.value`.
1201
1142
 
@@ -1234,7 +1175,7 @@ if (isOk(r)) r.value; // number, narrowed
1234
1175
  function isResult(x): x is Result<unknown, unknown>;
1235
1176
  ```
1236
1177
 
1237
- Defined in: [packages/core/src/core.ts:333](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/core.ts#L333)
1178
+ Defined in: [packages/core/src/core.ts:338](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/core.ts#L338)
1238
1179
 
1239
1180
  Type guard: is `x` a [Result](#result) (any of `Ok` / `Err` / `Defect`)?
1240
1181
 
@@ -1268,7 +1209,7 @@ is not a `Result` and returns `false`.
1268
1209
  function matchTags<T, E, R>(result, handlers): R;
1269
1210
  ```
1270
1211
 
1271
- Defined in: [packages/core/src/tagged.ts:138](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/tagged.ts#L138)
1212
+ Defined in: [packages/core/src/tagged.ts:138](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/tagged.ts#L138)
1272
1213
 
1273
1214
  Exhaustively fold a [Result](#result) (or [AsyncResult](#asyncresult)) whose error type is
1274
1215
  a tagged union, dispatching each error to the handler matching its `_tag`.
@@ -1320,7 +1261,7 @@ matchTags(r, {
1320
1261
  function matchTags<T, E, R>(result, handlers): Promise<R>;
1321
1262
  ```
1322
1263
 
1323
- Defined in: [packages/core/src/tagged.ts:142](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/tagged.ts#L142)
1264
+ Defined in: [packages/core/src/tagged.ts:142](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/tagged.ts#L142)
1324
1265
 
1325
1266
  Exhaustively fold a [Result](#result) (or [AsyncResult](#asyncresult)) whose error type is
1326
1267
  a tagged union, dispatching each error to the handler matching its `_tag`.
@@ -1374,7 +1315,7 @@ matchTags(r, {
1374
1315
  function Ok<T>(value): Result<T, never>;
1375
1316
  ```
1376
1317
 
1377
- Defined in: [packages/core/src/constructors.ts:18](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/constructors.ts#L18)
1318
+ Defined in: [packages/core/src/constructors.ts:18](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/constructors.ts#L18)
1378
1319
 
1379
1320
  Construct a successful [Result](#result).
1380
1321
 
@@ -1409,7 +1350,7 @@ Ok(42).unwrap(); // 42
1409
1350
  function TaggedError<Tag>(tag, options?): TaggedErrorConstructor<Tag>;
1410
1351
  ```
1411
1352
 
1412
- Defined in: [packages/core/src/tagged.ts:72](https://github.com/btravstack/unthrown/blob/9964bddff12c79925119bbfc5de67104bbcfc533/packages/core/src/tagged.ts#L72)
1353
+ Defined in: [packages/core/src/tagged.ts:72](https://github.com/btravstack/unthrown/blob/6af2083f66eff6f878bfea8d336602c60827f96e/packages/core/src/tagged.ts#L72)
1413
1354
 
1414
1355
  Build a base class for a tagged error — a class extending `Error` with a
1415
1356
  `_tag` string discriminant, in the style of Effect's `Data.TaggedError`.