unthrown 5.11.0 → 5.12.0

package/dist/index.d.cts

@@ -63,6 +63,32 @@ type UniversalPattern = PatternMatcher<unknown> & {
  * @internal
  */
 type MatchedOf<Pt> = Pt extends PatternMatcher<infer M> ? M : Pt extends object ? { [K in keyof Pt]: MatchedOf<Pt[K]>; } : Pt;
+/** Whether a value's type describes multiple alternatives, not one literal. */
+type IsUnion<T, Whole = T> = T extends Whole ? ([Whole] extends [T] ? false : true) : never;
+/**
+ * What a pattern is guaranteed to cover, rather than merely able to match.
+ *
+ * A value pattern is an equality test, so it discharges a case only when its
+ * type is a **unit type** — one inhabitant: a string / number / bigint /
+ * boolean literal, `null`, `undefined`, a `unique symbol` — or a plain object
+ * of such fields, recursively (so a variable inferred as `{ _tag: string }`
+ * cannot make an entire tagged union exhaustive). Everything else covers
+ * nothing: a widened `string`, a template literal (`` `E_${string}` `` is as
+ * wide as `string`), a union (one runtime value however many alternatives its
+ * type lists — a union of `P.*` patterns included, which is why the union test
+ * runs before the predicate one), an array or a function (compared by identity
+ * at runtime). Keep `MatchedOf` for handler narrowing; subtract only this
+ * coverage. Branded predicate patterns still cover their declared type: unlike
+ * a value, they test the whole type. An allow-list rather than a deny-list of
+ * wide types, so a shape it did not anticipate fails closed. One gap is
+ * accepted: a class instance is structurally an object type, so it recurses
+ * like a plain object while the runtime compares it by identity — pinned in
+ * `types.test-d.ts`.
+ *
+ * @internal
+ */
+type CoveredBy<Pt> = true extends IsUnion<Pt> ? never : [Pt] extends [PatternMatcher<infer M>] ? M : Pt extends string ? {} extends Record<Pt, never> ? never : Pt : Pt extends number ? number extends Pt ? never : Pt : Pt extends bigint ? bigint extends Pt ? never : Pt : Pt extends symbol ? symbol extends Pt ? never : Pt : Pt extends boolean | null | undefined ? Pt : Pt extends readonly unknown[] | ((...args: never) => unknown) ? never : Pt extends object ? { [K in keyof Pt]: CoveredBy<Pt[K]>; } : never;
+type CoveredByPatterns<Pts extends readonly unknown[]> = { [I in keyof Pts]: CoveredBy<Pts[I]>; }[number];
 /**
  * Reject a **keyless object pattern** (`{}`) where it is written.
  *
@@ -173,9 +199,11 @@ type Matcher<E, Remaining, O, Declared = Unset> = {
    * patterns — `matcher.with(P.tag("A"), P.tag("B"), handler)`). The handler
    * receives the input narrowed to what the patterns match (computed against
    * `Remaining`, so cases already handled by earlier arms are excluded); the
-   * matched cases are subtracted from `Remaining`.
+   * guaranteed covered cases are subtracted from `Remaining`. A widened value
+   * pattern (e.g. `{ _tag: string }`) can match but proves no coverage: use
+   * literal patterns / `P.tag` to discharge the remaining cases.
    */
-  with<const Pts extends readonly [unknown, ...unknown[]], O2>(...args: [...patterns: { [I in keyof Pts]: NoEmptyPattern<Pts[I]>; }, handler: (value: Extract<Remaining, MatchedOf<Pts[number]>>) => BranchReturn<Declared, O2>]): Matcher<E, Exclude<Remaining, MatchedOf<Pts[number]>>, O | O2, Declared>;
+  with<const Pts extends readonly [unknown, ...unknown[]], O2>(...args: [...patterns: { [I in keyof Pts]: NoEmptyPattern<Pts[I]>; }, handler: (value: Extract<Remaining, MatchedOf<Pts[number]>>) => BranchReturn<Declared, O2>]): Matcher<E, Exclude<Remaining, CoveredByPatterns<Pts>>, O | O2, Declared>;
   /**
    * Declare the match's output type up front: every subsequent branch handler
    * is checked against `R`, and the match evaluates to `R` instead of the

package/dist/index.d.mts

@@ -63,6 +63,32 @@ type UniversalPattern = PatternMatcher<unknown> & {
  * @internal
  */
 type MatchedOf<Pt> = Pt extends PatternMatcher<infer M> ? M : Pt extends object ? { [K in keyof Pt]: MatchedOf<Pt[K]>; } : Pt;
+/** Whether a value's type describes multiple alternatives, not one literal. */
+type IsUnion<T, Whole = T> = T extends Whole ? ([Whole] extends [T] ? false : true) : never;
+/**
+ * What a pattern is guaranteed to cover, rather than merely able to match.
+ *
+ * A value pattern is an equality test, so it discharges a case only when its
+ * type is a **unit type** — one inhabitant: a string / number / bigint /
+ * boolean literal, `null`, `undefined`, a `unique symbol` — or a plain object
+ * of such fields, recursively (so a variable inferred as `{ _tag: string }`
+ * cannot make an entire tagged union exhaustive). Everything else covers
+ * nothing: a widened `string`, a template literal (`` `E_${string}` `` is as
+ * wide as `string`), a union (one runtime value however many alternatives its
+ * type lists — a union of `P.*` patterns included, which is why the union test
+ * runs before the predicate one), an array or a function (compared by identity
+ * at runtime). Keep `MatchedOf` for handler narrowing; subtract only this
+ * coverage. Branded predicate patterns still cover their declared type: unlike
+ * a value, they test the whole type. An allow-list rather than a deny-list of
+ * wide types, so a shape it did not anticipate fails closed. One gap is
+ * accepted: a class instance is structurally an object type, so it recurses
+ * like a plain object while the runtime compares it by identity — pinned in
+ * `types.test-d.ts`.
+ *
+ * @internal
+ */
+type CoveredBy<Pt> = true extends IsUnion<Pt> ? never : [Pt] extends [PatternMatcher<infer M>] ? M : Pt extends string ? {} extends Record<Pt, never> ? never : Pt : Pt extends number ? number extends Pt ? never : Pt : Pt extends bigint ? bigint extends Pt ? never : Pt : Pt extends symbol ? symbol extends Pt ? never : Pt : Pt extends boolean | null | undefined ? Pt : Pt extends readonly unknown[] | ((...args: never) => unknown) ? never : Pt extends object ? { [K in keyof Pt]: CoveredBy<Pt[K]>; } : never;
+type CoveredByPatterns<Pts extends readonly unknown[]> = { [I in keyof Pts]: CoveredBy<Pts[I]>; }[number];
 /**
  * Reject a **keyless object pattern** (`{}`) where it is written.
  *
@@ -173,9 +199,11 @@ type Matcher<E, Remaining, O, Declared = Unset> = {
    * patterns — `matcher.with(P.tag("A"), P.tag("B"), handler)`). The handler
    * receives the input narrowed to what the patterns match (computed against
    * `Remaining`, so cases already handled by earlier arms are excluded); the
-   * matched cases are subtracted from `Remaining`.
+   * guaranteed covered cases are subtracted from `Remaining`. A widened value
+   * pattern (e.g. `{ _tag: string }`) can match but proves no coverage: use
+   * literal patterns / `P.tag` to discharge the remaining cases.
    */
-  with<const Pts extends readonly [unknown, ...unknown[]], O2>(...args: [...patterns: { [I in keyof Pts]: NoEmptyPattern<Pts[I]>; }, handler: (value: Extract<Remaining, MatchedOf<Pts[number]>>) => BranchReturn<Declared, O2>]): Matcher<E, Exclude<Remaining, MatchedOf<Pts[number]>>, O | O2, Declared>;
+  with<const Pts extends readonly [unknown, ...unknown[]], O2>(...args: [...patterns: { [I in keyof Pts]: NoEmptyPattern<Pts[I]>; }, handler: (value: Extract<Remaining, MatchedOf<Pts[number]>>) => BranchReturn<Declared, O2>]): Matcher<E, Exclude<Remaining, CoveredByPatterns<Pts>>, O | O2, Declared>;
   /**
    * Declare the match's output type up front: every subsequent branch handler
    * is checked against `R`, and the match evaluates to `R` instead of the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unthrown",
-  "version": "5.11.0",
+  "version": "5.12.0",
   "description": "Explicit errors as values, with a separate defect (panic) channel",
   "keywords": [
     "defect",
@@ -47,11 +47,11 @@
   },
   "devDependencies": {
     "@btravstack/tsconfig": "0.4.0",
-    "@types/node": "26.6.2",
-    "@vitest/coverage-v8": "5.0.1",
+    "@types/node": "26.6.3",
+    "@vitest/coverage-v8": "5.0.2",
     "tsdown": "0.23.0",
     "typescript": "7.0.2",
-    "vitest": "5.0.1"
+    "vitest": "5.0.2"
   },
   "engines": {
     "node": ">=20"