unthrown 3.1.0 → 4.1.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,14 +14,19 @@ 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.
 *
+* `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).
+*
 * @typeParam E - the type of the {@link UnwrapError.error} it carries.
 *
 * @category Errors
 */
 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) {
@@ -109,7 +114,7 @@ var Res = class {
 			return defectRes(cause);
 		}
 	}
-	orElse(f) {
+	flatMapErr(f) {
 		if (this.tag !== "Err") return passThrough(this);
 		try {
 			return f(this.error);
@@ -117,7 +122,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));
@@ -125,6 +134,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 {
@@ -167,30 +180,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;
@@ -200,6 +229,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";
 	}
@@ -421,7 +455,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 {
@@ -431,7 +465,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 {
@@ -441,6 +479,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;
@@ -487,17 +529,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());
@@ -505,6 +563,9 @@ 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
@@ -519,7 +580,7 @@ var AsyncRes = class AsyncRes {
 * import { Ok } from "unthrown";
 *
 * Ok(2).map((n) => n + 1); // => Ok(3)
-* Ok(42).unwrap(); // => 42
+* Ok(42).get(); // => 42
 * ```
 *
 * @category Constructors
@@ -538,7 +599,7 @@ function Ok(value) {
 * import { Err } from "unthrown";
 *
 * Err("not_found").map((n) => n + 1); // => Err("not_found") (map skipped)
-* Err("not_found").unwrapErr(); // => "not_found"
+* Err("not_found").getErr(); // => "not_found"
 * ```
 *
 * @category Constructors
@@ -547,6 +608,58 @@ function Err(error) {
 	return errRes(error);
 }
 /**
+* Construct a successful {@link AsyncResult} from a pure value — the pre-lifted
+* form of {@link Ok}, sparing you `Ok(value).toAsync()`.
+*
+* @remarks
+* Reach for this on the synchronous/early branch of an `AsyncResult`-returning
+* function, so both branches share one return type without a trailing
+* `.toAsync()`. Named with the `Async` suffix the async free functions carry
+* (`allAsync`, `allFromDictAsync`); the {@link AsyncResult} companion aliases it
+* as `AsyncResult.Ok` (the namespace already says "async", so the suffix drops).
+*
+* @typeParam T - the success value type.
+* @param value - the success value to wrap.
+*
+* @example
+* ```ts
+* import { OkAsync, type AsyncResult } from "unthrown";
+*
+* function loadItems(ids: string[]): AsyncResult<Item[], never> {
+*   if (ids.length === 0) return OkAsync([]); // no more Ok([]).toAsync()
+*   return itemRepository.load(ids);
+* }
+* ```
+*
+* @category Constructors
+*/
+function OkAsync(value) {
+	return Ok(value).toAsync();
+}
+/**
+* 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 { ErrAsync } from "unthrown";
+*
+* ErrAsync("not_found"); // AsyncResult<never, string>
+* ```
+*
+* @category Constructors
+*/
+function ErrAsync(error) {
+	return Err(error).toAsync();
+}
+/**
 * Type guard: narrow a {@link Result} to its `Ok` variant, exposing `.value`.
 *
 * @returns `true` when `r` is `Ok`.
@@ -713,9 +826,9 @@ function isDefectMarker(x) {
 * import { fromNullable } from "unthrown";
 *
 * const map = new Map([["a", 1]]);
-* fromNullable(map.get("a"), () => "absent").unwrap(); // => 1
+* fromNullable(map.get("a"), () => "absent").getOr(0); // => 1
 * fromNullable(map.get("z"), () => "absent"); // => Err("absent")
-* fromNullable(0, () => "absent").unwrap(); // => 0 (falsy but present)
+* fromNullable(0, () => "absent").getOr(-1); // => 0 (falsy but present)
 * ```
 */
 function fromNullable(value, onAbsent) {
@@ -735,7 +848,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.
@@ -759,7 +872,7 @@ function fromNullable(value, onAbsent) {
 *     cause instanceof SyntaxError ? ("invalid_json" as const) : defect(cause),
 * );
 *
-* parse('{"ok":true}').unwrap(); // => { ok: true }
+* parse('{"ok":true}').getOr(null); // => { ok: true }
 * parse("nope"); // => Err("invalid_json")
 * ```
 */
@@ -774,6 +887,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.
 *
@@ -806,8 +957,8 @@ function fromThrowable(fn, qualify) {
 *   cause instanceof NotFoundError ? ("not_found" as const) : defect(cause),
 * );
 *
-* user.unwrap(); // => the fetched user (on success)
-* // when fetchUser rejects with NotFoundError: => Err("not_found")
+* if (user.isOk()) user.value; // => the fetched user
+* // when fetchUser rejects with NotFoundError: user is Err("not_found")
 * ```
 */
 function fromPromise(promise, qualify) {
@@ -821,7 +972,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.
@@ -832,7 +984,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"))
 * ```
@@ -906,7 +1058,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)
 * ```
 */
@@ -929,7 +1081,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")
 * ```
 */
@@ -953,7 +1105,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) {
@@ -977,7 +1129,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) {
@@ -996,8 +1148,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.
@@ -1014,7 +1167,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 = {
@@ -1023,6 +1176,7 @@ const Result = {
 	Do,
 	fromNullable,
 	fromThrowable,
+	fromSafeThrowable,
 	all,
 	allFromDict,
 	isOk,
@@ -1032,18 +1186,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
 *
@@ -1051,10 +1207,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,
@@ -1068,8 +1226,13 @@ const AsyncResult = {
 *
 * @remarks
 * Extend the returned class to declare a concrete error. Supply the payload with
-* an instantiation expression; omit it for a payload-less error. A `message`
-* field in the payload is forwarded to `Error`. The `_tag` always reflects
+* an instantiation expression; omit it for a payload-less error. The `message`
+* is **not** a payload field — it is the human string owned by `Error`, not
+* structured data, so it is reserved. Define it once per subclass the standard
+* way, `override message = "…"` (it may interpolate the payload via `this`,
+* which the base populates before the subclass field initialiser runs); a
+* payload `message` is rejected at compile time, so contextual detail lives in
+* typed fields, never baked into per-call prose. The `_tag` always reflects
 * `tag` and cannot be overridden by the payload. `name` is likewise reserved —
 * it is the display label (set it with `options.name`); a payload `name` is
 * rejected at compile time (and excluded from the instance type), so it can't
@@ -1084,11 +1247,14 @@ const AsyncResult = {
 * ```ts
 * class RetryableError extends TaggedError("@my-lib/RetryableError", {
 *   name: "RetryableError",
-* })<{ message: string }> {}
-*
-* const e = new RetryableError({ message: "boom" });
-* e._tag; // "@my-lib/RetryableError" — namespaced discriminant
-* e.name; // "RetryableError"          — clean display name
+* }) {
+*   override message = "operation failed; safe to retry";
+* }
+*
+* const e = new RetryableError();
+* e._tag;    // "@my-lib/RetryableError" — namespaced discriminant
+* e.name;    // "RetryableError"          — clean display name
+* e.message; // "operation failed; safe to retry" — the standard Error.message
 * ```
 *
 * @typeParam Tag - the string literal discriminant.
@@ -1112,10 +1278,11 @@ function TaggedError(tag, options) {
 	class TaggedErrorBase extends Error {
 		_tag;
 		constructor(props) {
-			super(typeof props?.["message"] === "string" ? props["message"] : void 0);
+			super();
 			if (props) Object.assign(this, props);
 			this._tag = tag;
 			this.name = displayName;
+			delete this.message;
 			Object.setPrototypeOf(this, new.target.prototype);
 		}
 	}
@@ -1137,7 +1304,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;
@@ -1148,6 +1317,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;