unthrown 4.0.0 → 4.2.0

package/dist/index.cjs

@@ -1,8 +1,8 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/core.ts
 /**
-* Thrown by a {@link Result}'s `unwrap` / `unwrapErr` when the assertion is
-* wrong on a *modeled* result — `unwrap()` on an `Err`, or `unwrapErr()` on an
+* Thrown by a {@link Result}'s `get` / `getErr` when the assertion is
+* wrong on a *modeled* result — `get()` on an `Err`, or `getErr()` on an
 * `Ok`.
 *
 * @remarks
@@ -14,7 +14,7 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 * A `Defect` is never wrapped in an `UnwrapError`: its original cause is
 * re-thrown (with its original stack) instead.
 *
-* `unwrap()` and `unwrapErr()` are type-gated (`this: Result<T, never>` /
+* `get()` and `getErr()` are type-gated (`this: Result<T, never>` /
 * `Result<never, E>`), so the wrong-variant branch that throws this is
 * unreachable through well-typed code — it remains only as a defensive guard
 * against unsound runtime misuse (e.g. an `as` cast past the gate).
@@ -25,8 +25,8 @@ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 */
 var UnwrapError = class extends Error {
 	/**
-	* The offending value: the `Err` error for `unwrap()`, or the `Ok` value for
-	* `unwrapErr()`.
+	* The offending value: the `Err` error for `get()`, or the `Ok` value for
+	* `getErr()`.
 	*/
 	error;
 	constructor(error) {
@@ -106,6 +106,10 @@ var Res = class {
 		if (this.tag !== "Ok") return passThrough(this);
 		return okRes(value);
 	}
+	discard() {
+		if (this.tag !== "Ok") return passThrough(this);
+		return okRes(void 0);
+	}
 	mapErr(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
@@ -114,7 +118,7 @@ var Res = class {
 			return defectRes(cause);
 		}
 	}
-	orElse(f) {
+	flatMapErr(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
 			return f(this.error);
@@ -122,7 +126,11 @@ var Res = class {
 			return defectRes(cause);
 		}
 	}
-	recover(f) {
+	/** @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));
@@ -130,6 +138,10 @@ var Res = class {
 			return defectRes(cause);
 		}
 	}
+	/** @deprecated Use {@link Res.recoverErr}. */
+	recover(f) {
+		return this.recoverErr(f);
+	}
 	tapErr(f) {
 		if (this.tag !== "Err") return this;
 		try {
@@ -172,30 +184,46 @@ var Res = class {
 			case "Defect": return cases.defect(this.cause);
 		}
 	}
-	unwrap() {
+	get() {
 		switch (this.tag) {
 			case "Ok": return this.value;
 			case "Err": throw new UnwrapError(this.error);
 			case "Defect": throw this.cause;
 		}
 	}
-	unwrapErr() {
+	/** @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 "Defect": throw this.cause;
 		}
 	}
-	unwrapOr(fallback) {
+	/** @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;
 	}
-	unwrapOrElse(f) {
+	/** @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;
@@ -205,6 +233,11 @@ var Res = class {
 		if (this.tag === "Ok") return this.value;
 		if (this.tag === "Defect") throw this.cause;
 	}
+	getOrThrow() {
+		if (this.tag === "Ok") return this.value;
+		if (this.tag === "Defect") throw this.cause;
+		throw this.error;
+	}
 	isOk() {
 		return this.tag === "Ok";
 	}
@@ -416,6 +449,9 @@ var AsyncRes = class AsyncRes {
 	as(value) {
 		return new AsyncRes(this.promise.then((r) => r.tag === "Ok" ? okRes(value) : passThrough(r)));
 	}
+	discard() {
+		return new AsyncRes(this.promise.then((r) => r.tag === "Ok" ? okRes(void 0) : passThrough(r)));
+	}
 	mapErr(f) {
 		return new AsyncRes(this.promise.then((r) => {
 			if (r.tag !== "Err") return passThrough(r);
@@ -426,7 +462,7 @@ var AsyncRes = class AsyncRes {
 			}
 		}));
 	}
-	orElse(f) {
+	flatMapErr(f) {
 		return new AsyncRes(this.promise.then(async (r) => {
 			if (r.tag !== "Err") return passThrough(r);
 			try {
@@ -436,7 +472,11 @@ var AsyncRes = class AsyncRes {
 			}
 		}));
 	}
-	recover(f) {
+	/** @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 {
@@ -446,6 +486,10 @@ var AsyncRes = class AsyncRes {
 			}
 		}));
 	}
+	/** @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;
@@ -492,17 +536,33 @@ var AsyncRes = class AsyncRes {
 	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.promise.then((r) => r.unwrap());
+		return this.get();
+	}
+	getErr() {
+		return this.promise.then((r) => r.getErr());
 	}
+	/** @deprecated Use {@link AsyncRes.getErr}. */
 	unwrapErr() {
-		return this.promise.then((r) => r.unwrapErr());
+		return this.getErr();
+	}
+	getOr(fallback) {
+		return this.promise.then((r) => r.getOr(fallback));
 	}
+	/** @deprecated Use {@link AsyncRes.getOr}. */
 	unwrapOr(fallback) {
-		return this.promise.then((r) => r.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.promise.then((r) => r.unwrapOrElse(f));
+		return this.getOrElse(f);
 	}
 	getOrNull() {
 		return this.promise.then((r) => r.getOrNull());
@@ -510,46 +570,59 @@ var AsyncRes = class AsyncRes {
 	getOrUndefined() {
 		return this.promise.then((r) => r.getOrUndefined());
 	}
+	getOrThrow() {
+		return this.promise.then((r) => r.getOrThrow());
+	}
 };
 //#endregion
 //#region src/constructors.ts
+function Ok(value) {
+	return okRes(value);
+}
 /**
-* Construct a successful {@link Result}.
+* Construct a failed {@link Result} carrying a **modeled** error.
 *
-* @typeParam T - the success value type.
-* @param value - the success value to wrap.
+* @typeParam E - the modeled error type.
+* @param error - the domain error to wrap.
 *
 * @example
 * ```ts
-* import { Ok } from "unthrown";
+* import { Err } from "unthrown";
 *
-* Ok(2).map((n) => n + 1); // => Ok(3)
-* Ok(42).unwrap(); // => 42
+* Err("not_found").map((n) => n + 1); // => Err("not_found") (map skipped)
+* Err("not_found").getErr(); // => "not_found"
 * ```
 *
 * @category Constructors
 */
-function Ok(value) {
-	return okRes(value);
+function Err(error) {
+	return errRes(error);
+}
+function OkAsync(value) {
+	return Ok(value).toAsync();
 }
 /**
-* Construct a failed {@link Result} carrying a **modeled** error.
+* Construct a failed {@link AsyncResult} carrying a **modeled** error — the
+* pre-lifted form of {@link Err}, sparing you `Err(error).toAsync()`.
+*
+* @remarks
+* The error-channel mirror of {@link OkAsync}; see it for the naming and the
+* `AsyncResult.Err` companion alias.
 *
 * @typeParam E - the modeled error type.
 * @param error - the domain error to wrap.
 *
 * @example
 * ```ts
-* import { Err } from "unthrown";
+* import { ErrAsync } from "unthrown";
 *
-* Err("not_found").map((n) => n + 1); // => Err("not_found") (map skipped)
-* Err("not_found").unwrapErr(); // => "not_found"
+* ErrAsync("not_found"); // AsyncResult<never, string>
 * ```
 *
 * @category Constructors
 */
-function Err(error) {
-	return errRes(error);
+function ErrAsync(error) {
+	return Err(error).toAsync();
 }
 /**
 * Type guard: narrow a {@link Result} to its `Ok` variant, exposing `.value`.
@@ -718,9 +791,9 @@ function isDefectMarker(x) {
 * import { fromNullable } from "unthrown";
 *
 * const map = new Map([["a", 1]]);
-* fromNullable(map.get("a"), () => "absent").unwrapOr(0); // => 1
+* fromNullable(map.get("a"), () => "absent").getOr(0); // => 1
 * fromNullable(map.get("z"), () => "absent"); // => Err("absent")
-* fromNullable(0, () => "absent").unwrapOr(-1); // => 0 (falsy but present)
+* fromNullable(0, () => "absent").getOr(-1); // => 0 (falsy but present)
 * ```
 */
 function fromNullable(value, onAbsent) {
@@ -740,7 +813,7 @@ function fromNullable(value, onAbsent) {
 * `qualify`'s return is **subtracted** from `E`, never inferred into it. So a
 * `qualify` that returns *only* `defect(cause)` yields `E = never` (a Defect is
 * out-of-band and must not pollute the error channel); reach for
-* {@link fromSafePromise} when every failure is a Defect.
+* {@link fromSafeThrowable} when every throw is a Defect.
 *
 * @typeParam A - the wrapped function's argument tuple.
 * @typeParam T - the wrapped function's return type.
@@ -764,7 +837,7 @@ function fromNullable(value, onAbsent) {
 *     cause instanceof SyntaxError ? ("invalid_json" as const) : defect(cause),
 * );
 *
-* parse('{"ok":true}').unwrapOr(null); // => { ok: true }
+* parse('{"ok":true}').getOr(null); // => { ok: true }
 * parse("nope"); // => Err("invalid_json")
 * ```
 */
@@ -779,6 +852,44 @@ function fromThrowable(fn, qualify) {
 	};
 }
 /**
+* Wrap a throwing synchronous function asserted **not** to fail in any modeled
+* way: any throw becomes a `Defect`.
+*
+* @remarks
+* The synchronous counterpart of {@link fromSafePromise}. Use it only when a
+* throw genuinely indicates a bug rather than an anticipated outcome — the
+* error channel is `never`, so there is nothing to triage; there is no
+* `qualify`. When some throws *are* anticipated, reach for
+* {@link fromThrowable} and triage them.
+*
+* @typeParam A - the wrapped function's argument tuple.
+* @typeParam T - the wrapped function's return type.
+* @param fn - the throwing function to wrap.
+* @returns a function with the same arguments returning `Result<T, never>`.
+*
+* @category Interop
+*
+* @example
+* ```ts
+* import { fromSafeThrowable } from "unthrown";
+*
+* // A decode failure here is a bug (the row came from our own schema), so
+* // every throw is a defect — no throwaway `(cause, defect) => defect(cause)`.
+* const decode = fromSafeThrowable((row: Row) => userSchema.parse(row));
+*
+* decode(row); // => Result<User, never> — a throw becomes a Defect
+* ```
+*/
+function fromSafeThrowable(fn) {
+	return (...args) => {
+		try {
+			return Ok(fn(...args));
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	};
+}
+/**
 * Wrap a `Promise` (or a thunk producing one) as an {@link AsyncResult}, forcing
 * every rejection to be triaged.
 *
@@ -826,7 +937,8 @@ function fromPromise(promise, qualify) {
 * @remarks
 * Use this only when a rejection genuinely indicates a bug rather than an
 * anticipated outcome — the error channel is `never`, so there is nothing to
-* triage. (`await`-ing still yields a `Result`; it never throws.)
+* triage. (`await`-ing still yields a `Result`; it never throws.) The
+* synchronous counterpart is {@link fromSafeThrowable}.
 *
 * @typeParam T - the resolved value type.
 * @param promise - the promise, or a thunk returning one.
@@ -837,7 +949,7 @@ function fromPromise(promise, qualify) {
 * ```ts
 * import { fromSafePromise } from "unthrown";
 *
-* (await fromSafePromise(Promise.resolve(3))).unwrap(); // => 3
+* (await fromSafePromise(Promise.resolve(3))).get(); // => 3
 * // a rejection becomes a Defect (never a modeled Err):
 * await fromSafePromise(Promise.reject(new Error("boom"))); // => Defect(Error("boom"))
 * ```
@@ -911,7 +1023,7 @@ function foldRecord(results) {
 * ```ts
 * import { all, Ok, Err } from "unthrown";
 *
-* all([Ok(1), Ok("a"), Ok(true)]).unwrap(); // => [1, "a", true] (typed [number, string, boolean])
+* all([Ok(1), Ok("a"), Ok(true)]).get(); // => [1, "a", true] (typed [number, string, boolean])
 * all([Ok(1), Err("e"), Ok(3)]); // => Err("e") (short-circuits on the first Err)
 * ```
 */
@@ -934,7 +1046,7 @@ function all(results) {
 * ```ts
 * import { allFromDict, Ok, Err } from "unthrown";
 *
-* allFromDict({ id: Ok(1), name: Ok("ada") }).unwrap(); // => { id: 1, name: "ada" }
+* allFromDict({ id: Ok(1), name: Ok("ada") }).get(); // => { id: 1, name: "ada" }
 * allFromDict({ id: Ok(1), name: Err("missing") }); // => Err("missing")
 * ```
 */
@@ -958,7 +1070,7 @@ function allFromDict(results) {
 * import { allAsync, fromSafePromise } from "unthrown";
 *
 * const both = allAsync([fromSafePromise(Promise.resolve(1)), fromSafePromise(Promise.resolve(2))]);
-* (await both).unwrap(); // => [1, 2]
+* (await both).get(); // => [1, 2]
 * ```
 */
 function allAsync(results) {
@@ -982,7 +1094,7 @@ function allAsync(results) {
 *   a: fromSafePromise(Promise.resolve(1)),
 *   b: fromSafePromise(Promise.resolve("x")),
 * });
-* (await both).unwrap(); // => { a: 1, b: "x" }
+* (await both).get(); // => { a: 1, b: "x" }
 * ```
 */
 function allFromDictAsync(results) {
@@ -1001,8 +1113,9 @@ function allFromDictAsync(results) {
 * Companion object grouping the **`Result`-producing** entry points under a
 * single, discoverable namespace: {@link Result.Ok}, {@link Result.Err},
 * {@link Result.Do}, {@link Result.fromNullable}, {@link Result.fromThrowable},
-* {@link Result.all}, {@link Result.allFromDict}, {@link Result.isOk},
-* {@link Result.isErr}, {@link Result.isDefect}, {@link Result.isResult}.
+* {@link Result.fromSafeThrowable}, {@link Result.all},
+* {@link Result.allFromDict}, {@link Result.isOk}, {@link Result.isErr},
+* {@link Result.isDefect}, {@link Result.isResult}.
 *
 * @remarks
 * Purely additive sugar — each member **is** the corresponding free function.
@@ -1019,7 +1132,7 @@ function allFromDictAsync(results) {
 * @example
 * ```ts
 * import { Result } from "unthrown";
-* Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // => 2
+* Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).get(); // => 2
 * ```
 */
 const Result = {
@@ -1028,6 +1141,7 @@ const Result = {
 	Do,
 	fromNullable,
 	fromThrowable,
+	fromSafeThrowable,
 	all,
 	allFromDict,
 	isOk,
@@ -1037,18 +1151,20 @@ const Result = {
 };
 /**
 * Companion object grouping the **`AsyncResult`-producing** entry points under
-* the matching namespace: {@link AsyncResult.fromPromise},
-* {@link AsyncResult.fromSafePromise}, {@link AsyncResult.all},
-* {@link AsyncResult.allFromDict}.
+* the matching namespace: {@link AsyncResult.Ok}, {@link AsyncResult.Err},
+* {@link AsyncResult.fromPromise}, {@link AsyncResult.fromSafePromise},
+* {@link AsyncResult.all}, {@link AsyncResult.allFromDict}.
 *
 * @remarks
 * The async sibling of {@link Result}. Statics are grouped by what they
-* **return**, so `fromPromise`/`fromSafePromise` and the async aggregates sit
-* here rather than on {@link Result}; the namespace already conveys "async", so
-* the aggregates drop the `Async` suffix (`AsyncResult.all` is the free function
-* `allAsync`; `AsyncResult.allFromDict` is `allFromDictAsync`). Like
-* {@link Result}, the free functions remain the primary, tree-shakeable API; the
-* value `AsyncResult` and the type {@link AsyncResult} share one name.
+* **return**, so the pre-lifted constructors, `fromPromise`/`fromSafePromise`,
+* and the async aggregates sit here rather than on {@link Result}; the namespace
+* already conveys "async", so the members drop the `Async` suffix their free
+* functions carry (`AsyncResult.Ok` is `OkAsync`; `AsyncResult.Err` is
+* `ErrAsync`; `AsyncResult.all` is `allAsync`; `AsyncResult.allFromDict` is
+* `allFromDictAsync`). Like {@link Result}, the free functions remain the
+* primary, tree-shakeable API; the value `AsyncResult` and the type
+* {@link AsyncResult} share one name.
 *
 * @category Facade
 *
@@ -1056,10 +1172,12 @@ const Result = {
 * ```ts
 * import { AsyncResult } from "unthrown";
 * const user = await AsyncResult.fromPromise(fetchUser(id), (c, defect) => defect(c));
-* user.unwrap(); // => the fetched user (on success)
+* user.get(); // => the fetched user (on success)
 * ```
 */
 const AsyncResult = {
+	Ok: OkAsync,
+	Err: ErrAsync,
 	fromPromise,
 	fromSafePromise,
 	all: allAsync,
@@ -1151,7 +1269,9 @@ function matchTags(result, handlers) {
 exports.AsyncResult = AsyncResult;
 exports.Do = Do;
 exports.Err = Err;
+exports.ErrAsync = ErrAsync;
 exports.Ok = Ok;
+exports.OkAsync = OkAsync;
 exports.Result = Result;
 exports.TaggedError = TaggedError;
 exports.UnwrapError = UnwrapError;
@@ -1162,6 +1282,7 @@ exports.allFromDictAsync = allFromDictAsync;
 exports.fromNullable = fromNullable;
 exports.fromPromise = fromPromise;
 exports.fromSafePromise = fromSafePromise;
+exports.fromSafeThrowable = fromSafeThrowable;
 exports.fromThrowable = fromThrowable;
 exports.isDefect = isDefect;
 exports.isErr = isErr;