unthrown 5.0.0-beta.1 → 5.0.0-beta.11

package/README.md

@@ -10,6 +10,9 @@
 pnpm add unthrown
 ```
 
+No peer dependencies — the exhaustive error matcher is built-in and exported as
+`match` / `P`.
+
 ```ts
 import { fromPromise, P, TaggedError } from "unthrown";
 
@@ -22,23 +25,29 @@ const user = fromPromise(fetchUser(id), (cause, defect) =>
 
 const status = await user.match({
   ok: () => 200,
-  err: (matcher) => matcher.with(P._, () => 404), // `err` takes the exhaustive matcher
+  // `errCases` takes the exhaustive matcher — every case of E named:
+  errCases: (matcher) => matcher.with(P.tag("NotFound"), () => 404),
   defect: () => 500,
 });
 ```
 
 - **Errors as values** via `Result<T, E>` / `AsyncResult<T, E>`.
 - **A separate defect channel** for the unexpected — invisible to the type,
-  observable only via `match` / `recoverDefect`.
+  observable only via `match` / `recoverDefect` and the `tapDefect` /
+  `tapFailure` observers.
 - **Qualification at every boundary** — `fromPromise` / `fromThrowable` force you
   to triage each failure into a modeled error or a defect.
-- **Tagged errors** — `TaggedError(tag)` + `tag(t)`, folded exhaustively through
-  `match`'s ts-pattern error matcher.
-- One tiny runtime dependency (`ts-pattern`), ESM-first, dual CJS/ESM.
+- **Tagged errors** — `TaggedError(tag)` + `P.tag(t)`, folded exhaustively through
+  `match`'s built-in error matcher.
+- **Zero runtime dependencies** (the matcher is built-in), ESM-first, dual
+  CJS/ESM.
 
 See the [full documentation](https://btravstack.github.io/unthrown/) for the guide
 and complete API.
 
+**Upgrading from 4.x?** See
+[Upgrade from 4.x to 5.0](https://btravstack.github.io/unthrown/how-to/upgrade-to-v5).
+
 ## License
 
 [MIT](https://github.com/btravstack/unthrown/blob/main/LICENSE) © Benoit TRAVERS

package/dist/index.cjs

@@ -1,5 +1,179 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-let ts_pattern = require("ts-pattern");
+//#region src/matcher.ts
+/**
+* Cross-copy brand for `P.*` pattern objects: `Symbol.for` yields the same
+* symbol in every copy of the library (dual CJS/ESM, duplicated install,
+* another realm), so a pattern built by one copy is recognised by another —
+* the same rationale as `isResult`'s prototype brand.
+*
+* @internal
+*/
+const PATTERN_BRAND = Symbol.for("unthrown.matcher.pattern");
+/**
+* Thrown by `.run()` / `.exhaustive()` when no arm matched the value. For
+* well-typed callers the match is exhaustive by construction, so this is only
+* reachable by a value that slipped past the types (a widened cast, a raw-JS
+* caller); inside the error combinators the throw-to-defect net converts it to
+* a `Defect`, and at the `match` edge it surfaces (a genuinely unmodeled value
+* is a bug).
+*
+* @category Errors
+*/
+var NonExhaustiveError = class extends Error {
+	/** The value no arm matched. */
+	input;
+	constructor(input) {
+		let printed;
+		try {
+			printed = JSON.stringify(input);
+		} catch {
+			printed = String(input);
+		}
+		super(`unthrown: no pattern matched the value ${printed}`);
+		this.name = "NonExhaustiveError";
+		this.input = input;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+/**
+* Is `x` a *plain* object (prototype `Object.prototype` or `null`) — an object
+* literal, the only object shape that acts as a structural pattern?
+*
+* @internal
+*/
+function isPlainObject(x) {
+	const proto = Object.getPrototypeOf(x);
+	return proto === Object.prototype || proto === null;
+}
+/**
+* Runtime test: does `pattern` match `value`? A branded `P.*` pattern applies
+* its predicate; a **plain-object** pattern (an object literal, e.g. the
+* `{ _tag }` produced by `P.tag()`) matches when every key matches recursively
+* (extra keys on the value are ignored — matching is structural); anything
+* else — primitives, but also class instances, arrays, and foreign pattern
+* objects (e.g. a real ts-pattern matcher, whose keys are symbols) — is
+* compared with `Object.is`. Restricting structural matching to plain objects
+* is load-bearing: a keyless non-plain object (`new Date()`, `new Error()`, a
+* symbol-keyed foreign pattern) would otherwise vacuously match *every* object
+* via an empty `Object.entries`.
+*
+* @internal
+*/
+function matches(pattern, value) {
+	if (typeof pattern === "object" && pattern !== null) {
+		const predicate = pattern[PATTERN_BRAND];
+		if (typeof predicate === "function") return predicate(value);
+		if (!isPlainObject(pattern) || Object.getOwnPropertySymbols(pattern).length > 0) return Object.is(pattern, value);
+		if (typeof value !== "object" || value === null) return false;
+		return Object.entries(pattern).every(([key, sub]) => matches(sub, value[key]));
+	}
+	return Object.is(pattern, value);
+}
+/**
+* The runtime builder: first matching arm wins; later arms are skipped once a
+* result is captured. `exhaustive` is a *method* at runtime (the conditional
+* type gates its callability per instantiation).
+*
+* @internal
+*/
+var MatcherImpl = class {
+	#value;
+	#matched = false;
+	#result;
+	constructor(value) {
+		this.#value = value;
+	}
+	with(...args) {
+		if (this.#matched) return this;
+		const handler = args[args.length - 1];
+		for (let i = 0; i < args.length - 1; i++) if (matches(args[i], this.#value)) {
+			this.#matched = true;
+			this.#result = handler(this.#value);
+			return this;
+		}
+		return this;
+	}
+	/**
+	* Type-level only — pinning the output type has no runtime meaning, so the
+	* builder is returned unchanged (as ts-pattern does).
+	*/
+	returnType() {
+		return this;
+	}
+	exhaustive() {
+		if (this.#matched) return this.#result;
+		throw new NonExhaustiveError(this.#value);
+	}
+	run() {
+		return this.exhaustive();
+	}
+};
+Object.freeze(MatcherImpl.prototype);
+/**
+* Begin a match over `value`. Chain `.with(pattern, …patterns, handler)` arms;
+* terminate with `.exhaustive()` — or return the un-terminated builder to an
+* unthrown error combinator / `match({ errCases })`, which runs it for you.
+*
+* @remarks
+* This is unthrown's own matcher (the former ts-pattern re-export): the same
+* call-site shape, with exhaustiveness computed by plain `Exclude` over the
+* builder's `Remaining` parameter. Name every case of the input union; the
+* `P._` catch-all is the escape hatch, and is provably exhaustive even over an
+* unresolved generic input — one of the two cases it is irreplaceable for (see
+* {@link P}).
+*
+* @category Constructors
+*/
+function match(value) {
+	return new MatcherImpl(value);
+}
+/** @internal */
+function pattern(predicate) {
+	return Object.freeze({ [PATTERN_BRAND]: predicate });
+}
+const universal = pattern(() => true);
+/**
+* The pattern namespace (unthrown's own; the former ts-pattern `P`):
+*
+* - `P._` / `P.any` — the universal catch-all, and an **escape hatch** rather
+*   than the default: matching the error channel means naming its cases, so
+*   reach for this only where they cannot be named. Matches anything, and
+*   (because its phantom type is `unknown`) makes the builder provably
+*   exhaustive even when the matched input is an unresolved type parameter.
+*   Two situations are legitimate: a **helper generic in `E`**, where no arm
+*   list can prove exhaustiveness against an unresolved type parameter; and an
+*   **`E` that is a single type**, not a union of cases (a validator's issues
+*   array, say), where one arm _is_ the enumeration. `@unthrown/oxlint`'s
+*   `no-catch-all-pattern` (in its `recommended` preset) flags every other use;
+*   keep the deliberate ones behind a targeted `oxlint-disable` saying which of
+*   the two it is.
+* - `P.tag<const Tag extends string>(value: Tag): { _tag: Tag }` — the
+*   `{ _tag: t }` object pattern, matching any value whose `_tag` equals `t` (a
+*   `TaggedError`, or any `_tag`-discriminated member) and narrowing the
+*   branch's parameter to that variant, payload included. The workhorse of the
+*   error channel: `matcher.with(P.tag("NotFound"), (e) => …)`. It composes like
+*   any other pattern — in a grouped arm
+*   (`.with(P.tag("A"), P.tag("B"), handler)`) and inside `P.union`.
+* - `P.instanceOf(Cls)` — an `instanceof` check, narrowing to the class
+*   instance type (for union members that are not tagged, e.g. a third-party
+*   error class).
+* - `P.when(guard)` — an arbitrary type-guard predicate.
+* - `P.union(…patterns)` — matches when any sub-pattern matches.
+* - `P.string` / `P.number` — primitive-type wildcards.
+*
+* @category Constructors
+*/
+const P = Object.freeze({
+	_: universal,
+	any: universal,
+	tag: (value) => ({ _tag: value }),
+	instanceOf: (cls) => pattern((value) => value instanceof cls),
+	when: (guard) => pattern(guard),
+	union: (...patterns) => pattern((value) => patterns.some((sub) => matches(sub, value))),
+	string: pattern((value) => typeof value === "string"),
+	number: pattern((value) => typeof value === "number")
+});
+//#endregion
 //#region src/defect.ts
 const DEFECT = Symbol("unthrown/Defect");
 /**
@@ -152,7 +326,7 @@ var Res = class {
 			return defectRes(cause);
 		}
 	}
-	mapErr(f) {
+	mapErrCases(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
 			const out = runMatch(f, this.error);
@@ -162,7 +336,7 @@ var Res = class {
 			return defectRes(cause);
 		}
 	}
-	flatMapErr(f) {
+	flatMapErrCases(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
 			const out = runMatch(f, this.error);
@@ -173,7 +347,7 @@ var Res = class {
 			return defectRes(cause);
 		}
 	}
-	recoverErr(f) {
+	recoverErrCases(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
 			const out = runMatch(f, this.error);
@@ -183,19 +357,21 @@ var Res = class {
 			return defectRes(cause);
 		}
 	}
-	tapErr(f) {
+	tapErrCases(f) {
 		if (this.tag !== "Err") return this;
 		try {
-			runMatch(f, this.error);
+			const out = runMatch(f, this.error);
+			if (isDefectMarker(out)) return observerThrowToDefect(out.cause, this.error);
 			return this;
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.error);
 		}
 	}
-	flatTapErr(f) {
+	flatTapErrCases(f) {
 		if (this.tag !== "Err") return this;
 		try {
 			const r = runMatch(f, this.error);
+			if (isDefectMarker(r)) return observerThrowToDefect(r.cause, this.error);
 			if (!isResult(r)) return nonResultCallbackDefect();
 			return r.tag === "Ok" ? this : passThrough(r);
 		} catch (cause) {
@@ -232,7 +408,7 @@ var Res = class {
 	match(cases) {
 		switch (this.tag) {
 			case "Ok": return cases.ok(this.value);
-			case "Err": return cases.err((0, ts_pattern.match)(this.error)).run();
+			case "Err": return cases.errCases(match(this.error)).run();
 			case "Defect": return cases.defect(this.cause);
 		}
 	}
@@ -350,14 +526,18 @@ function defectRes(cause) {
 *
 * @example
 * ```ts
-* import { isResult, Ok } from "unthrown";
+* import { isResult, Ok, P } from "unthrown";
 *
 * isResult(Ok(1)); // => true
 * isResult({ tag: "Ok" }); // => false (look-alike, wrong prototype)
 * isResult(Ok(1).toAsync()); // => false (an AsyncResult is not a Result)
 *
 * const x: unknown = Ok(1);
-* if (isResult(x)) x.match({ ok: () => 1, err: () => 0, defect: () => -1 });
+* if (isResult(x))
+*   // `E` is `unknown` here — an untyped boundary has no cases to enumerate,
+*   // so the `P._` escape hatch is the only arm that can terminate the match:
+*   // oxlint-disable-next-line unthrown/no-catch-all-pattern -- untyped boundary: `E` is `unknown`
+*   x.match({ ok: () => 1, errCases: (m) => m.with(P._, () => 0), defect: () => -1 });
 * ```
 *
 * @category Guards
@@ -407,19 +587,24 @@ function nonResultCallbackDefect() {
 * @internal
 */
 function runMatch(f, error) {
-	return f((0, ts_pattern.match)(error), defect).run();
+	return f(match(error), defect).run();
 }
 /**
-* A throw inside a *failure observer* (`tapErr` / `tapDefect` / `flatTapErr`)
-* must not destroy the failure being observed — that is the exact place (e.g. a
-* failing error-logger) where losing the underlying failure hurts most. The
-* resulting Defect aggregates both: `errors[0]` is the observer's throw,
-* `errors[1]` the original failure.
+* A throw inside a *failure observer* (`tapErrCases` / `tapDefect` /
+* `tapFailure` / `flatTapErrCases`) must not destroy the failure being observed
+* — that is the exact place (e.g. a failing error-logger) where losing the
+* underlying failure hurts most. The resulting Defect aggregates both:
+* `errors[0]` is the observer's own failure, `errors[1]` the original failure.
+*
+* An observer branch returning the injected `defect(cause)` marker
+* (`tapErrCases` / `flatTapErrCases`) takes the same route: it is the
+* lint-clean, expression-position form of a `throw` (Thesis #5), so it must not
+* behave differently from one.
 *
 * @internal
 */
 function observerThrowToDefect(thrown, original) {
-	return defectRes(new AggregateError([thrown, original], "unthrown: a failure-observer callback threw; errors[0] is the callback's throw, errors[1] the original failure"));
+	return defectRes(new AggregateError([thrown, original], "unthrown: a failure-observer callback failed; errors[0] is the callback's failure (a throw, or a deliberate defect), errors[1] the original failure"));
 }
 /**
 * Validate that a `bind`/`let` scope is a real (non-null) object before merging a
@@ -547,7 +732,7 @@ var AsyncRes = class AsyncRes {
 			}
 		}));
 	}
-	mapErr(f) {
+	mapErrCases(f) {
 		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
@@ -559,7 +744,7 @@ var AsyncRes = class AsyncRes {
 			}
 		}));
 	}
-	flatMapErr(f) {
+	flatMapErrCases(f) {
 		return new AsyncRes(this.#promise.then(async (r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
@@ -573,7 +758,7 @@ var AsyncRes = class AsyncRes {
 			}
 		}));
 	}
-	recoverErr(f) {
+	recoverErrCases(f) {
 		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
@@ -585,22 +770,25 @@ var AsyncRes = class AsyncRes {
 			}
 		}));
 	}
-	tapErr(f) {
+	tapErrCases(f) {
 		return new AsyncRes(this.#promise.then((r) => {
 			if (r.tag !== "Err") return r;
 			try {
-				runMatch(f, r.error);
+				const out = runMatch(f, r.error);
+				if (isDefectMarker(out)) return observerThrowToDefect(out.cause, r.error);
 				return r;
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.error);
 			}
 		}));
 	}
-	flatTapErr(f) {
+	flatTapErrCases(f) {
 		return new AsyncRes(this.#promise.then(async (r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
-				const inner = await runMatch(f, r.error);
+				const out = runMatch(f, r.error);
+				if (isDefectMarker(out)) return observerThrowToDefect(out.cause, r.error);
+				const inner = await out;
 				if (!isResult(inner)) return nonResultCallbackDefect();
 				return inner.tag === "Ok" ? passThrough(r) : passThrough(inner);
 			} catch (cause) {
@@ -1006,6 +1194,11 @@ function fromSafeThrowable(fn) {
 * @param promise - the promise, or a thunk returning one.
 * @param qualify - triages a rejection `cause` into a modeled `E`, or marks it
 * unmodeled by returning `defect(cause)` (the helper passed as its second arg).
+* @param _guard - compile-time only; never pass it. The phantom rest-tuple that
+* enforces "qualify is synchronous": an `async` qualify makes this demand an
+* impossible extra argument (whose type spells out the error), while a
+* synchronous one leaves it empty. Encoded here — not on `qualify`'s return
+* type — so `T`'s inference from `promise` is undisturbed.
 *
 * @category Interop
 *
@@ -1022,7 +1215,7 @@ function fromSafeThrowable(fn) {
 * // when fetchUser rejects with NotFoundError: user is Err("not_found")
 * ```
 */
-function fromPromise(promise, qualify) {
+function fromPromise(promise, qualify, ..._guard) {
 	const triage = qualify;
 	return new AsyncRes((typeof promise === "function" ? Promise.resolve().then(promise) : Promise.resolve(promise)).then((value) => okRes(value), (cause) => qualifyToResult(cause, triage)));
 }
@@ -1336,10 +1529,14 @@ const AsyncResult = {
 * so a payload `cause` (e.g. a wrapped driver error) is a legitimate,
 * *narrowing* structured field.
 *
-* `_tag` is the discriminant matched by {@link tag} in the error combinators
-* (`result.mapErr((matcher) => matcher.with(tag("NotFound"), …))`) and in
-* `match`; `Error.name` is the human-facing label in stack traces and logs. By
-* default they coincide, but
+* The matching half of the convention is `P.tag(t)` — the pattern constructor on
+* the `P` namespace, which builds the `{ _tag: t }` pattern this factory's `_tag`
+* is selected by (there is no standalone `tag` export).
+*
+* `_tag` is the discriminant matched by `P.tag` in the error combinators
+* (`result.mapErrCases((matcher) => matcher.with(P.tag("NotFound"), …))`) and in
+* `match`'s `errCases` handler; `Error.name` is the human-facing label in stack
+* traces and logs. By default they coincide, but
 * they can be **decoupled** with `options.name` — so a tag can be namespaced for
 * collision-safety (`"@my-lib/RetryableError"`) without that slash-prefixed
 * string leaking into `Error.name`:
@@ -1398,29 +1595,6 @@ function TaggedError(tag, options) {
 	}
 	return TaggedErrorBase;
 }
-/**
-* A `ts-pattern` pattern matching any value whose `_tag` equals `value` — a
-* {@link TaggedError}, or any discriminated member. Equivalent to the object
-* pattern `{ _tag: value }`, but reads better inside an error-matching
-* combinator and narrows to the matching variant, payload included.
-*
-* @typeParam Tag - the string literal tag to match.
-* @param value - the `_tag` to match.
-*
-* @category Tagged errors
-*
-* @example
-* ```ts
-* result.mapErr((matcher) =>
-*   matcher
-*     .with(tag("NotFound"), () => new NotFoundException())
-*     .with(tag("Conflict"), (e) => new ConflictException(e.key)),
-* );
-* ```
-*/
-function tag(value) {
-	return { _tag: value };
-}
 //#endregion
 exports.AsyncResult = AsyncResult;
 exports.Do = Do;
@@ -1428,14 +1602,10 @@ exports.DoAsync = DoAsync;
 exports.Err = Err;
 exports.ErrAsync = ErrAsync;
 exports.GetError = GetError;
+exports.NonExhaustiveError = NonExhaustiveError;
 exports.Ok = Ok;
 exports.OkAsync = OkAsync;
-Object.defineProperty(exports, "P", {
-	enumerable: true,
-	get: function() {
-		return ts_pattern.P;
-	}
-});
+exports.P = P;
 exports.Result = Result;
 exports.TaggedError = TaggedError;
 exports.all = all;
@@ -1451,10 +1621,4 @@ exports.isDefect = isDefect;
 exports.isErr = isErr;
 exports.isOk = isOk;
 exports.isResult = isResult;
-Object.defineProperty(exports, "match", {
-	enumerable: true,
-	get: function() {
-		return ts_pattern.match;
-	}
-});
-exports.tag = tag;
+exports.match = match;