unthrown 5.11.0 → 5.12.1

package/dist/index.cjs

@@ -1206,12 +1206,15 @@ function DoAsync() {
 *
 * @remarks
 * `null` and `undefined` map to `Err(onAbsent())`; any other value (including
-* falsy ones like `0`, `""`, `false`) maps to `Ok`.
+* falsy ones like `0`, `""`, `false`) maps to `Ok`. A throw inside `onAbsent`
+* becomes a `Defect`. Its return must be synchronous ({@link NotThenable});
+* a thenable slipped past the types becomes a `Defect`, with an orphaned
+* Promise silenced and a lazy thenable left unstarted.
 *
 * @typeParam T - the (nullable) value type.
 * @typeParam E - the error produced when the value is absent.
 * @param value - the possibly-absent value.
-* @param onAbsent - lazily produces the error for the absent case.
+* @param onAbsent - synchronously and lazily produces the error for the absent case.
 *
 * @category Interop
 *
@@ -1226,7 +1229,13 @@ function DoAsync() {
 * ```
 */
 function fromNullable(value, onAbsent) {
-	return value === null || value === void 0 ? Err(onAbsent()) : Ok(value);
+	if (value !== null && value !== void 0) return Ok(value);
+	try {
+		const error = onAbsent();
+		return isThenable(error) ? thenableReturnDefect(error, "unthrown: fromNullable's onAbsent must be synchronous — it returned a thenable") : Err(error);
+	} catch (cause) {
+		return defectRes(cause);
+	}
 }
 /**
 * Wrap a throwing synchronous function so it returns a {@link Result} instead of

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
@@ -504,12 +532,15 @@ export declare function DoAsync(): AsyncResult<{}, never>;
  *
  * @remarks
  * `null` and `undefined` map to `Err(onAbsent())`; any other value (including
- * falsy ones like `0`, `""`, `false`) maps to `Ok`.
+ * falsy ones like `0`, `""`, `false`) maps to `Ok`. A throw inside `onAbsent`
+ * becomes a `Defect`. Its return must be synchronous ({@link NotThenable});
+ * a thenable slipped past the types becomes a `Defect`, with an orphaned
+ * Promise silenced and a lazy thenable left unstarted.
  *
  * @typeParam T - the (nullable) value type.
  * @typeParam E - the error produced when the value is absent.
  * @param value - the possibly-absent value.
- * @param onAbsent - lazily produces the error for the absent case.
+ * @param onAbsent - synchronously and lazily produces the error for the absent case.
  *
  * @category Interop
  *
@@ -523,7 +554,7 @@ export declare function DoAsync(): AsyncResult<{}, never>;
  * fromNullable(0, () => "absent").getOr(-1); // => 0 (falsy but present)
  * ```
  */
-export declare function fromNullable<T, E>(value: T | null | undefined, onAbsent: () => E): Result<NonNullable<T>, E>;
+export declare function fromNullable<T, E>(value: T | null | undefined, onAbsent: () => E & NotThenable<E>): Result<NonNullable<T>, E>;
 /**
  * Wrap a throwing synchronous function so it returns a {@link Result} instead of
  * throwing.

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
@@ -504,12 +532,15 @@ export declare function DoAsync(): AsyncResult<{}, never>;
  *
  * @remarks
  * `null` and `undefined` map to `Err(onAbsent())`; any other value (including
- * falsy ones like `0`, `""`, `false`) maps to `Ok`.
+ * falsy ones like `0`, `""`, `false`) maps to `Ok`. A throw inside `onAbsent`
+ * becomes a `Defect`. Its return must be synchronous ({@link NotThenable});
+ * a thenable slipped past the types becomes a `Defect`, with an orphaned
+ * Promise silenced and a lazy thenable left unstarted.
  *
  * @typeParam T - the (nullable) value type.
  * @typeParam E - the error produced when the value is absent.
  * @param value - the possibly-absent value.
- * @param onAbsent - lazily produces the error for the absent case.
+ * @param onAbsent - synchronously and lazily produces the error for the absent case.
  *
  * @category Interop
  *
@@ -523,7 +554,7 @@ export declare function DoAsync(): AsyncResult<{}, never>;
  * fromNullable(0, () => "absent").getOr(-1); // => 0 (falsy but present)
  * ```
  */
-export declare function fromNullable<T, E>(value: T | null | undefined, onAbsent: () => E): Result<NonNullable<T>, E>;
+export declare function fromNullable<T, E>(value: T | null | undefined, onAbsent: () => E & NotThenable<E>): Result<NonNullable<T>, E>;
 /**
  * Wrap a throwing synchronous function so it returns a {@link Result} instead of
  * throwing.

package/dist/index.mjs

@@ -1205,12 +1205,15 @@ function DoAsync() {
 *
 * @remarks
 * `null` and `undefined` map to `Err(onAbsent())`; any other value (including
-* falsy ones like `0`, `""`, `false`) maps to `Ok`.
+* falsy ones like `0`, `""`, `false`) maps to `Ok`. A throw inside `onAbsent`
+* becomes a `Defect`. Its return must be synchronous ({@link NotThenable});
+* a thenable slipped past the types becomes a `Defect`, with an orphaned
+* Promise silenced and a lazy thenable left unstarted.
 *
 * @typeParam T - the (nullable) value type.
 * @typeParam E - the error produced when the value is absent.
 * @param value - the possibly-absent value.
-* @param onAbsent - lazily produces the error for the absent case.
+* @param onAbsent - synchronously and lazily produces the error for the absent case.
 *
 * @category Interop
 *
@@ -1225,7 +1228,13 @@ function DoAsync() {
 * ```
 */
 function fromNullable(value, onAbsent) {
-	return value === null || value === void 0 ? Err(onAbsent()) : Ok(value);
+	if (value !== null && value !== void 0) return Ok(value);
+	try {
+		const error = onAbsent();
+		return isThenable(error) ? thenableReturnDefect(error, "unthrown: fromNullable's onAbsent must be synchronous — it returned a thenable") : Err(error);
+	} catch (cause) {
+		return defectRes(cause);
+	}
 }
 /**
 * Wrap a throwing synchronous function so it returns a {@link Result} instead of

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unthrown",
-  "version": "5.11.0",
+  "version": "5.12.1",
   "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"