unthrown 4.2.0 → 5.0.0-beta.0

package/README.md

@@ -11,7 +11,7 @@ pnpm add unthrown
 ```
 
 ```ts
-import { fromPromise, TaggedError } from "unthrown";
+import { fromPromise, P, TaggedError } from "unthrown";
 
 class NotFound extends TaggedError("NotFound") {} // our modeled domain failure
 class NotFoundError extends Error {} // what `fetchUser` rejects with on a 404
@@ -22,7 +22,7 @@ const user = fromPromise(fetchUser(id), (cause, defect) =>
 
 const status = await user.match({
   ok: () => 200,
-  err: () => 404,
+  err: (matcher) => matcher.with(P._, () => 404), // `err` takes the exhaustive matcher
   defect: () => 500,
 });
 ```
@@ -32,8 +32,9 @@ const status = await user.match({
   observable only via `match` / `recoverDefect`.
 - **Qualification at every boundary** — `fromPromise` / `fromThrowable` force you
   to triage each failure into a modeled error or a defect.
-- **Tagged errors** — `TaggedError(tag)` + the exhaustive `matchTags` fold.
-- Zero runtime dependencies, ESM-first, dual CJS/ESM.
+- **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.
 
 See the [full documentation](https://btravstack.github.io/unthrown/) for the guide
 and complete API.

package/dist/index.cjs

@@ -1,4 +1,35 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let ts_pattern = require("ts-pattern");
+//#region src/defect.ts
+const DEFECT = Symbol("unthrown/Defect");
+/**
+* Wrap a cause as a `Defect` marker — the value returned from a `qualify`
+* function when a failure is **not** a modeled domain error. The boundary
+* (`fromPromise` / `fromThrowable`) passes this in as `qualify`'s second
+* argument, so domain code never imports it.
+*
+* @param cause - the original thrown/rejected value.
+* @returns an opaque Defect marker carrying `cause`.
+*
+* @internal
+*/
+function defect(cause) {
+	return {
+		[DEFECT]: true,
+		cause
+	};
+}
+/**
+* Internal guard for the qualify-time marker. Distinct from the public
+* {@link isDefect} state guard — this one narrows the `E | Defect` union a
+* `qualify` function returns, not a `Result`.
+*
+* @internal
+*/
+function isDefectMarker(x) {
+	return typeof x === "object" && x !== null && x[DEFECT] === true;
+}
+//#endregion
 //#region src/core.ts
 /**
 * Thrown by a {@link Result}'s `get` / `getErr` when the assertion is
@@ -6,12 +37,12 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * `Ok`.
 *
 * @remarks
-* The offending value is exposed two ways: the typed {@link UnwrapError.error}
+* The offending value is exposed two ways: the typed {@link GetError.error}
 * property for programmatic access, and the standard `Error.cause` for the
 * runtime and devtools to chain — when `E` is an `Error` (e.g. a `TaggedError`)
 * its original stack is printed under "caused by".
 *
-* A `Defect` is never wrapped in an `UnwrapError`: its original cause is
+* A `Defect` is never wrapped in a `GetError`: its original cause is
 * re-thrown (with its original stack) instead.
 *
 * `get()` and `getErr()` are type-gated (`this: Result<T, never>` /
@@ -19,19 +50,19 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * unreachable through well-typed code — it remains only as a defensive guard
 * against unsound runtime misuse (e.g. an `as` cast past the gate).
 *
-* @typeParam E - the type of the {@link UnwrapError.error} it carries.
+* @typeParam E - the type of the {@link GetError.error} it carries.
 *
 * @category Errors
 */
-var UnwrapError = class extends Error {
+var GetError = class extends Error {
 	/**
 	* The offending value: the `Err` error for `get()`, or the `Ok` value for
 	* `getErr()`.
 	*/
 	error;
 	constructor(error) {
-		super("unthrown: called unwrap on a non-matching Result", { cause: error });
-		this.name = "UnwrapError";
+		super("unthrown: get() / getErr() called on a non-matching Result variant", { cause: error });
+		this.name = "GetError";
 		this.error = error;
 		Object.setPrototypeOf(this, new.target.prototype);
 	}
@@ -113,7 +144,9 @@ var Res = class {
 	mapErr(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
-			return errRes(f(this.error));
+			const out = runMatch(f, this.error);
+			if (isDefectMarker(out)) return defectRes(out.cause);
+			return errRes(out);
 		} catch (cause) {
 			return defectRes(cause);
 		}
@@ -121,31 +154,27 @@ var Res = class {
 	flatMapErr(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
-			return f(this.error);
+			const out = runMatch(f, this.error);
+			if (isDefectMarker(out)) return defectRes(out.cause);
+			return out;
 		} catch (cause) {
 			return defectRes(cause);
 		}
 	}
-	/** @deprecated Use {@link Res.flatMapErr}. */
-	orElse(f) {
-		return this.flatMapErr(f);
-	}
 	recoverErr(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
-			return okRes(f(this.error));
+			const out = runMatch(f, this.error);
+			if (isDefectMarker(out)) return defectRes(out.cause);
+			return okRes(out);
 		} catch (cause) {
 			return defectRes(cause);
 		}
 	}
-	/** @deprecated Use {@link Res.recoverErr}. */
-	recover(f) {
-		return this.recoverErr(f);
-	}
 	tapErr(f) {
 		if (this.tag !== "Err") return this;
 		try {
-			f(this.error);
+			runMatch(f, this.error);
 			return this;
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.error);
@@ -154,7 +183,7 @@ var Res = class {
 	flatTapErr(f) {
 		if (this.tag !== "Err") return this;
 		try {
-			const r = f(this.error);
+			const r = runMatch(f, this.error);
 			return r.tag === "Ok" ? this : passThrough(r);
 		} catch (cause) {
 			return observerThrowToDefect(cause, this.error);
@@ -177,53 +206,46 @@ var Res = class {
 			return observerThrowToDefect(cause, this.cause);
 		}
 	}
+	tapFailure(f) {
+		if (this.tag === "Ok") return this;
+		try {
+			f(this);
+			return this;
+		} catch (cause) {
+			return observerThrowToDefect(cause, this.tag === "Err" ? this.error : this.cause);
+		}
+	}
 	match(cases) {
 		switch (this.tag) {
 			case "Ok": return cases.ok(this.value);
-			case "Err": return cases.err(this.error);
+			case "Err": return cases.err((0, ts_pattern.match)(this.error)).run();
 			case "Defect": return cases.defect(this.cause);
 		}
 	}
 	get() {
 		switch (this.tag) {
 			case "Ok": return this.value;
-			case "Err": throw new UnwrapError(this.error);
+			case "Err": throw new GetError(this.error);
 			case "Defect": throw this.cause;
 		}
 	}
-	/** @deprecated Use {@link Res.get}. */
-	unwrap() {
-		return this.get();
-	}
 	getErr() {
 		switch (this.tag) {
 			case "Err": return this.error;
-			case "Ok": throw new UnwrapError(this.value);
+			case "Ok": throw new GetError(this.value);
 			case "Defect": throw this.cause;
 		}
 	}
-	/** @deprecated Use {@link Res.getErr}. */
-	unwrapErr() {
-		return this.getErr();
-	}
 	getOr(fallback) {
 		if (this.tag === "Ok") return this.value;
 		if (this.tag === "Defect") throw this.cause;
 		return fallback;
 	}
-	/** @deprecated Use {@link Res.getOr}. */
-	unwrapOr(fallback) {
-		return this.getOr(fallback);
-	}
 	getOrElse(f) {
 		if (this.tag === "Ok") return this.value;
 		if (this.tag === "Defect") throw this.cause;
 		return f(this.error);
 	}
-	/** @deprecated Use {@link Res.getOrElse}. */
-	unwrapOrElse(f) {
-		return this.getOrElse(f);
-	}
 	getOrNull() {
 		if (this.tag === "Ok") return this.value;
 		if (this.tag === "Defect") throw this.cause;
@@ -328,6 +350,19 @@ function passThrough(self) {
 	return self;
 }
 /**
+* Drive an error-combinator callback: build `match(error)`, hand it (plus the
+* injected `defect`) to the callback, and `.run()` the returned exhaustive
+* builder to its output. `.run()` executes `.exhaustive()` — type-forced
+* exhaustive, so it always matches for well-typed callers; a value that slips
+* through the types (a widened cast, a JS caller) throws `NonExhaustiveError`,
+* which the caller's `try/catch` turns into a `Defect` — an unmodeled failure.
+*
+* @internal
+*/
+function runMatch(f, error) {
+	return f((0, ts_pattern.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
@@ -456,7 +491,9 @@ var AsyncRes = class AsyncRes {
 		return new AsyncRes(this.promise.then((r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
-				return errRes(f(r.error));
+				const out = runMatch(f, r.error);
+				if (isDefectMarker(out)) return defectRes(out.cause);
+				return errRes(out);
 			} catch (cause) {
 				return defectRes(cause);
 			}
@@ -466,35 +503,31 @@ var AsyncRes = class AsyncRes {
 		return new AsyncRes(this.promise.then(async (r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
-				return await f(r.error);
+				const out = runMatch(f, r.error);
+				if (isDefectMarker(out)) return defectRes(out.cause);
+				return await out;
 			} catch (cause) {
 				return defectRes(cause);
 			}
 		}));
 	}
-	/** @deprecated Use {@link AsyncRes.flatMapErr}. */
-	orElse(f) {
-		return this.flatMapErr(f);
-	}
 	recoverErr(f) {
 		return new AsyncRes(this.promise.then((r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
-				return okRes(f(r.error));
+				const out = runMatch(f, r.error);
+				if (isDefectMarker(out)) return defectRes(out.cause);
+				return okRes(out);
 			} catch (cause) {
 				return defectRes(cause);
 			}
 		}));
 	}
-	/** @deprecated Use {@link AsyncRes.recoverErr}. */
-	recover(f) {
-		return this.recoverErr(f);
-	}
 	tapErr(f) {
 		return new AsyncRes(this.promise.then((r) => {
 			if (r.tag !== "Err") return r;
 			try {
-				f(r.error);
+				runMatch(f, r.error);
 				return r;
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.error);
@@ -505,7 +538,7 @@ var AsyncRes = class AsyncRes {
 		return new AsyncRes(this.promise.then(async (r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
-				const inner = await f(r.error);
+				const inner = await runMatch(f, r.error);
 				return inner.tag === "Ok" ? passThrough(r) : passThrough(inner);
 			} catch (cause) {
 				return observerThrowToDefect(cause, r.error);
@@ -533,37 +566,32 @@ var AsyncRes = class AsyncRes {
 			}
 		}));
 	}
+	tapFailure(f) {
+		return new AsyncRes(this.promise.then((r) => {
+			if (r.tag === "Ok") return r;
+			try {
+				f(r);
+				return r;
+			} catch (cause) {
+				return observerThrowToDefect(cause, r.tag === "Err" ? r.error : r.cause);
+			}
+		}));
+	}
 	match(cases) {
 		return this.promise.then((r) => r.match(cases));
 	}
 	get() {
 		return this.promise.then((r) => r.get());
 	}
-	/** @deprecated Use {@link AsyncRes.get}. */
-	unwrap() {
-		return this.get();
-	}
 	getErr() {
 		return this.promise.then((r) => r.getErr());
 	}
-	/** @deprecated Use {@link AsyncRes.getErr}. */
-	unwrapErr() {
-		return this.getErr();
-	}
 	getOr(fallback) {
 		return this.promise.then((r) => r.getOr(fallback));
 	}
-	/** @deprecated Use {@link AsyncRes.getOr}. */
-	unwrapOr(fallback) {
-		return this.getOr(fallback);
-	}
 	getOrElse(f) {
 		return this.promise.then((r) => r.getOrElse(f));
 	}
-	/** @deprecated Use {@link AsyncRes.getOrElse}. */
-	unwrapOrElse(f) {
-		return this.getOrElse(f);
-	}
 	getOrNull() {
 		return this.promise.then((r) => r.getOrNull());
 	}
@@ -740,36 +768,6 @@ function Do() {
 	return Ok({});
 }
 //#endregion
-//#region src/defect.ts
-const DEFECT = Symbol("unthrown/Defect");
-/**
-* Wrap a cause as a `Defect` marker — the value returned from a `qualify`
-* function when a failure is **not** a modeled domain error. The boundary
-* (`fromPromise` / `fromThrowable`) passes this in as `qualify`'s second
-* argument, so domain code never imports it.
-*
-* @param cause - the original thrown/rejected value.
-* @returns an opaque Defect marker carrying `cause`.
-*
-* @internal
-*/
-function defect(cause) {
-	return {
-		[DEFECT]: true,
-		cause
-	};
-}
-/**
-* Internal guard for the qualify-time marker. Distinct from the public
-* {@link isDefect} state guard — this one narrows the `E | Defect` union a
-* `qualify` function returns, not a `Result`.
-*
-* @internal
-*/
-function isDefectMarker(x) {
-	return typeof x === "object" && x !== null && x[DEFECT] === true;
-}
-//#endregion
 //#region src/interop.ts
 /**
 * Bridge a nullable value into a {@link Result}: absence becomes a **modeled**
@@ -971,15 +969,25 @@ function qualifyToResult(cause, qualify) {
 *
 * @internal
 */
+/** The Defect minted for an out-of-contract non-`Result` element in an aggregate. */
+function nonResultDefect() {
+	return defectRes(/* @__PURE__ */ new TypeError("unthrown: aggregate received a non-Result element"));
+}
 function foldArray(results) {
 	let firstErr;
 	let firstDefect;
 	const values = [];
-	for (const r of results) if (r.tag === "Defect") {
-		firstDefect ??= r;
-		break;
-	} else if (r.tag === "Err") firstErr ??= r;
-	else values.push(r.value);
+	for (const r of results) {
+		if (!isResult(r)) {
+			firstDefect ??= nonResultDefect();
+			break;
+		}
+		if (r.tag === "Defect") {
+			firstDefect ??= r;
+			break;
+		} else if (r.tag === "Err") firstErr ??= r;
+		else values.push(r.value);
+	}
 	return firstDefect ?? firstErr ?? Ok(values);
 }
 /**
@@ -993,16 +1001,22 @@ function foldRecord(results) {
 	let firstErr;
 	let firstDefect;
 	const values = {};
-	for (const [key, r] of Object.entries(results)) if (r.tag === "Defect") {
-		firstDefect ??= r;
-		break;
-	} else if (r.tag === "Err") firstErr ??= r;
-	else Object.defineProperty(values, key, {
-		value: r.value,
-		enumerable: true,
-		writable: true,
-		configurable: true
-	});
+	for (const [key, r] of Object.entries(results)) {
+		if (!isResult(r)) {
+			firstDefect ??= nonResultDefect();
+			break;
+		}
+		if (r.tag === "Defect") {
+			firstDefect ??= r;
+			break;
+		} else if (r.tag === "Err") firstErr ??= r;
+		else Object.defineProperty(values, key, {
+			value: r.value,
+			enumerable: true,
+			writable: true,
+			configurable: true
+		});
+	}
 	return firstDefect ?? firstErr ?? Ok(values);
 }
 /**
@@ -1074,7 +1088,7 @@ function allFromDict(results) {
 * ```
 */
 function allAsync(results) {
-	return new AsyncRes(Promise.all(results).then((resolved) => foldArray(resolved)));
+	return new AsyncRes(Promise.all(results.map((r) => Promise.resolve(r).then((x) => x, (cause) => defectRes(cause)))).then((resolved) => foldArray(resolved)));
 }
 /**
 * The asynchronous counterpart of {@link allFromDict}: combine a record of
@@ -1099,7 +1113,7 @@ function allAsync(results) {
 */
 function allFromDictAsync(results) {
 	const entries = Object.entries(results);
-	return new AsyncRes(Promise.all(entries.map(([, ar]) => ar)).then((resolved) => {
+	return new AsyncRes(Promise.all(entries.map(([, ar]) => Promise.resolve(ar).then((x) => x, (cause) => defectRes(cause)))).then((resolved) => {
 		const byKey = Object.create(null);
 		entries.forEach(([key], i) => {
 			byKey[key] = resolved[i];
@@ -1203,8 +1217,10 @@ const AsyncResult = {
 * rejected at compile time (and excluded from the instance type), so it can't
 * shadow `Error.name`.
 *
-* `_tag` is the discriminant used by {@link matchTags}; `Error.name` is the
-* human-facing label in stack traces and logs. By default they coincide, but
+* `_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
 * 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`:
@@ -1253,28 +1269,45 @@ function TaggedError(tag, options) {
 	}
 	return TaggedErrorBase;
 }
-function matchTags(result, handlers) {
-	const onErr = (error) => {
-		const tag = error._tag;
-		const handler = tag === "Ok" || tag === "Defect" || !Object.hasOwn(handlers, tag) ? void 0 : handlers[tag];
-		return handler ? handler(error) : handlers.Defect(error);
-	};
-	return result.match({
-		ok: handlers.Ok,
-		err: onErr,
-		defect: handlers.Defect
-	});
+/**
+* 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;
 exports.Err = Err;
 exports.ErrAsync = ErrAsync;
+exports.GetError = GetError;
 exports.Ok = Ok;
 exports.OkAsync = OkAsync;
+Object.defineProperty(exports, "P", {
+	enumerable: true,
+	get: function() {
+		return ts_pattern.P;
+	}
+});
 exports.Result = Result;
 exports.TaggedError = TaggedError;
-exports.UnwrapError = UnwrapError;
 exports.all = all;
 exports.allAsync = allAsync;
 exports.allFromDict = allFromDict;
@@ -1288,4 +1321,10 @@ exports.isDefect = isDefect;
 exports.isErr = isErr;
 exports.isOk = isOk;
 exports.isResult = isResult;
-exports.matchTags = matchTags;
+Object.defineProperty(exports, "match", {
+	enumerable: true,
+	get: function() {
+		return ts_pattern.match;
+	}
+});
+exports.tag = tag;