unthrown 0.3.0 → 1.1.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) {
@@ -61,17 +61,41 @@ var Res = class {
 		if (this.tag !== "Ok") return this;
 		try {
 			const r = f(this.value);
-			return r.tag === "Ok" ? this : r;
+			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 this;
+		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) {
@@ -79,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) {
@@ -87,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) {
@@ -103,6 +127,15 @@ var Res = class {
 			return defectRes(cause);
 		}
 	}
+	flatTapErr(f) {
+		if (this.tag !== "Err") return this;
+		try {
+			const r = f(this.error);
+			return r.tag === "Ok" ? this : passThrough(r);
+		} catch (cause) {
+			return defectRes(cause);
+		}
+	}
 	recoverDefect(f) {
 		if (this.tag !== "Defect") return this;
 		try {
@@ -208,6 +241,56 @@ function defectRes(cause) {
 	});
 }
 /**
+* Type guard: is `x` a {@link Result} (any of `Ok` / `Err` / `Defect`)?
+*
+* @remarks
+* Unlike {@link isOk} / {@link isErr} / {@link isDefect}, which narrow a value
+* already known to be a `Result`, this narrows from `unknown` — useful at an
+* untyped boundary. It checks the value carries the `Result` prototype, so a
+* look-alike plain object (`{ tag: "Ok" }`) is **not** matched. An `AsyncResult`
+* is not a `Result` and returns `false`.
+*
+* @returns `true` when `x` is a `Result` produced by this library.
+*/
+function isResult(x) {
+	return x instanceof Res;
+}
+/**
+* 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`.
@@ -224,7 +307,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) {
@@ -234,7 +317,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) {
@@ -255,21 +338,49 @@ var AsyncRes = class AsyncRes {
 	}
 	flatTap(f) {
 		return new AsyncRes(this.promise.then(async (r) => {
-			if (r.tag !== "Ok") return 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);
-				return inner.tag === "Ok" ? r : inner;
+				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) {
@@ -279,7 +390,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) {
@@ -289,7 +400,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) {
@@ -308,6 +419,17 @@ var AsyncRes = class AsyncRes {
 			}
 		}));
 	}
+	flatTapErr(f) {
+		return new AsyncRes(this.promise.then(async (r) => {
+			if (r.tag !== "Err") return passThrough(r);
+			try {
+				const inner = await f(r.error);
+				return inner.tag === "Ok" ? passThrough(r) : passThrough(inner);
+			} catch (cause) {
+				return defectRes(cause);
+			}
+		}));
+	}
 	recoverDefect(f) {
 		return new AsyncRes(this.promise.then(async (r) => {
 			if (r.tag !== "Defect") return r;
@@ -365,11 +487,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);
 }
 /**
@@ -380,11 +502,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);
 }
 /**
@@ -420,24 +542,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
@@ -454,13 +576,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.
@@ -475,7 +624,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
@@ -483,14 +632,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.
@@ -502,8 +651,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();
 * ```
 */
@@ -511,7 +660,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);
 		}
@@ -529,8 +678,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
@@ -540,9 +689,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),
 * );
 * ```
 */
@@ -586,7 +735,7 @@ function foldArray(results) {
 	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);
+	return firstDefect ?? firstErr ?? Ok(values);
 }
 /**
 * Fold a record of settled `Result`s with the same rules, else `Ok` of the
@@ -607,7 +756,7 @@ function foldRecord(results) {
 		writable: true,
 		configurable: true
 	});
-	return firstDefect ?? firstErr ?? ok(values);
+	return firstDefect ?? firstErr ?? Ok(values);
 }
 /**
 * Collect a tuple/array of {@link Result}s into a single `Result` of all their
@@ -616,16 +765,16 @@ function foldRecord(results) {
 * @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. 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) {
@@ -643,8 +792,8 @@ function all(results) {
 *
 * @example
 * ```ts
-* import { allFromDict, ok } from "unthrown";
-* allFromDict({ id: ok(1), name: ok("ada") }).unwrap(); // { id: 1, name: "ada" }
+* import { allFromDict, Ok } from "unthrown";
+* allFromDict({ id: Ok(1), name: Ok("ada") }).unwrap(); // { id: 1, name: "ada" }
 * ```
 */
 function allFromDict(results) {
@@ -697,29 +846,30 @@ function allFromDictAsync(results) {
 //#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.allFromDict},
 * {@link Result.allFromDictAsync}, {@link Result.isOk}, {@link Result.isErr},
-* {@link Result.isDefect}.
+* {@link Result.isDefect}, {@link Result.isResult}.
 *
 * @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,
@@ -730,7 +880,8 @@ const Result = {
 	allFromDictAsync,
 	isOk,
 	isErr,
-	isDefect
+	isDefect,
+	isResult
 };
 //#endregion
 //#region src/tagged.ts
@@ -800,6 +951,10 @@ 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;
@@ -807,8 +962,6 @@ exports.all = all;
 exports.allAsync = allAsync;
 exports.allFromDict = allFromDict;
 exports.allFromDictAsync = allFromDictAsync;
-exports.defect = defect;
-exports.err = err;
 exports.fromNullable = fromNullable;
 exports.fromPromise = fromPromise;
 exports.fromSafePromise = fromSafePromise;
@@ -816,5 +969,5 @@ exports.fromThrowable = fromThrowable;
 exports.isDefect = isDefect;
 exports.isErr = isErr;
 exports.isOk = isOk;
+exports.isResult = isResult;
 exports.matchTags = matchTags;
-exports.ok = ok;