unthrown 0.2.0 → 1.0.0

package/README.md

@@ -11,10 +11,10 @@ pnpm add unthrown
 ```
 
 ```ts
-import { ok, err, fromPromise, defect, type Result } from "unthrown";
+import { Ok, Err, fromPromise, Defect, type Result } from "unthrown";
 
 const user = fromPromise(fetchUser(id), (cause) =>
-  cause instanceof NotFoundError ? new NotFound() : defect(cause),
+  cause instanceof NotFoundError ? new NotFound() : Defect(cause),
 );
 
 const status = await user.match({

package/dist/index.cjs

@@ -33,7 +33,7 @@ var UnwrapError = class extends Error {
 */
 var Res = class {
 	map(f) {
-		if (this.tag !== "Ok") return this;
+		if (this.tag !== "Ok") return passThrough(this);
 		try {
 			return okRes(f(this.value));
 		} catch (cause) {
@@ -41,7 +41,7 @@ var Res = class {
 		}
 	}
 	flatMap(f) {
-		if (this.tag !== "Ok") return this;
+		if (this.tag !== "Ok") return passThrough(this);
 		try {
 			return f(this.value);
 		} catch (cause) {
@@ -57,12 +57,45 @@ var Res = class {
 			return defectRes(cause);
 		}
 	}
-	as(value) {
+	flatTap(f) {
 		if (this.tag !== "Ok") return this;
+		try {
+			const r = f(this.value);
+			return r.tag === "Ok" ? this : passThrough(r);
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	bind(name, f) {
+		if (this.tag !== "Ok") return passThrough(this);
+		try {
+			const r = f(this.value);
+			if (r.tag !== "Ok") return passThrough(r);
+			return okRes({
+				...scopeOf(this.value),
+				[name]: r.value
+			});
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	let(name, f) {
+		if (this.tag !== "Ok") return passThrough(this);
+		try {
+			return okRes({
+				...scopeOf(this.value),
+				[name]: f(this.value)
+			});
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
+	as(value) {
+		if (this.tag !== "Ok") return passThrough(this);
 		return okRes(value);
 	}
 	mapErr(f) {
-		if (this.tag !== "Err") return this;
+		if (this.tag !== "Err") return passThrough(this);
 		try {
 			return errRes(f(this.error));
 		} catch (cause) {
@@ -70,7 +103,7 @@ var Res = class {
 		}
 	}
 	orElse(f) {
-		if (this.tag !== "Err") return this;
+		if (this.tag !== "Err") return passThrough(this);
 		try {
 			return f(this.error);
 		} catch (cause) {
@@ -78,7 +111,7 @@ var Res = class {
 		}
 	}
 	recover(f) {
-		if (this.tag !== "Err") return this;
+		if (this.tag !== "Err") return passThrough(this);
 		try {
 			return okRes(f(this.error));
 		} catch (cause) {
@@ -199,6 +232,41 @@ function defectRes(cause) {
 	});
 }
 /**
+* Reuse a non-matching variant (an `Err` or `Defect`) as a differently-typed
+* `Result`, with no runtime work. Sound because the passed-through variant
+* carries no value of the changed success type, so retyping it is a no-op — only
+* the phantom type parameter moves. This is the single sanctioned home for that
+* assertion (the same one boxed applies inline at every pass-through); every
+* combinator's short-circuit branch funnels through here instead of casting.
+*
+* @internal
+*/
+function passThrough(self) {
+	return self;
+}
+/**
+* Validate that a `bind`/`let` scope is a real (non-null) object before merging a
+* key into it.
+*
+* @remarks
+* Do-notation accumulates an **object** scope: a chain starts at `Do()` (an
+* empty object) and every `bind`/`let` returns an object, so in typed code the
+* scope is always an object. The method lives on the general `Result` surface,
+* though, so a primitive `Ok` (e.g. `Ok(5).bind(...)`, or a chain whose value was
+* `map`-ped away from its scope) could reach it. Rather than let `{ ...5 }`
+* silently collapse to `{}` and drop the prior scope, we throw here — the
+* surrounding `try` turns it into a {@link Defect}, surfacing the misuse as the
+* bug it is (a defect is a bug, not an absent value). A `this: object` constraint
+* was rejected: TypeScript does not hard-enforce a constraint inferred solely
+* from `this`, and it breaks `AsyncRes implements AsyncResult`.
+*
+* @internal
+*/
+function scopeOf(value) {
+	if (typeof value !== "object" || value === null) throw new TypeError("bind/let requires an object scope — start a do-chain with Do()");
+	return value;
+}
+/**
 * 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`.
@@ -215,7 +283,7 @@ var AsyncRes = class AsyncRes {
 	}
 	map(f) {
 		return new AsyncRes(this.promise.then((r) => {
-			if (r.tag !== "Ok") return r;
+			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				return okRes(f(r.value));
 			} catch (cause) {
@@ -225,7 +293,7 @@ var AsyncRes = class AsyncRes {
 	}
 	flatMap(f) {
 		return new AsyncRes(this.promise.then(async (r) => {
-			if (r.tag !== "Ok") return r;
+			if (r.tag !== "Ok") return passThrough(r);
 			try {
 				return await f(r.value);
 			} catch (cause) {
@@ -244,12 +312,51 @@ var AsyncRes = class AsyncRes {
 			}
 		}));
 	}
+	flatTap(f) {
+		return new AsyncRes(this.promise.then(async (r) => {
+			if (r.tag !== "Ok") return passThrough(r);
+			try {
+				const inner = await f(r.value);
+				return inner.tag === "Ok" ? r : passThrough(inner);
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
+	bind(name, f) {
+		return new AsyncRes(this.promise.then(async (r) => {
+			if (r.tag !== "Ok") return passThrough(r);
+			try {
+				const inner = await f(r.value);
+				if (inner.tag !== "Ok") return passThrough(inner);
+				return okRes({
+					...scopeOf(r.value),
+					[name]: inner.value
+				});
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
+	let(name, f) {
+		return new AsyncRes(this.promise.then((r) => {
+			if (r.tag !== "Ok") return passThrough(r);
+			try {
+				return okRes({
+					...scopeOf(r.value),
+					[name]: f(r.value)
+				});
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
 	as(value) {
-		return new AsyncRes(this.promise.then((r) => r.tag === "Ok" ? okRes(value) : r));
+		return new AsyncRes(this.promise.then((r) => r.tag === "Ok" ? okRes(value) : passThrough(r)));
 	}
 	mapErr(f) {
 		return new AsyncRes(this.promise.then((r) => {
-			if (r.tag !== "Err") return r;
+			if (r.tag !== "Err") return passThrough(r);
 			try {
 				return errRes(f(r.error));
 			} catch (cause) {
@@ -259,7 +366,7 @@ var AsyncRes = class AsyncRes {
 	}
 	orElse(f) {
 		return new AsyncRes(this.promise.then(async (r) => {
-			if (r.tag !== "Err") return r;
+			if (r.tag !== "Err") return passThrough(r);
 			try {
 				return await f(r.error);
 			} catch (cause) {
@@ -269,7 +376,7 @@ var AsyncRes = class AsyncRes {
 	}
 	recover(f) {
 		return new AsyncRes(this.promise.then((r) => {
-			if (r.tag !== "Err") return r;
+			if (r.tag !== "Err") return passThrough(r);
 			try {
 				return okRes(f(r.error));
 			} catch (cause) {
@@ -345,11 +452,11 @@ var AsyncRes = class AsyncRes {
 *
 * @example
 * ```ts
-* import { ok } from "unthrown";
-* ok(42).unwrap(); // 42
+* import { Ok } from "unthrown";
+* Ok(42).unwrap(); // 42
 * ```
 */
-function ok(value) {
+function Ok(value) {
 	return okRes(value);
 }
 /**
@@ -360,11 +467,11 @@ function ok(value) {
 *
 * @example
 * ```ts
-* import { err } from "unthrown";
-* err("not_found").unwrapErr(); // "not_found"
+* import { Err } from "unthrown";
+* Err("not_found").unwrapErr(); // "not_found"
 * ```
 */
-function err(error) {
+function Err(error) {
 	return errRes(error);
 }
 /**
@@ -400,24 +507,24 @@ function isDefect(r) {
 }
 //#endregion
 //#region src/defect.ts
-const DEFECT = Symbol("unthrown/defect");
+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`.
+* @returns an opaque Defect marker carrying `cause`.
 *
 * @example
 * ```ts
-* import { fromPromise, defect } from "unthrown";
+* import { fromPromise, Defect } from "unthrown";
 *
 * const user = fromPromise(fetchUser(id), (cause) =>
-*   cause instanceof NotFoundError ? cause : defect(cause),
+*   cause instanceof NotFoundError ? cause : Defect(cause),
 * );
 * ```
 */
-function defect(cause) {
+function Defect(cause) {
 	return {
 		[DEFECT]: true,
 		cause
@@ -434,13 +541,40 @@ function isDefectMarker(x) {
 	return typeof x === "object" && x !== null && x[DEFECT] === true;
 }
 //#endregion
+//#region src/do.ts
+/**
+* Start a do-notation chain with an empty object scope, grown step by step with
+* `bind` (for `Result`-returning steps) and `let` (for pure values).
+*
+* @remarks
+* Capitalised because `do` is a reserved word. Each step receives the scope
+* accumulated so far; the error types union across `bind`s, and a throw in any
+* step becomes a `Defect`. To go asynchronous, lift the chain with `toAsync()`
+* (then a `bind` may return an `AsyncResult`).
+*
+* @example
+* ```ts
+* import { Do, Ok } from "unthrown";
+*
+* const result = Do()
+*   .bind("user", () => findUser(id)) // Result<User, NotFound>
+*   .bind("org", ({ user }) => findOrg(user.orgId)) // Result<Org, NotFound>
+*   .let("label", ({ user, org }) => `${user.name} @ ${org.name}`)
+*   .map(({ user, org, label }) => render(user, org, label));
+* // Result<View, NotFound>
+* ```
+*/
+function Do() {
+	return Ok({});
+}
+//#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
+* `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.
@@ -455,7 +589,7 @@ function isDefectMarker(x) {
 * ```
 */
 function fromNullable(value, onAbsent) {
-	return value === null || value === void 0 ? err(onAbsent()) : ok(value);
+	return value === null || value === void 0 ? Err(onAbsent()) : Ok(value);
 }
 /**
 * Wrap a throwing synchronous function so it returns a {@link Result} instead of
@@ -463,14 +597,14 @@ function fromNullable(value, onAbsent) {
 *
 * @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`
+* {@link Defect} (via {@link Defect}) — there is no path that leaves `unknown`
 * in `E`. A throw inside `qualify` itself is treated as a `Defect`.
 *
 * The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
 * `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
+* `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 fromSafePromise} when every failure is a Defect.
 *
 * @typeParam A - the wrapped function's argument tuple.
 * @typeParam T - the wrapped function's return type.
@@ -482,8 +616,8 @@ function fromNullable(value, onAbsent) {
 *
 * @example
 * ```ts
-* import { fromThrowable, defect } from "unthrown";
-* const parse = fromThrowable(JSON.parse, (cause) => defect(cause));
+* import { fromThrowable, Defect } from "unthrown";
+* const parse = fromThrowable(JSON.parse, (cause) => Defect(cause));
 * parse("{}").unwrap();
 * ```
 */
@@ -491,7 +625,7 @@ function fromThrowable(fn, qualify) {
 	const triage = qualify;
 	return (...args) => {
 		try {
-			return ok(fn(...args));
+			return Ok(fn(...args));
 		} catch (cause) {
 			return qualifyToResult(cause, triage);
 		}
@@ -509,8 +643,8 @@ function fromThrowable(fn, qualify) {
 *
 * The modeled error type is `Exclude<R, Defect>` — the `Defect` arm of
 * `qualify`'s return is **subtracted** from `E`, never inferred into it. So a
-* `qualify` that returns *only* `defect(cause)` yields `E = never`; when every
-* rejection is a defect, prefer {@link fromSafePromise}.
+* `qualify` that returns *only* `Defect(cause)` yields `E = never`; when every
+* rejection is a Defect, prefer {@link fromSafePromise}.
 *
 * @typeParam T - the resolved value type.
 * @typeParam R - `qualify`'s return type; the modeled error `E` is
@@ -520,9 +654,9 @@ function fromThrowable(fn, qualify) {
 *
 * @example
 * ```ts
-* import { fromPromise, defect } from "unthrown";
+* import { fromPromise, Defect } from "unthrown";
 * const user = await fromPromise(fetchUser(id), (cause) =>
-*   cause instanceof NotFoundError ? ("not_found" as const) : defect(cause),
+*   cause instanceof NotFoundError ? ("not_found" as const) : Defect(cause),
 * );
 * ```
 */
@@ -554,92 +688,161 @@ function qualifyToResult(cause, qualify) {
 	}
 }
 /**
-* Collect {@link Result}s into a single `Result` of all their success values.
+* Fold an array of settled `Result`s: first `Err` wins, any `Defect` dominates,
+* else `Ok` of the values array.
+*
+* @internal
+*/
+function foldArray(results) {
+	let firstErr;
+	let firstDefect;
+	const values = [];
+	for (const r of results) if (r.tag === "Defect") firstDefect ??= r;
+	else if (r.tag === "Err") firstErr ??= r;
+	else values.push(r.value);
+	return firstDefect ?? firstErr ?? Ok(values);
+}
+/**
+* Fold a record of settled `Result`s with the same rules, else `Ok` of the
+* record of values. Keys are written with `Object.defineProperty` so a
+* caller-supplied `"__proto__"` key cannot pollute the prototype.
+*
+* @internal
+*/
+function foldRecord(results) {
+	let firstErr;
+	let firstDefect;
+	const values = {};
+	for (const [key, r] of Object.entries(results)) if (r.tag === "Defect") firstDefect ??= r;
+	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);
+}
+/**
+* Collect a tuple/array of {@link Result}s into a single `Result` of all their
+* 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`. A **fixed tuple** keeps its positional types — `all([ok(1), ok("a")])`
+* `Err`. A **fixed tuple** keeps its positional types — `all([Ok(1), Ok("a")])`
 * is `Result<[number, string], …>` — while a **dynamic array** `Result<T, E>[]`
-* collapses to `Result<T[], E>` with no cast.
-*
-* @typeParam Rs - the tuple/array of input `Result` types.
-* @param results - the results to combine.
+* collapses to `Result<T[], E>` with no cast. For a **record** keyed by name,
+* use {@link allFromDict}.
 *
 * @example
 * ```ts
-* import { all, ok } from "unthrown";
-* all([ok(1), ok("a"), ok(true)]).unwrap(); // [1, "a", true] (typed [number, string, boolean])
-* all([ok(1), ok(2)] as Result<number, never>[]).unwrap(); // number[]
+* import { all, Ok } from "unthrown";
+* all([Ok(1), Ok("a"), Ok(true)]).unwrap(); // [1, "a", true] (typed [number, string, boolean])
+* all([Ok(1), Ok(2)] as Result<number, never>[]).unwrap(); // number[]
 * ```
 */
 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);
+	return foldArray(results);
 }
 /**
-* The asynchronous counterpart of {@link all}: combine {@link AsyncResult}s into
-* one `AsyncResult` of all their success values.
+* Collect a **record** of {@link Result}s into a single `Result` of a record of
+* their success values — `allFromDict({ a: Result<A, E>, b: Result<B, E> })` is
+* `Result<{ a: A; b: B }, E>`. The named counterpart of {@link all}, for
+* parallel work you'd rather not tuple.
 *
 * @remarks
-* The inputs are resolved **concurrently** (their order is preserved); the
-* resolved `Result`s are then folded with the same rules as {@link all} —
-* first `Err` short-circuits, any `Defect` dominates. As ever, the returned
-* `AsyncResult`'s internal promise never rejects. A **fixed tuple** keeps its
-* positional types; a **dynamic array** `AsyncResult<T, E>[]` collapses to
-* `AsyncResult<T[], E>`.
+* Same folding rules as {@link all}: first `Err` short-circuits, any `Defect`
+* dominates. This is **not** error accumulation.
+*
+* @example
+* ```ts
+* import { allFromDict, Ok } from "unthrown";
+* allFromDict({ id: Ok(1), name: Ok("ada") }).unwrap(); // { id: 1, name: "ada" }
+* ```
+*/
+function allFromDict(results) {
+	return foldRecord(results);
+}
+/**
+* The asynchronous counterpart of {@link all}: combine a tuple/array of
+* {@link AsyncResult}s into one `AsyncResult` of all their success values.
 *
-* @typeParam Rs - the tuple/array of input `AsyncResult` types.
-* @param results - the async results to combine.
+* @remarks
+* The inputs are resolved **concurrently** (order preserved); the resolved
+* `Result`s are then folded with the same rules as {@link all} — first `Err`
+* short-circuits, any `Defect` dominates. As ever, the returned `AsyncResult`'s
+* internal promise never rejects. For a **record**, use {@link allFromDictAsync}.
 *
 * @example
 * ```ts
 * import { allAsync, fromSafePromise } from "unthrown";
-* const both = await allAsync([fromSafePromise(a()), fromSafePromise(b())]);
+* await allAsync([fromSafePromise(a()), fromSafePromise(b())]);
 * ```
 */
 function allAsync(results) {
-	return new AsyncRes(Promise.all(results).then((resolved) => all(resolved)));
+	return new AsyncRes(Promise.all(results).then((resolved) => foldArray(resolved)));
+}
+/**
+* The asynchronous counterpart of {@link allFromDict}: combine a record of
+* {@link AsyncResult}s into one `AsyncResult` of a record of their values.
+*
+* @remarks
+* Resolved concurrently (order preserved), folded with the {@link all} rules,
+* and the internal promise never rejects.
+*
+* @example
+* ```ts
+* import { allFromDictAsync, fromSafePromise } from "unthrown";
+* await allFromDictAsync({ a: fromSafePromise(a()), b: fromSafePromise(b()) });
+* ```
+*/
+function allFromDictAsync(results) {
+	const entries = Object.entries(results);
+	return new AsyncRes(Promise.all(entries.map(([, ar]) => ar)).then((resolved) => {
+		const byKey = Object.create(null);
+		entries.forEach(([key], i) => {
+			byKey[key] = resolved[i];
+		});
+		return foldRecord(byKey);
+	}));
 }
 //#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},
+* 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.allAsync}, {@link Result.isOk}, {@link Result.isErr},
+* {@link Result.allAsync}, {@link Result.allFromDict},
+* {@link Result.allFromDictAsync}, {@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
+* `{ 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
+* Result.Ok(1).flatMap((n) => Result.Ok(n + 1)).unwrap(); // 2
 * ```
 */
 const Result = {
-	ok,
-	err,
-	defect,
+	Ok,
+	Err,
+	Defect,
+	Do,
 	fromNullable,
 	fromThrowable,
 	fromPromise,
 	fromSafePromise,
 	all,
 	allAsync,
+	allFromDict,
+	allFromDictAsync,
 	isOk,
 	isErr,
 	isDefect
@@ -712,13 +915,17 @@ function matchTags(result, handlers) {
 	});
 }
 //#endregion
+exports.Defect = Defect;
+exports.Do = Do;
+exports.Err = Err;
+exports.Ok = Ok;
 exports.Result = Result;
 exports.TaggedError = TaggedError;
 exports.UnwrapError = UnwrapError;
 exports.all = all;
 exports.allAsync = allAsync;
-exports.defect = defect;
-exports.err = err;
+exports.allFromDict = allFromDict;
+exports.allFromDictAsync = allFromDictAsync;
 exports.fromNullable = fromNullable;
 exports.fromPromise = fromPromise;
 exports.fromSafePromise = fromSafePromise;
@@ -727,4 +934,3 @@ exports.isDefect = isDefect;
 exports.isErr = isErr;
 exports.isOk = isOk;
 exports.matchTags = matchTags;
-exports.ok = ok;