unthrown 5.0.0-beta.7 → 5.0.0-beta.9
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -3
- package/dist/index.cjs +37 -35
- package/dist/index.d.cts +69 -49
- package/dist/index.d.cts.map +1 -1
- package/dist/index.d.mts +69 -49
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +38 -35
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -11,7 +11,7 @@ pnpm add unthrown
|
|
|
11
11
|
```
|
|
12
12
|
|
|
13
13
|
No peer dependencies — the exhaustive error matcher is built-in and exported as
|
|
14
|
-
`match` / `P
|
|
14
|
+
`match` / `P`.
|
|
15
15
|
|
|
16
16
|
```ts
|
|
17
17
|
import { fromPromise, P, TaggedError } from "unthrown";
|
|
@@ -25,7 +25,8 @@ const user = fromPromise(fetchUser(id), (cause, defect) =>
|
|
|
25
25
|
|
|
26
26
|
const status = await user.match({
|
|
27
27
|
ok: () => 200,
|
|
28
|
-
|
|
28
|
+
// `errCases` takes the exhaustive matcher — every case of E named:
|
|
29
|
+
errCases: (matcher) => matcher.with(P.tag("NotFound"), () => 404),
|
|
29
30
|
defect: () => 500,
|
|
30
31
|
});
|
|
31
32
|
```
|
|
@@ -35,7 +36,7 @@ const status = await user.match({
|
|
|
35
36
|
observable only via `match` / `recoverDefect`.
|
|
36
37
|
- **Qualification at every boundary** — `fromPromise` / `fromThrowable` force you
|
|
37
38
|
to triage each failure into a modeled error or a defect.
|
|
38
|
-
- **Tagged errors** — `TaggedError(tag)` + `tag(t)`, folded exhaustively through
|
|
39
|
+
- **Tagged errors** — `TaggedError(tag)` + `P.tag(t)`, folded exhaustively through
|
|
39
40
|
`match`'s built-in error matcher.
|
|
40
41
|
- **Zero runtime dependencies** (the matcher is built-in), ESM-first, dual
|
|
41
42
|
CJS/ESM.
|
package/dist/index.cjs
CHANGED
|
@@ -48,7 +48,7 @@ function isPlainObject(x) {
|
|
|
48
48
|
/**
|
|
49
49
|
* Runtime test: does `pattern` match `value`? A branded `P.*` pattern applies
|
|
50
50
|
* its predicate; a **plain-object** pattern (an object literal, e.g. the
|
|
51
|
-
* `{ _tag }` produced by `tag()`) matches when every key matches recursively
|
|
51
|
+
* `{ _tag }` produced by `P.tag()`) matches when every key matches recursively
|
|
52
52
|
* (extra keys on the value are ignored — matching is structural); anything
|
|
53
53
|
* else — primitives, but also class instances, arrays, and foreign pattern
|
|
54
54
|
* objects (e.g. a real ts-pattern matcher, whose keys are symbols) — is
|
|
@@ -117,8 +117,10 @@ Object.freeze(MatcherImpl.prototype);
|
|
|
117
117
|
* @remarks
|
|
118
118
|
* This is unthrown's own matcher (the former ts-pattern re-export): the same
|
|
119
119
|
* call-site shape, with exhaustiveness computed by plain `Exclude` over the
|
|
120
|
-
* builder's `Remaining` parameter.
|
|
121
|
-
* even over an
|
|
120
|
+
* builder's `Remaining` parameter. Name every case of the input union; the
|
|
121
|
+
* `P._` catch-all is the escape hatch, and is provably exhaustive even over an
|
|
122
|
+
* unresolved generic input — one of the two cases it is irreplaceable for (see
|
|
123
|
+
* {@link P}).
|
|
122
124
|
*
|
|
123
125
|
* @category Constructors
|
|
124
126
|
*/
|
|
@@ -133,9 +135,25 @@ const universal = pattern(() => true);
|
|
|
133
135
|
/**
|
|
134
136
|
* The pattern namespace (unthrown's own; the former ts-pattern `P`):
|
|
135
137
|
*
|
|
136
|
-
* - `P._` / `P.any` — the universal catch-all
|
|
137
|
-
*
|
|
138
|
-
*
|
|
138
|
+
* - `P._` / `P.any` — the universal catch-all, and an **escape hatch** rather
|
|
139
|
+
* than the default: matching the error channel means naming its cases, so
|
|
140
|
+
* reach for this only where they cannot be named. Matches anything, and
|
|
141
|
+
* (because its phantom type is `unknown`) makes the builder provably
|
|
142
|
+
* exhaustive even when the matched input is an unresolved type parameter.
|
|
143
|
+
* Two situations are legitimate: a **helper generic in `E`**, where no arm
|
|
144
|
+
* list can prove exhaustiveness against an unresolved type parameter; and an
|
|
145
|
+
* **`E` that is a single type**, not a union of cases (a validator's issues
|
|
146
|
+
* array, say), where one arm _is_ the enumeration. `@unthrown/oxlint`'s
|
|
147
|
+
* `no-catch-all-pattern` (in its `recommended` preset) flags every other use;
|
|
148
|
+
* keep the deliberate ones behind a targeted `oxlint-disable` saying which of
|
|
149
|
+
* the two it is.
|
|
150
|
+
* - `P.tag<const Tag extends string>(value: Tag): { _tag: Tag }` — the
|
|
151
|
+
* `{ _tag: t }` object pattern, matching any value whose `_tag` equals `t` (a
|
|
152
|
+
* `TaggedError`, or any `_tag`-discriminated member) and narrowing the
|
|
153
|
+
* branch's parameter to that variant, payload included. The workhorse of the
|
|
154
|
+
* error channel: `matcher.with(P.tag("NotFound"), (e) => …)`. It composes like
|
|
155
|
+
* any other pattern — in a grouped arm
|
|
156
|
+
* (`.with(P.tag("A"), P.tag("B"), handler)`) and inside `P.union`.
|
|
139
157
|
* - `P.instanceOf(Cls)` — an `instanceof` check, narrowing to the class
|
|
140
158
|
* instance type (for union members that are not tagged, e.g. a third-party
|
|
141
159
|
* error class).
|
|
@@ -148,6 +166,7 @@ const universal = pattern(() => true);
|
|
|
148
166
|
const P = Object.freeze({
|
|
149
167
|
_: universal,
|
|
150
168
|
any: universal,
|
|
169
|
+
tag: (value) => ({ _tag: value }),
|
|
151
170
|
instanceOf: (cls) => pattern((value) => value instanceof cls),
|
|
152
171
|
when: (guard) => pattern(guard),
|
|
153
172
|
union: (...patterns) => pattern((value) => patterns.some((sub) => matches(sub, value))),
|
|
@@ -507,7 +526,7 @@ function defectRes(cause) {
|
|
|
507
526
|
*
|
|
508
527
|
* @example
|
|
509
528
|
* ```ts
|
|
510
|
-
* import { isResult, Ok } from "unthrown";
|
|
529
|
+
* import { isResult, Ok, P } from "unthrown";
|
|
511
530
|
*
|
|
512
531
|
* isResult(Ok(1)); // => true
|
|
513
532
|
* isResult({ tag: "Ok" }); // => false (look-alike, wrong prototype)
|
|
@@ -515,6 +534,9 @@ function defectRes(cause) {
|
|
|
515
534
|
*
|
|
516
535
|
* const x: unknown = Ok(1);
|
|
517
536
|
* if (isResult(x))
|
|
537
|
+
* // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
|
|
538
|
+
* // so the `P._` escape hatch is the only arm that can terminate the match:
|
|
539
|
+
* // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
|
|
518
540
|
* x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
|
|
519
541
|
* ```
|
|
520
542
|
*
|
|
@@ -1507,10 +1529,14 @@ const AsyncResult = {
|
|
|
1507
1529
|
* so a payload `cause` (e.g. a wrapped driver error) is a legitimate,
|
|
1508
1530
|
* *narrowing* structured field.
|
|
1509
1531
|
*
|
|
1510
|
-
*
|
|
1511
|
-
*
|
|
1512
|
-
*
|
|
1513
|
-
*
|
|
1532
|
+
* The matching half of the convention is `P.tag(t)` — the pattern constructor on
|
|
1533
|
+
* the `P` namespace, which builds the `{ _tag: t }` pattern this factory's `_tag`
|
|
1534
|
+
* is selected by (there is no standalone `tag` export).
|
|
1535
|
+
*
|
|
1536
|
+
* `_tag` is the discriminant matched by `P.tag` in the error combinators
|
|
1537
|
+
* (`result.mapErrCases((matcher) => matcher.with(P.tag("NotFound"), …))`) and in
|
|
1538
|
+
* `match`'s `errCases` handler; `Error.name` is the human-facing label in stack
|
|
1539
|
+
* traces and logs. By default they coincide, but
|
|
1514
1540
|
* they can be **decoupled** with `options.name` — so a tag can be namespaced for
|
|
1515
1541
|
* collision-safety (`"@my-lib/RetryableError"`) without that slash-prefixed
|
|
1516
1542
|
* string leaking into `Error.name`:
|
|
@@ -1569,29 +1595,6 @@ function TaggedError(tag, options) {
|
|
|
1569
1595
|
}
|
|
1570
1596
|
return TaggedErrorBase;
|
|
1571
1597
|
}
|
|
1572
|
-
/**
|
|
1573
|
-
* A matcher pattern matching any value whose `_tag` equals `value` — a
|
|
1574
|
-
* {@link TaggedError}, or any discriminated member. Equivalent to the object
|
|
1575
|
-
* pattern `{ _tag: value }`, but reads better inside an error-matching
|
|
1576
|
-
* combinator and narrows to the matching variant, payload included.
|
|
1577
|
-
*
|
|
1578
|
-
* @typeParam Tag - the string literal tag to match.
|
|
1579
|
-
* @param value - the `_tag` to match.
|
|
1580
|
-
*
|
|
1581
|
-
* @category Tagged errors
|
|
1582
|
-
*
|
|
1583
|
-
* @example
|
|
1584
|
-
* ```ts
|
|
1585
|
-
* result.mapErrCases((matcher) =>
|
|
1586
|
-
* matcher
|
|
1587
|
-
* .with(tag("NotFound"), () => new NotFoundException())
|
|
1588
|
-
* .with(tag("Conflict"), (e) => new ConflictException(e.key)),
|
|
1589
|
-
* );
|
|
1590
|
-
* ```
|
|
1591
|
-
*/
|
|
1592
|
-
function tag(value) {
|
|
1593
|
-
return { _tag: value };
|
|
1594
|
-
}
|
|
1595
1598
|
//#endregion
|
|
1596
1599
|
exports.AsyncResult = AsyncResult;
|
|
1597
1600
|
exports.Do = Do;
|
|
@@ -1619,4 +1622,3 @@ exports.isErr = isErr;
|
|
|
1619
1622
|
exports.isOk = isOk;
|
|
1620
1623
|
exports.isResult = isResult;
|
|
1621
1624
|
exports.match = match;
|
|
1622
|
-
exports.tag = tag;
|
package/dist/index.d.cts
CHANGED
|
@@ -127,17 +127,23 @@ type PinTooLate = {
|
|
|
127
127
|
*/
|
|
128
128
|
type Matcher<E, Remaining, O, Declared = Unset> = {
|
|
129
129
|
/**
|
|
130
|
-
* The catch-all arm: `.with(P._, handler)` / `.with(P.any, handler)
|
|
131
|
-
* **
|
|
132
|
-
*
|
|
133
|
-
*
|
|
134
|
-
*
|
|
135
|
-
*
|
|
130
|
+
* The catch-all arm: `.with(P._, handler)` / `.with(P.any, handler)` — the
|
|
131
|
+
* wildcard **escape hatch**, not the way to handle a concrete error union
|
|
132
|
+
* (name those cases; `@unthrown/oxlint`'s `no-catch-all-pattern`, in its
|
|
133
|
+
* `recommended` preset, flags the wildcard).
|
|
134
|
+
*
|
|
135
|
+
* It is a **state transition**, not a computation — it returns
|
|
136
|
+
* `Matcher<E, never, …>` with the remaining cases literally `never`, so the
|
|
137
|
+
* builder is provably exhaustive even when `E` is an unresolved type
|
|
138
|
+
* parameter (a lazily-deferred `Exclude<E, unknown>` would not resolve
|
|
139
|
+
* there). That is what makes it irreplaceable for a helper generic in `E`:
|
|
140
|
+
* it can terminate a match no arm list could (issue #145) — one of the two
|
|
141
|
+
* sanctioned uses (see {@link P}).
|
|
136
142
|
*/
|
|
137
143
|
with<O2>(pattern: UniversalPattern, handler: (value: Remaining) => BranchReturn<Declared, O2>): Matcher<E, never, O | O2, Declared>;
|
|
138
144
|
/**
|
|
139
145
|
* Add an arm: one or more patterns sharing a single handler (grouped
|
|
140
|
-
* patterns — `matcher.with(tag("A"), tag("B"), handler)`). The handler
|
|
146
|
+
* patterns — `matcher.with(P.tag("A"), P.tag("B"), handler)`). The handler
|
|
141
147
|
* receives the input narrowed to what the patterns match (computed against
|
|
142
148
|
* `Remaining`, so cases already handled by earlier arms are excluded); the
|
|
143
149
|
* matched cases are subtracted from `Remaining`.
|
|
@@ -208,8 +214,10 @@ declare class NonExhaustiveError extends Error {
|
|
|
208
214
|
* @remarks
|
|
209
215
|
* This is unthrown's own matcher (the former ts-pattern re-export): the same
|
|
210
216
|
* call-site shape, with exhaustiveness computed by plain `Exclude` over the
|
|
211
|
-
* builder's `Remaining` parameter.
|
|
212
|
-
* even over an
|
|
217
|
+
* builder's `Remaining` parameter. Name every case of the input union; the
|
|
218
|
+
* `P._` catch-all is the escape hatch, and is provably exhaustive even over an
|
|
219
|
+
* unresolved generic input — one of the two cases it is irreplaceable for (see
|
|
220
|
+
* {@link P}).
|
|
213
221
|
*
|
|
214
222
|
* @category Constructors
|
|
215
223
|
*/
|
|
@@ -217,9 +225,25 @@ declare function match<const E>(value: E): Matcher<E, E, never>;
|
|
|
217
225
|
/**
|
|
218
226
|
* The pattern namespace (unthrown's own; the former ts-pattern `P`):
|
|
219
227
|
*
|
|
220
|
-
* - `P._` / `P.any` — the universal catch-all
|
|
221
|
-
*
|
|
222
|
-
*
|
|
228
|
+
* - `P._` / `P.any` — the universal catch-all, and an **escape hatch** rather
|
|
229
|
+
* than the default: matching the error channel means naming its cases, so
|
|
230
|
+
* reach for this only where they cannot be named. Matches anything, and
|
|
231
|
+
* (because its phantom type is `unknown`) makes the builder provably
|
|
232
|
+
* exhaustive even when the matched input is an unresolved type parameter.
|
|
233
|
+
* Two situations are legitimate: a **helper generic in `E`**, where no arm
|
|
234
|
+
* list can prove exhaustiveness against an unresolved type parameter; and an
|
|
235
|
+
* **`E` that is a single type**, not a union of cases (a validator's issues
|
|
236
|
+
* array, say), where one arm _is_ the enumeration. `@unthrown/oxlint`'s
|
|
237
|
+
* `no-catch-all-pattern` (in its `recommended` preset) flags every other use;
|
|
238
|
+
* keep the deliberate ones behind a targeted `oxlint-disable` saying which of
|
|
239
|
+
* the two it is.
|
|
240
|
+
* - `P.tag<const Tag extends string>(value: Tag): { _tag: Tag }` — the
|
|
241
|
+
* `{ _tag: t }` object pattern, matching any value whose `_tag` equals `t` (a
|
|
242
|
+
* `TaggedError`, or any `_tag`-discriminated member) and narrowing the
|
|
243
|
+
* branch's parameter to that variant, payload included. The workhorse of the
|
|
244
|
+
* error channel: `matcher.with(P.tag("NotFound"), (e) => …)`. It composes like
|
|
245
|
+
* any other pattern — in a grouped arm
|
|
246
|
+
* (`.with(P.tag("A"), P.tag("B"), handler)`) and inside `P.union`.
|
|
223
247
|
* - `P.instanceOf(Cls)` — an `instanceof` check, narrowing to the class
|
|
224
248
|
* instance type (for union members that are not tagged, e.g. a third-party
|
|
225
249
|
* error class).
|
|
@@ -232,6 +256,9 @@ declare function match<const E>(value: E): Matcher<E, E, never>;
|
|
|
232
256
|
declare const P: Readonly<{
|
|
233
257
|
_: UniversalPattern;
|
|
234
258
|
any: UniversalPattern;
|
|
259
|
+
tag: <const Tag extends string>(value: Tag) => {
|
|
260
|
+
_tag: Tag;
|
|
261
|
+
};
|
|
235
262
|
instanceOf: <C extends abstract new (...args: never[]) => unknown>(cls: C) => PatternMatcher<InstanceType<C>>;
|
|
236
263
|
when: <G>(guard: (value: unknown) => value is G) => PatternMatcher<G>;
|
|
237
264
|
union: <const Pts extends readonly [unknown, ...unknown[]]>(...patterns: Pts) => PatternMatcher<MatchedOf<Pts[number]>>;
|
|
@@ -499,9 +526,15 @@ type ResultMethods<out T, out E> = {
|
|
|
499
526
|
* to a `Defect` and drops it from `E`. Runs only on `Err`; `Ok` and `Defect`
|
|
500
527
|
* pass through. A branch that throws also becomes a `Defect`.
|
|
501
528
|
*
|
|
502
|
-
*
|
|
503
|
-
*
|
|
504
|
-
*
|
|
529
|
+
* **Name every case.** Match on anything the matcher supports — `_tag`,
|
|
530
|
+
* `code`, structural shape, guards — and group the cases that share a handler
|
|
531
|
+
* with `.with(a, b, handler)`. `.with(P._, …)` is the wildcard **escape
|
|
532
|
+
* hatch**, not the default: it makes any match exhaustive, so it also absorbs
|
|
533
|
+
* every case `E` grows later. Two uses are sanctioned — a helper generic in
|
|
534
|
+
* `E`, where no arm list can prove exhaustiveness against an unresolved type
|
|
535
|
+
* parameter, and an `E` that is a single type rather than a union of cases
|
|
536
|
+
* (see {@link P} for both). `@unthrown/oxlint`'s `no-catch-all-pattern` (in
|
|
537
|
+
* its `recommended` preset) flags the rest.
|
|
505
538
|
*
|
|
506
539
|
* @typeParam M - the exhaustive builder the callback returns.
|
|
507
540
|
* @param f - builds the match over the error (returns the un-terminated builder).
|
|
@@ -542,7 +575,8 @@ type ResultMethods<out T, out E> = {
|
|
|
542
575
|
* @remarks
|
|
543
576
|
* The callback builds a match whose branches run side effects; their return
|
|
544
577
|
* values are ignored and the original `Err` flows through. Exhaustive like the
|
|
545
|
-
* transformers
|
|
578
|
+
* transformers, and like them it wants every case named — `.with(P._, …)`
|
|
579
|
+
* remains the wildcard escape hatch. If a branch throws, the
|
|
546
580
|
* result is a `Defect` whose cause is an `AggregateError` of `[thrown, original
|
|
547
581
|
* failure]` — observing a failure never destroys it. An **async branch is
|
|
548
582
|
* rejected at compile time** ({@link NotThenable} on the builder output):
|
|
@@ -642,8 +676,9 @@ type ResultMethods<out T, out E> = {
|
|
|
642
676
|
* exactly like the error combinators — which is why the key carries the same
|
|
643
677
|
* `…Cases` suffix. Chain `.with(pattern, handler)` and **return the
|
|
644
678
|
* un-terminated builder** — `match` calls `.exhaustive()` itself, so a missing
|
|
645
|
-
* case is a compile error at the call site (no `.exhaustive()` to forget).
|
|
646
|
-
* `.with(P._, …)`
|
|
679
|
+
* case is a compile error at the call site (no `.exhaustive()` to forget).
|
|
680
|
+
* Folding at the edge names every case too — `.with(P._, …)` is the wildcard
|
|
681
|
+
* escape hatch, not the default. Unlike the combinators the branches
|
|
647
682
|
* receive **no `defect` helper** — `match` is total elimination to a value,
|
|
648
683
|
* with no `Defect` output channel; the `defect` case handles a `Result` that
|
|
649
684
|
* already carries one. (A `Result` is also a discriminated union — for richer
|
|
@@ -856,7 +891,7 @@ type FailureView<E, T = never> = ErrView<E, T> | DefectView<T, E>;
|
|
|
856
891
|
*
|
|
857
892
|
* @example
|
|
858
893
|
* ```ts
|
|
859
|
-
* import { Ok, Err,
|
|
894
|
+
* import { Ok, Err, type Result } from "unthrown";
|
|
860
895
|
*
|
|
861
896
|
* function half(n: number): Result<number, "odd"> {
|
|
862
897
|
* return n % 2 === 0 ? Ok(n / 2) : Err("odd");
|
|
@@ -864,7 +899,8 @@ type FailureView<E, T = never> = ErrView<E, T> | DefectView<T, E>;
|
|
|
864
899
|
*
|
|
865
900
|
* const message = half(10).match({
|
|
866
901
|
* ok: (n) => `got ${n}`,
|
|
867
|
-
*
|
|
902
|
+
* // every case of `E` named — here the one literal it holds
|
|
903
|
+
* errCases: (matcher) => matcher.with("odd", () => "failed: odd"),
|
|
868
904
|
* defect: (cause) => `bug: ${String(cause)}`,
|
|
869
905
|
* });
|
|
870
906
|
* ```
|
|
@@ -1396,7 +1432,7 @@ declare class GetError<E = unknown> extends Error {
|
|
|
1396
1432
|
*
|
|
1397
1433
|
* @example
|
|
1398
1434
|
* ```ts
|
|
1399
|
-
* import { isResult, Ok } from "unthrown";
|
|
1435
|
+
* import { isResult, Ok, P } from "unthrown";
|
|
1400
1436
|
*
|
|
1401
1437
|
* isResult(Ok(1)); // => true
|
|
1402
1438
|
* isResult({ tag: "Ok" }); // => false (look-alike, wrong prototype)
|
|
@@ -1404,6 +1440,9 @@ declare class GetError<E = unknown> extends Error {
|
|
|
1404
1440
|
*
|
|
1405
1441
|
* const x: unknown = Ok(1);
|
|
1406
1442
|
* if (isResult(x))
|
|
1443
|
+
* // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
|
|
1444
|
+
* // so the `P._` escape hatch is the only arm that can terminate the match:
|
|
1445
|
+
* // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
|
|
1407
1446
|
* x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
|
|
1408
1447
|
* ```
|
|
1409
1448
|
*
|
|
@@ -1934,10 +1973,14 @@ type TaggedErrorConstructor<Tag extends string> = {
|
|
|
1934
1973
|
* so a payload `cause` (e.g. a wrapped driver error) is a legitimate,
|
|
1935
1974
|
* *narrowing* structured field.
|
|
1936
1975
|
*
|
|
1937
|
-
*
|
|
1938
|
-
*
|
|
1939
|
-
*
|
|
1940
|
-
*
|
|
1976
|
+
* The matching half of the convention is `P.tag(t)` — the pattern constructor on
|
|
1977
|
+
* the `P` namespace, which builds the `{ _tag: t }` pattern this factory's `_tag`
|
|
1978
|
+
* is selected by (there is no standalone `tag` export).
|
|
1979
|
+
*
|
|
1980
|
+
* `_tag` is the discriminant matched by `P.tag` in the error combinators
|
|
1981
|
+
* (`result.mapErrCases((matcher) => matcher.with(P.tag("NotFound"), …))`) and in
|
|
1982
|
+
* `match`'s `errCases` handler; `Error.name` is the human-facing label in stack
|
|
1983
|
+
* traces and logs. By default they coincide, but
|
|
1941
1984
|
* they can be **decoupled** with `options.name` — so a tag can be namespaced for
|
|
1942
1985
|
* collision-safety (`"@my-lib/RetryableError"`) without that slash-prefixed
|
|
1943
1986
|
* string leaking into `Error.name`:
|
|
@@ -1974,29 +2017,6 @@ type TaggedErrorConstructor<Tag extends string> = {
|
|
|
1974
2017
|
declare function TaggedError<Tag extends string>(tag: Tag, options?: {
|
|
1975
2018
|
readonly name?: string;
|
|
1976
2019
|
}): TaggedErrorConstructor<Tag>;
|
|
1977
|
-
/**
|
|
1978
|
-
* A matcher pattern matching any value whose `_tag` equals `value` — a
|
|
1979
|
-
* {@link TaggedError}, or any discriminated member. Equivalent to the object
|
|
1980
|
-
* pattern `{ _tag: value }`, but reads better inside an error-matching
|
|
1981
|
-
* combinator and narrows to the matching variant, payload included.
|
|
1982
|
-
*
|
|
1983
|
-
* @typeParam Tag - the string literal tag to match.
|
|
1984
|
-
* @param value - the `_tag` to match.
|
|
1985
|
-
*
|
|
1986
|
-
* @category Tagged errors
|
|
1987
|
-
*
|
|
1988
|
-
* @example
|
|
1989
|
-
* ```ts
|
|
1990
|
-
* result.mapErrCases((matcher) =>
|
|
1991
|
-
* matcher
|
|
1992
|
-
* .with(tag("NotFound"), () => new NotFoundException())
|
|
1993
|
-
* .with(tag("Conflict"), (e) => new ConflictException(e.key)),
|
|
1994
|
-
* );
|
|
1995
|
-
* ```
|
|
1996
|
-
*/
|
|
1997
|
-
declare function tag<const Tag extends string>(value: Tag): {
|
|
1998
|
-
_tag: Tag;
|
|
1999
|
-
};
|
|
2000
2020
|
//#endregion
|
|
2001
|
-
export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type AsyncResultMethods, type Awaitable, type DefectView, Do, DoAsync, Err, ErrAsync, type ErrMatcher, type ErrOf, type ErrView, type FailureView, GetError, type Matcher, NonExhaustiveError, type NotThenable, Ok, OkAsync, type OkOf, type OkView, P, type PatternMatcher, Result, type ResultMethods, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, type UniversalPattern, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, match
|
|
2021
|
+
export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type AsyncResultMethods, type Awaitable, type DefectView, Do, DoAsync, Err, ErrAsync, type ErrMatcher, type ErrOf, type ErrView, type FailureView, GetError, type Matcher, NonExhaustiveError, type NotThenable, Ok, OkAsync, type OkOf, type OkView, P, type PatternMatcher, Result, type ResultMethods, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, type UniversalPattern, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, match };
|
|
2002
2022
|
//# sourceMappingURL=index.d.cts.map
|
package/dist/index.d.cts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.cts","names":[],"sources":["../src/defect.ts","../src/matcher.ts","../src/types.ts","../src/constructors.ts","../src/core.ts","../src/do.ts","../src/interop.ts","../src/facade.ts","../src/tagged.ts"],"mappings":";cAEM;;;;;;;;;;;;;;;KAgBM;YACA;WACD;;;;;;;;;;;;
|
|
1
|
+
{"version":3,"file":"index.d.cts","names":[],"sources":["../src/defect.ts","../src/matcher.ts","../src/types.ts","../src/constructors.ts","../src/core.ts","../src/do.ts","../src/interop.ts","../src/facade.ts","../src/tagged.ts"],"mappings":"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"}
|
package/dist/index.d.mts
CHANGED
|
@@ -127,17 +127,23 @@ type PinTooLate = {
|
|
|
127
127
|
*/
|
|
128
128
|
type Matcher<E, Remaining, O, Declared = Unset> = {
|
|
129
129
|
/**
|
|
130
|
-
* The catch-all arm: `.with(P._, handler)` / `.with(P.any, handler)
|
|
131
|
-
* **
|
|
132
|
-
*
|
|
133
|
-
*
|
|
134
|
-
*
|
|
135
|
-
*
|
|
130
|
+
* The catch-all arm: `.with(P._, handler)` / `.with(P.any, handler)` — the
|
|
131
|
+
* wildcard **escape hatch**, not the way to handle a concrete error union
|
|
132
|
+
* (name those cases; `@unthrown/oxlint`'s `no-catch-all-pattern`, in its
|
|
133
|
+
* `recommended` preset, flags the wildcard).
|
|
134
|
+
*
|
|
135
|
+
* It is a **state transition**, not a computation — it returns
|
|
136
|
+
* `Matcher<E, never, …>` with the remaining cases literally `never`, so the
|
|
137
|
+
* builder is provably exhaustive even when `E` is an unresolved type
|
|
138
|
+
* parameter (a lazily-deferred `Exclude<E, unknown>` would not resolve
|
|
139
|
+
* there). That is what makes it irreplaceable for a helper generic in `E`:
|
|
140
|
+
* it can terminate a match no arm list could (issue #145) — one of the two
|
|
141
|
+
* sanctioned uses (see {@link P}).
|
|
136
142
|
*/
|
|
137
143
|
with<O2>(pattern: UniversalPattern, handler: (value: Remaining) => BranchReturn<Declared, O2>): Matcher<E, never, O | O2, Declared>;
|
|
138
144
|
/**
|
|
139
145
|
* Add an arm: one or more patterns sharing a single handler (grouped
|
|
140
|
-
* patterns — `matcher.with(tag("A"), tag("B"), handler)`). The handler
|
|
146
|
+
* patterns — `matcher.with(P.tag("A"), P.tag("B"), handler)`). The handler
|
|
141
147
|
* receives the input narrowed to what the patterns match (computed against
|
|
142
148
|
* `Remaining`, so cases already handled by earlier arms are excluded); the
|
|
143
149
|
* matched cases are subtracted from `Remaining`.
|
|
@@ -208,8 +214,10 @@ declare class NonExhaustiveError extends Error {
|
|
|
208
214
|
* @remarks
|
|
209
215
|
* This is unthrown's own matcher (the former ts-pattern re-export): the same
|
|
210
216
|
* call-site shape, with exhaustiveness computed by plain `Exclude` over the
|
|
211
|
-
* builder's `Remaining` parameter.
|
|
212
|
-
* even over an
|
|
217
|
+
* builder's `Remaining` parameter. Name every case of the input union; the
|
|
218
|
+
* `P._` catch-all is the escape hatch, and is provably exhaustive even over an
|
|
219
|
+
* unresolved generic input — one of the two cases it is irreplaceable for (see
|
|
220
|
+
* {@link P}).
|
|
213
221
|
*
|
|
214
222
|
* @category Constructors
|
|
215
223
|
*/
|
|
@@ -217,9 +225,25 @@ declare function match<const E>(value: E): Matcher<E, E, never>;
|
|
|
217
225
|
/**
|
|
218
226
|
* The pattern namespace (unthrown's own; the former ts-pattern `P`):
|
|
219
227
|
*
|
|
220
|
-
* - `P._` / `P.any` — the universal catch-all
|
|
221
|
-
*
|
|
222
|
-
*
|
|
228
|
+
* - `P._` / `P.any` — the universal catch-all, and an **escape hatch** rather
|
|
229
|
+
* than the default: matching the error channel means naming its cases, so
|
|
230
|
+
* reach for this only where they cannot be named. Matches anything, and
|
|
231
|
+
* (because its phantom type is `unknown`) makes the builder provably
|
|
232
|
+
* exhaustive even when the matched input is an unresolved type parameter.
|
|
233
|
+
* Two situations are legitimate: a **helper generic in `E`**, where no arm
|
|
234
|
+
* list can prove exhaustiveness against an unresolved type parameter; and an
|
|
235
|
+
* **`E` that is a single type**, not a union of cases (a validator's issues
|
|
236
|
+
* array, say), where one arm _is_ the enumeration. `@unthrown/oxlint`'s
|
|
237
|
+
* `no-catch-all-pattern` (in its `recommended` preset) flags every other use;
|
|
238
|
+
* keep the deliberate ones behind a targeted `oxlint-disable` saying which of
|
|
239
|
+
* the two it is.
|
|
240
|
+
* - `P.tag<const Tag extends string>(value: Tag): { _tag: Tag }` — the
|
|
241
|
+
* `{ _tag: t }` object pattern, matching any value whose `_tag` equals `t` (a
|
|
242
|
+
* `TaggedError`, or any `_tag`-discriminated member) and narrowing the
|
|
243
|
+
* branch's parameter to that variant, payload included. The workhorse of the
|
|
244
|
+
* error channel: `matcher.with(P.tag("NotFound"), (e) => …)`. It composes like
|
|
245
|
+
* any other pattern — in a grouped arm
|
|
246
|
+
* (`.with(P.tag("A"), P.tag("B"), handler)`) and inside `P.union`.
|
|
223
247
|
* - `P.instanceOf(Cls)` — an `instanceof` check, narrowing to the class
|
|
224
248
|
* instance type (for union members that are not tagged, e.g. a third-party
|
|
225
249
|
* error class).
|
|
@@ -232,6 +256,9 @@ declare function match<const E>(value: E): Matcher<E, E, never>;
|
|
|
232
256
|
declare const P: Readonly<{
|
|
233
257
|
_: UniversalPattern;
|
|
234
258
|
any: UniversalPattern;
|
|
259
|
+
tag: <const Tag extends string>(value: Tag) => {
|
|
260
|
+
_tag: Tag;
|
|
261
|
+
};
|
|
235
262
|
instanceOf: <C extends abstract new (...args: never[]) => unknown>(cls: C) => PatternMatcher<InstanceType<C>>;
|
|
236
263
|
when: <G>(guard: (value: unknown) => value is G) => PatternMatcher<G>;
|
|
237
264
|
union: <const Pts extends readonly [unknown, ...unknown[]]>(...patterns: Pts) => PatternMatcher<MatchedOf<Pts[number]>>;
|
|
@@ -499,9 +526,15 @@ type ResultMethods<out T, out E> = {
|
|
|
499
526
|
* to a `Defect` and drops it from `E`. Runs only on `Err`; `Ok` and `Defect`
|
|
500
527
|
* pass through. A branch that throws also becomes a `Defect`.
|
|
501
528
|
*
|
|
502
|
-
*
|
|
503
|
-
*
|
|
504
|
-
*
|
|
529
|
+
* **Name every case.** Match on anything the matcher supports — `_tag`,
|
|
530
|
+
* `code`, structural shape, guards — and group the cases that share a handler
|
|
531
|
+
* with `.with(a, b, handler)`. `.with(P._, …)` is the wildcard **escape
|
|
532
|
+
* hatch**, not the default: it makes any match exhaustive, so it also absorbs
|
|
533
|
+
* every case `E` grows later. Two uses are sanctioned — a helper generic in
|
|
534
|
+
* `E`, where no arm list can prove exhaustiveness against an unresolved type
|
|
535
|
+
* parameter, and an `E` that is a single type rather than a union of cases
|
|
536
|
+
* (see {@link P} for both). `@unthrown/oxlint`'s `no-catch-all-pattern` (in
|
|
537
|
+
* its `recommended` preset) flags the rest.
|
|
505
538
|
*
|
|
506
539
|
* @typeParam M - the exhaustive builder the callback returns.
|
|
507
540
|
* @param f - builds the match over the error (returns the un-terminated builder).
|
|
@@ -542,7 +575,8 @@ type ResultMethods<out T, out E> = {
|
|
|
542
575
|
* @remarks
|
|
543
576
|
* The callback builds a match whose branches run side effects; their return
|
|
544
577
|
* values are ignored and the original `Err` flows through. Exhaustive like the
|
|
545
|
-
* transformers
|
|
578
|
+
* transformers, and like them it wants every case named — `.with(P._, …)`
|
|
579
|
+
* remains the wildcard escape hatch. If a branch throws, the
|
|
546
580
|
* result is a `Defect` whose cause is an `AggregateError` of `[thrown, original
|
|
547
581
|
* failure]` — observing a failure never destroys it. An **async branch is
|
|
548
582
|
* rejected at compile time** ({@link NotThenable} on the builder output):
|
|
@@ -642,8 +676,9 @@ type ResultMethods<out T, out E> = {
|
|
|
642
676
|
* exactly like the error combinators — which is why the key carries the same
|
|
643
677
|
* `…Cases` suffix. Chain `.with(pattern, handler)` and **return the
|
|
644
678
|
* un-terminated builder** — `match` calls `.exhaustive()` itself, so a missing
|
|
645
|
-
* case is a compile error at the call site (no `.exhaustive()` to forget).
|
|
646
|
-
* `.with(P._, …)`
|
|
679
|
+
* case is a compile error at the call site (no `.exhaustive()` to forget).
|
|
680
|
+
* Folding at the edge names every case too — `.with(P._, …)` is the wildcard
|
|
681
|
+
* escape hatch, not the default. Unlike the combinators the branches
|
|
647
682
|
* receive **no `defect` helper** — `match` is total elimination to a value,
|
|
648
683
|
* with no `Defect` output channel; the `defect` case handles a `Result` that
|
|
649
684
|
* already carries one. (A `Result` is also a discriminated union — for richer
|
|
@@ -856,7 +891,7 @@ type FailureView<E, T = never> = ErrView<E, T> | DefectView<T, E>;
|
|
|
856
891
|
*
|
|
857
892
|
* @example
|
|
858
893
|
* ```ts
|
|
859
|
-
* import { Ok, Err,
|
|
894
|
+
* import { Ok, Err, type Result } from "unthrown";
|
|
860
895
|
*
|
|
861
896
|
* function half(n: number): Result<number, "odd"> {
|
|
862
897
|
* return n % 2 === 0 ? Ok(n / 2) : Err("odd");
|
|
@@ -864,7 +899,8 @@ type FailureView<E, T = never> = ErrView<E, T> | DefectView<T, E>;
|
|
|
864
899
|
*
|
|
865
900
|
* const message = half(10).match({
|
|
866
901
|
* ok: (n) => `got ${n}`,
|
|
867
|
-
*
|
|
902
|
+
* // every case of `E` named — here the one literal it holds
|
|
903
|
+
* errCases: (matcher) => matcher.with("odd", () => "failed: odd"),
|
|
868
904
|
* defect: (cause) => `bug: ${String(cause)}`,
|
|
869
905
|
* });
|
|
870
906
|
* ```
|
|
@@ -1396,7 +1432,7 @@ declare class GetError<E = unknown> extends Error {
|
|
|
1396
1432
|
*
|
|
1397
1433
|
* @example
|
|
1398
1434
|
* ```ts
|
|
1399
|
-
* import { isResult, Ok } from "unthrown";
|
|
1435
|
+
* import { isResult, Ok, P } from "unthrown";
|
|
1400
1436
|
*
|
|
1401
1437
|
* isResult(Ok(1)); // => true
|
|
1402
1438
|
* isResult({ tag: "Ok" }); // => false (look-alike, wrong prototype)
|
|
@@ -1404,6 +1440,9 @@ declare class GetError<E = unknown> extends Error {
|
|
|
1404
1440
|
*
|
|
1405
1441
|
* const x: unknown = Ok(1);
|
|
1406
1442
|
* if (isResult(x))
|
|
1443
|
+
* // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
|
|
1444
|
+
* // so the `P._` escape hatch is the only arm that can terminate the match:
|
|
1445
|
+
* // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
|
|
1407
1446
|
* x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
|
|
1408
1447
|
* ```
|
|
1409
1448
|
*
|
|
@@ -1934,10 +1973,14 @@ type TaggedErrorConstructor<Tag extends string> = {
|
|
|
1934
1973
|
* so a payload `cause` (e.g. a wrapped driver error) is a legitimate,
|
|
1935
1974
|
* *narrowing* structured field.
|
|
1936
1975
|
*
|
|
1937
|
-
*
|
|
1938
|
-
*
|
|
1939
|
-
*
|
|
1940
|
-
*
|
|
1976
|
+
* The matching half of the convention is `P.tag(t)` — the pattern constructor on
|
|
1977
|
+
* the `P` namespace, which builds the `{ _tag: t }` pattern this factory's `_tag`
|
|
1978
|
+
* is selected by (there is no standalone `tag` export).
|
|
1979
|
+
*
|
|
1980
|
+
* `_tag` is the discriminant matched by `P.tag` in the error combinators
|
|
1981
|
+
* (`result.mapErrCases((matcher) => matcher.with(P.tag("NotFound"), …))`) and in
|
|
1982
|
+
* `match`'s `errCases` handler; `Error.name` is the human-facing label in stack
|
|
1983
|
+
* traces and logs. By default they coincide, but
|
|
1941
1984
|
* they can be **decoupled** with `options.name` — so a tag can be namespaced for
|
|
1942
1985
|
* collision-safety (`"@my-lib/RetryableError"`) without that slash-prefixed
|
|
1943
1986
|
* string leaking into `Error.name`:
|
|
@@ -1974,29 +2017,6 @@ type TaggedErrorConstructor<Tag extends string> = {
|
|
|
1974
2017
|
declare function TaggedError<Tag extends string>(tag: Tag, options?: {
|
|
1975
2018
|
readonly name?: string;
|
|
1976
2019
|
}): TaggedErrorConstructor<Tag>;
|
|
1977
|
-
/**
|
|
1978
|
-
* A matcher pattern matching any value whose `_tag` equals `value` — a
|
|
1979
|
-
* {@link TaggedError}, or any discriminated member. Equivalent to the object
|
|
1980
|
-
* pattern `{ _tag: value }`, but reads better inside an error-matching
|
|
1981
|
-
* combinator and narrows to the matching variant, payload included.
|
|
1982
|
-
*
|
|
1983
|
-
* @typeParam Tag - the string literal tag to match.
|
|
1984
|
-
* @param value - the `_tag` to match.
|
|
1985
|
-
*
|
|
1986
|
-
* @category Tagged errors
|
|
1987
|
-
*
|
|
1988
|
-
* @example
|
|
1989
|
-
* ```ts
|
|
1990
|
-
* result.mapErrCases((matcher) =>
|
|
1991
|
-
* matcher
|
|
1992
|
-
* .with(tag("NotFound"), () => new NotFoundException())
|
|
1993
|
-
* .with(tag("Conflict"), (e) => new ConflictException(e.key)),
|
|
1994
|
-
* );
|
|
1995
|
-
* ```
|
|
1996
|
-
*/
|
|
1997
|
-
declare function tag<const Tag extends string>(value: Tag): {
|
|
1998
|
-
_tag: Tag;
|
|
1999
|
-
};
|
|
2000
2020
|
//#endregion
|
|
2001
|
-
export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type AsyncResultMethods, type Awaitable, type DefectView, Do, DoAsync, Err, ErrAsync, type ErrMatcher, type ErrOf, type ErrView, type FailureView, GetError, type Matcher, NonExhaustiveError, type NotThenable, Ok, OkAsync, type OkOf, type OkView, P, type PatternMatcher, Result, type ResultMethods, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, type UniversalPattern, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, match
|
|
2021
|
+
export { type AsyncErrOf, type AsyncOkOf, AsyncResult, type AsyncResultMethods, type Awaitable, type DefectView, Do, DoAsync, Err, ErrAsync, type ErrMatcher, type ErrOf, type ErrView, type FailureView, GetError, type Matcher, NonExhaustiveError, type NotThenable, Ok, OkAsync, type OkOf, type OkView, P, type PatternMatcher, Result, type ResultMethods, TaggedError, type TaggedErrorConstructor, type TaggedErrorInstance, type UniversalPattern, all, allAsync, allFromDict, allFromDictAsync, fromNullable, fromPromise, fromSafePromise, fromSafeThrowable, fromThrowable, isDefect, isErr, isOk, isResult, match };
|
|
2002
2022
|
//# sourceMappingURL=index.d.mts.map
|