unthrown 0.1.0

package/dist/index.cjs

@@ -0,0 +1,668 @@
+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
+* `Ok`.
+*
+* @remarks
+* A `Defect` is never wrapped in an `UnwrapError`: its original cause is
+* re-thrown (with its original stack) instead.
+*
+* @typeParam E - the type of the {@link UnwrapError.error} it carries.
+*/
+var UnwrapError = class extends Error {
+	/**
+	* The offending value: the `Err` error for `unwrap()`, or the `Ok` value for
+	* `unwrapErr()`.
+	*/
+	error;
+	constructor(error) {
+		super("unthrown: called unwrap on a non-matching Result");
+		this.name = "UnwrapError";
+		this.error = error;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+/**
+* Method holder for {@link Result}. Never instantiated with `new` and never
+* exported; the builders below attach its prototype to plain objects. Every
+* method types `this` as the public `Result` union, so it narrows on `tag`.
+*
+* @internal
+*/
+var Res = class {
+	map(f) {
+		if (this.tag !== "Ok") return this;
+		try {
+			return okRes(f(this.value));
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	flatMap(f) {
+		if (this.tag !== "Ok") return this;
+		try {
+			return f(this.value);
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	tap(f) {
+		if (this.tag !== "Ok") return this;
+		try {
+			f(this.value);
+			return this;
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	as(value) {
+		if (this.tag !== "Ok") return this;
+		return okRes(value);
+	}
+	mapErr(f) {
+		if (this.tag !== "Err") return this;
+		try {
+			return errRes(f(this.error));
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	orElse(f) {
+		if (this.tag !== "Err") return this;
+		try {
+			return f(this.error);
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	recover(f) {
+		if (this.tag !== "Err") return this;
+		try {
+			return okRes(f(this.error));
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	tapErr(f) {
+		if (this.tag !== "Err") return this;
+		try {
+			f(this.error);
+			return this;
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	recoverDefect(f) {
+		if (this.tag !== "Defect") return this;
+		try {
+			return f(this.cause);
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	tapDefect(f) {
+		if (this.tag !== "Defect") return this;
+		try {
+			f(this.cause);
+			return this;
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	match(cases) {
+		switch (this.tag) {
+			case "Ok": return cases.ok(this.value);
+			case "Err": return cases.err(this.error);
+			case "Defect": return cases.defect(this.cause);
+		}
+	}
+	unwrap() {
+		switch (this.tag) {
+			case "Ok": return this.value;
+			case "Err": throw new UnwrapError(this.error);
+			case "Defect": throw this.cause;
+		}
+	}
+	unwrapErr() {
+		switch (this.tag) {
+			case "Err": return this.error;
+			case "Ok": throw new UnwrapError(this.value);
+			case "Defect": throw this.cause;
+		}
+	}
+	unwrapOr(fallback) {
+		if (this.tag === "Ok") return this.value;
+		if (this.tag === "Defect") throw this.cause;
+		return fallback;
+	}
+	unwrapOrElse(f) {
+		if (this.tag === "Ok") return this.value;
+		if (this.tag === "Defect") throw this.cause;
+		return f(this.error);
+	}
+	getOrNull() {
+		if (this.tag === "Ok") return this.value;
+		if (this.tag === "Defect") throw this.cause;
+		return null;
+	}
+	getOrUndefined() {
+		if (this.tag === "Ok") return this.value;
+		if (this.tag === "Defect") throw this.cause;
+	}
+	isOk() {
+		return this.tag === "Ok";
+	}
+	isErr() {
+		return this.tag === "Err";
+	}
+	isDefect() {
+		return this.tag === "Defect";
+	}
+	toAsync() {
+		return new AsyncRes(Promise.resolve(this));
+	}
+};
+const RESULT_PROTO = Res.prototype;
+/**
+* Construct an `Ok` result — a plain object on the {@link Res} prototype.
+*
+* @internal
+*/
+function okRes(value) {
+	return Object.assign(Object.create(RESULT_PROTO), {
+		tag: "Ok",
+		value
+	});
+}
+/**
+* Construct an `Err` result.
+*
+* @internal
+*/
+function errRes(error) {
+	return Object.assign(Object.create(RESULT_PROTO), {
+		tag: "Err",
+		error
+	});
+}
+/**
+* Construct a `Defect` result.
+*
+* @internal
+*/
+function defectRes(cause) {
+	return Object.assign(Object.create(RESULT_PROTO), {
+		tag: "Defect",
+		cause
+	});
+}
+/**
+* The sole runtime implementation of {@link AsyncResult}: wraps a
+* `Promise<Result>` constructed never to reject. Operates on the public `Result`
+* union (via `tag`), never on `Res` internals. Never re-exported from `index.ts`.
+*
+* @internal
+*/
+var AsyncRes = class AsyncRes {
+	promise;
+	constructor(promise) {
+		this.promise = promise;
+	}
+	then(onfulfilled, onrejected) {
+		return this.promise.then(onfulfilled, onrejected);
+	}
+	map(f) {
+		return new AsyncRes(this.promise.then((r) => {
+			if (r.tag !== "Ok") return r;
+			try {
+				return okRes(f(r.value));
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
+	flatMap(f) {
+		return new AsyncRes(this.promise.then(async (r) => {
+			if (r.tag !== "Ok") return r;
+			try {
+				return await f(r.value);
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
+	tap(f) {
+		return new AsyncRes(this.promise.then((r) => {
+			if (r.tag !== "Ok") return r;
+			try {
+				f(r.value);
+				return r;
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
+	as(value) {
+		return new AsyncRes(this.promise.then((r) => r.tag === "Ok" ? okRes(value) : r));
+	}
+	mapErr(f) {
+		return new AsyncRes(this.promise.then((r) => {
+			if (r.tag !== "Err") return r;
+			try {
+				return errRes(f(r.error));
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
+	orElse(f) {
+		return new AsyncRes(this.promise.then(async (r) => {
+			if (r.tag !== "Err") return r;
+			try {
+				return await f(r.error);
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
+	recover(f) {
+		return new AsyncRes(this.promise.then((r) => {
+			if (r.tag !== "Err") return r;
+			try {
+				return okRes(f(r.error));
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
+	tapErr(f) {
+		return new AsyncRes(this.promise.then((r) => {
+			if (r.tag !== "Err") return r;
+			try {
+				f(r.error);
+				return r;
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
+	recoverDefect(f) {
+		return new AsyncRes(this.promise.then(async (r) => {
+			if (r.tag !== "Defect") return r;
+			try {
+				return await f(r.cause);
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
+	tapDefect(f) {
+		return new AsyncRes(this.promise.then((r) => {
+			if (r.tag !== "Defect") return r;
+			try {
+				f(r.cause);
+				return r;
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
+	match(cases) {
+		return this.promise.then((r) => r.match(cases));
+	}
+	unwrap() {
+		return this.promise.then((r) => r.unwrap());
+	}
+	unwrapErr() {
+		return this.promise.then((r) => r.unwrapErr());
+	}
+	unwrapOr(fallback) {
+		return this.promise.then((r) => r.unwrapOr(fallback));
+	}
+	unwrapOrElse(f) {
+		return this.promise.then((r) => {
+			if (r.tag === "Ok") return r.value;
+			if (r.tag === "Defect") throw r.cause;
+			return f(r.error);
+		});
+	}
+	getOrNull() {
+		return this.promise.then((r) => r.getOrNull());
+	}
+	getOrUndefined() {
+		return this.promise.then((r) => r.getOrUndefined());
+	}
+};
+//#endregion
+//#region src/constructors.ts
+/**
+* Construct a successful {@link Result}.
+*
+* @typeParam T - the success value type.
+* @param value - the success value to wrap.
+*
+* @example
+* ```ts
+* import { ok } from "unthrown";
+* ok(42).unwrap(); // 42
+* ```
+*/
+function ok(value) {
+	return okRes(value);
+}
+/**
+* Construct a failed {@link Result} carrying a **modeled** error.
+*
+* @typeParam E - the modeled error type.
+* @param error - the domain error to wrap.
+*
+* @example
+* ```ts
+* import { err } from "unthrown";
+* err("not_found").unwrapErr(); // "not_found"
+* ```
+*/
+function err(error) {
+	return errRes(error);
+}
+/**
+* Type guard: narrow a {@link Result} to its `Ok` variant, exposing `.value`.
+*
+* @returns `true` when `r` is `Ok`.
+*
+* @example
+* ```ts
+* import { isOk, type Result } from "unthrown";
+* declare const r: Result<number, string>;
+* if (isOk(r)) r.value; // number, narrowed
+* ```
+*/
+function isOk(r) {
+	return r.tag === "Ok";
+}
+/**
+* Type guard: narrow a {@link Result} to its `Err` variant, exposing `.error`.
+*
+* @returns `true` when `r` is `Err`.
+*/
+function isErr(r) {
+	return r.tag === "Err";
+}
+/**
+* Type guard: narrow a {@link Result} to its `Defect` variant, exposing `.cause`.
+*
+* @returns `true` when `r` is a `Defect`.
+*/
+function isDefect(r) {
+	return r.tag === "Defect";
+}
+//#endregion
+//#region src/defect.ts
+const DEFECT = Symbol("unthrown/defect");
+/**
+* Wrap a cause as a {@link Defect} — the value you return from a `qualify`
+* function when a failure is **not** a modeled domain error.
+*
+* @param cause - the original thrown/rejected value.
+* @returns an opaque defect marker carrying `cause`.
+*
+* @example
+* ```ts
+* import { fromPromise, defect } from "unthrown";
+*
+* const user = fromPromise(fetchUser(id), (cause) =>
+*   cause instanceof NotFoundError ? cause : defect(cause),
+* );
+* ```
+*/
+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**
+* `Err`. The sanctioned alternative to an `Option` type.
+*
+* @remarks
+* `null` and `undefined` map to `err(onAbsent())`; any other value (including
+* falsy ones like `0`, `""`, `false`) maps to `Ok`.
+*
+* @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.
+*
+* @example
+* ```ts
+* import { fromNullable } from "unthrown";
+* fromNullable(map.get(key), () => "missing").unwrap();
+* ```
+*/
+function fromNullable(value, onAbsent) {
+	return value === null || value === void 0 ? err(onAbsent()) : ok(value);
+}
+/**
+* Wrap a throwing synchronous function so it returns a {@link Result} instead of
+* throwing.
+*
+* @remarks
+* `qualify` **must** triage every thrown cause into a modeled error `E` or a
+* {@link Defect} (via {@link defect}) — there is no path that leaves `unknown`
+* in `E`. A throw inside `qualify` itself is treated as a `Defect`.
+*
+* @typeParam A - the wrapped function's argument tuple.
+* @typeParam T - the wrapped function's return type.
+* @typeParam E - the modeled error type.
+* @param fn - the throwing function to wrap.
+* @param qualify - triages a thrown cause into `E` or a `Defect`.
+* @returns a function with the same arguments returning `Result<T, E>`.
+*
+* @example
+* ```ts
+* import { fromThrowable, defect } from "unthrown";
+* const parse = fromThrowable(JSON.parse, (cause) => defect(cause));
+* parse("{}").unwrap();
+* ```
+*/
+function fromThrowable(fn, qualify) {
+	return (...args) => {
+		try {
+			return ok(fn(...args));
+		} catch (cause) {
+			return qualifyToResult(cause, qualify);
+		}
+	};
+}
+/**
+* Wrap a `Promise` (or a thunk producing one) as an {@link AsyncResult}, forcing
+* every rejection to be triaged.
+*
+* @remarks
+* `qualify` **must** map each rejection cause into a modeled error `E` or a
+* {@link Defect}. The returned `AsyncResult`'s internal promise never rejects;
+* `await`-ing it always yields a `Result`. A throw inside `qualify` is itself a
+* `Defect`.
+*
+* @typeParam T - the resolved value type.
+* @typeParam E - the modeled error type.
+* @param promise - the promise, or a thunk returning one.
+* @param qualify - triages a rejection cause into `E` or a `Defect`.
+*
+* @example
+* ```ts
+* import { fromPromise, defect } from "unthrown";
+* const user = await fromPromise(fetchUser(id), (cause) =>
+*   cause instanceof NotFoundError ? ("not_found" as const) : defect(cause),
+* );
+* ```
+*/
+function fromPromise(promise, qualify) {
+	return new AsyncRes((typeof promise === "function" ? Promise.resolve().then(promise) : promise).then((value) => okRes(value), (cause) => qualifyToResult(cause, qualify)));
+}
+/**
+* Wrap a `Promise` asserted **not** to fail in any modeled way: any rejection
+* becomes a `Defect`.
+*
+* @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.)
+*
+* @typeParam T - the resolved value type.
+* @param promise - the promise, or a thunk returning one.
+*/
+function fromSafePromise(promise) {
+	return new AsyncRes((typeof promise === "function" ? Promise.resolve().then(promise) : promise).then((value) => okRes(value), (cause) => defectRes(cause)));
+}
+function qualifyToResult(cause, qualify) {
+	try {
+		const q = qualify(cause);
+		return isDefectMarker(q) ? defectRes(q.cause) : errRes(q);
+	} catch (qErr) {
+		return defectRes(qErr);
+	}
+}
+/**
+* Collect a tuple of {@link Result}s into a single `Result` of the tuple of
+* success values.
+*
+* @remarks
+* Short-circuits on the **first** `Err` (later entries are not inspected for
+* their error); any `Defect` present **dominates**, winning even over an earlier
+* `Err`. Positional types are preserved, so `all([ok(1), ok("a")])` is
+* `Result<[number, string], …>`.
+*
+* @typeParam Rs - the tuple of input `Result` types.
+* @param results - the results to combine.
+*
+* @example
+* ```ts
+* import { all, ok } from "unthrown";
+* all([ok(1), ok("a"), ok(true)]).unwrap(); // [1, "a", true]
+* ```
+*/
+function all(results) {
+	const values = [];
+	let firstErr;
+	let firstDefect;
+	for (const r of results) if (r.tag === "Defect") firstDefect ??= r;
+	else if (r.tag === "Err") firstErr ??= r;
+	else values.push(r.value);
+	if (firstDefect) return firstDefect;
+	if (firstErr) return firstErr;
+	return ok(values);
+}
+//#endregion
+//#region src/facade.ts
+/**
+* Companion object grouping the standalone entry points under a single,
+* discoverable namespace: {@link Result.ok}, {@link Result.err},
+* {@link Result.defect}, {@link Result.fromNullable}, {@link Result.fromThrowable},
+* {@link Result.fromPromise}, {@link Result.fromSafePromise}, {@link Result.all},
+* {@link Result.isOk}, {@link Result.isErr}, {@link Result.isDefect}.
+*
+* @remarks
+* Purely additive sugar — each member **is** the corresponding free function.
+* The free functions remain the primary, tree-shakeable API; importing only
+* `{ ok }` never pulls this object in. The value `Result` and the type
+* {@link Result} share one name (the companion-object pattern).
+*
+* @example
+* ```ts
+* import { Result } from "unthrown";
+* Result.ok(1).flatMap((n) => Result.ok(n + 1)).unwrap(); // 2
+* ```
+*/
+const Result = {
+	ok,
+	err,
+	defect,
+	fromNullable,
+	fromThrowable,
+	fromPromise,
+	fromSafePromise,
+	all,
+	isOk,
+	isErr,
+	isDefect
+};
+//#endregion
+//#region src/tagged.ts
+/**
+* Build a base class for a tagged error — a class extending `Error` with a
+* `_tag` string discriminant, in the style of Effect's `Data.TaggedError`.
+*
+* @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
+* `tag` and cannot be overridden by the payload.
+*
+* @typeParam Tag - the string literal discriminant.
+* @param tag - the discriminant value, also used as the error `name`.
+*
+* @example
+* ```ts
+* class NotFound extends TaggedError("NotFound") {}
+* class HttpError extends TaggedError("HttpError")<{ status: number }> {}
+*
+* new NotFound()._tag; // "NotFound"
+* new HttpError({ status: 500 }).status; // 500
+* ```
+*/
+function TaggedError(tag) {
+	class TaggedErrorBase extends Error {
+		_tag;
+		constructor(props) {
+			super(typeof props?.["message"] === "string" ? props["message"] : void 0);
+			if (props) Object.assign(this, props);
+			this._tag = tag;
+			this.name = tag;
+			Object.setPrototypeOf(this, new.target.prototype);
+		}
+	}
+	return TaggedErrorBase;
+}
+function matchTags(result, handlers) {
+	const onErr = (error) => {
+		const handler = handlers[error._tag];
+		return handler(error);
+	};
+	return result.match({
+		ok: handlers.Ok,
+		err: onErr,
+		defect: handlers.Defect
+	});
+}
+//#endregion
+exports.Result = Result;
+exports.TaggedError = TaggedError;
+exports.UnwrapError = UnwrapError;
+exports.all = all;
+exports.defect = defect;
+exports.err = err;
+exports.fromNullable = fromNullable;
+exports.fromPromise = fromPromise;
+exports.fromSafePromise = fromSafePromise;
+exports.fromThrowable = fromThrowable;
+exports.isDefect = isDefect;
+exports.isErr = isErr;
+exports.isOk = isOk;
+exports.matchTags = matchTags;
+exports.ok = ok;