@shirudo/result 0.0.2 → 0.0.4

package/README.md

@@ -263,6 +263,8 @@ const result = await matchAsync({
 - `.serialize()`: Convert to `{ isSuccess, data?, error? }`.
 - `.toUserFriendly()`: User-friendly serialization with error messages.
 
+**Error types:** Methods that throw (e.g., `.unwrap()`, `.unwrapErr()`, `.expect()`, `.expectErr()`, and invalid-state checks) now use custom error classes with stable `code` values like `ERR_UNWRAP_ON_ERR` and `ERR_INVALID_STATE`. These classes and constants are exported from the package for programmatic handling.
+
 ### Utilities
 
 Type guards and helper functions:
@@ -350,7 +352,7 @@ swap(err("error")); // Ok("error")
 - `sequenceRecord(record)`: Like `sequence`, but for objects (`{ a: Result, b: Result }` → `Result<{ a, b }>`).
 - `collectFirstOk(results)`: Find the first success, or return all errors.
 - `collectFirstOkAsync(results)`: Async version - find the first success.
-- `collectFirstOkRaceAsync(results)`: Race variant - first success wins, all rejections continue.
+- `collectFirstOkParallelAsync(results)`: Parallel variant - first success wins, all rejections continue.
 - `collectAllErrors(results)`: Returns `Ok(values)` only if all are Ok, otherwise collects _all_ errors.
 - `partition(results)`: Separate a list into arrays of `[oks, errs]`.
 - `flatten(result)`: Flattens a nested `Result<Result<T, E>, E>` into `Result<T, E>`.

package/dist/index.cjs

@@ -13,6 +13,88 @@ var Pipeable = class {
 	}
 };
 
+//#endregion
+//#region src/errors.ts
+const ERR_INVALID_STATE = "ERR_INVALID_STATE";
+const ERR_TASK_YIELD_NOT_RESULT = "ERR_TASK_YIELD_NOT_RESULT";
+const ERR_MATCH_ON_OK = "ERR_MATCH_ON_OK";
+const ERR_UNWRAP_ON_ERR = "ERR_UNWRAP_ON_ERR";
+const ERR_UNWRAP_ERR_ON_OK = "ERR_UNWRAP_ERR_ON_OK";
+const ERR_EXPECT_OK = "ERR_EXPECT_OK";
+const ERR_EXPECT_ERR = "ERR_EXPECT_ERR";
+const formatResultErrorMessage = (code, message, context) => {
+	if (context) return `${code}: ${message} (context: ${context})`;
+	return `${code}: ${message}`;
+};
+var ResultError = class extends Error {
+	code;
+	context;
+	constructor(message, code, context) {
+		super(formatResultErrorMessage(code, message, context));
+		this.code = code;
+		this.context = context;
+		this.name = new.target.name;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+var ResultTypeError = class extends TypeError {
+	code;
+	context;
+	constructor(message, code, context) {
+		super(formatResultErrorMessage(code, message, context));
+		this.code = code;
+		this.context = context;
+		this.name = new.target.name;
+		Object.setPrototypeOf(this, new.target.prototype);
+	}
+};
+const INVALID_RESULT_STATE_MESSAGE = "Unreachable: Result is neither Ok nor Err";
+var InvalidResultStateError = class extends ResultError {
+	constructor(context) {
+		super(INVALID_RESULT_STATE_MESSAGE, ERR_INVALID_STATE, context);
+	}
+};
+var TaskYieldNotResultError = class extends ResultTypeError {
+	yieldedValue;
+	constructor(yieldedValue) {
+		super("task() expected yielded values to be Result. Use `yield*` on a Result.", ERR_TASK_YIELD_NOT_RESULT);
+		this.yieldedValue = yieldedValue;
+	}
+};
+var MatchOnOkError = class extends ResultTypeError {
+	constructor() {
+		super("match() can only be called on Err results. Use `if (result.isErr()) { ... }` first.", ERR_MATCH_ON_OK);
+	}
+};
+var UnwrapOnErrError = class extends ResultTypeError {
+	errorValue;
+	constructor(errorValue) {
+		super(`Called unwrap() on Err: ${String(errorValue)}`, ERR_UNWRAP_ON_ERR);
+		this.errorValue = errorValue;
+	}
+};
+var UnwrapErrOnOkError = class extends ResultTypeError {
+	okValue;
+	constructor(okValue) {
+		super(`Called unwrapErr() on Ok: ${String(okValue)}`, ERR_UNWRAP_ERR_ON_OK);
+		this.okValue = okValue;
+	}
+};
+var ExpectOkError = class extends ResultError {
+	expectedMessage;
+	constructor(expectedMessage) {
+		super(expectedMessage, ERR_EXPECT_OK);
+		this.expectedMessage = expectedMessage;
+	}
+};
+var ExpectErrError = class extends ResultError {
+	expectedMessage;
+	constructor(expectedMessage) {
+		super(expectedMessage, ERR_EXPECT_ERR);
+		this.expectedMessage = expectedMessage;
+	}
+};
+
 //#endregion
 //#region src/core/matcher.ts
 /**
@@ -75,7 +157,7 @@ var ErrMatchBuilder = class ErrMatchBuilder {
 	static fromResult(result, makeErr) {
 		if (result.isOk()) return new ErrMatchBuilder(makeErr, void 0, result);
 		if (result.isErr()) return new ErrMatchBuilder(makeErr, result.error);
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("ErrMatchBuilder.fromResult");
 	}
 	when(ctor, handler) {
 		if (this.#resolved) return this;
@@ -143,7 +225,7 @@ function mapBoth(mapOk, mapErr$1) {
 	return (source) => {
 		if (source.isOk()) return ok(mapOk(source.value));
 		if (source.isErr()) return err(mapErr$1(source.error));
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("mapBoth");
 	};
 }
 /**
@@ -170,7 +252,7 @@ function zipImpl(left, right) {
 	if (left.isErr()) return left;
 	if (right.isErr()) return right;
 	if (left.isOk() && right.isOk()) return ok([left.value, right.value]);
-	throw new Error("Unreachable: Result is neither Ok nor Err");
+	throw new InvalidResultStateError("zip");
 }
 function zip(...args) {
 	if (args.length === 1) {
@@ -236,7 +318,7 @@ function match(handlers) {
 	return (source) => {
 		if (source.isOk()) return handlers.ok(source.value);
 		if (source.isErr()) return handlers.err(source.error);
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("match");
 	};
 }
 
@@ -250,7 +332,7 @@ function recover(defaultValue) {
 	return (source) => {
 		if (source.isOk()) return source;
 		if (source.isErr()) return ok(defaultValue);
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("recover");
 	};
 }
 /**
@@ -260,7 +342,7 @@ function recoverWith(fn) {
 	return (source) => {
 		if (source.isOk()) return source;
 		if (source.isErr()) return ok(fn(source.error));
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("recoverWith");
 	};
 }
 
@@ -273,7 +355,7 @@ function recoverWith(fn) {
 function swap(result) {
 	if (result.isOk()) return err(result.value);
 	if (result.isErr()) return ok(result.error);
-	throw new Error("Unreachable: Result is neither Ok nor Err");
+	throw new InvalidResultStateError("swap");
 }
 
 //#endregion
@@ -304,7 +386,7 @@ function tryMap(project, errorMapper) {
 		if (source.isErr()) return source;
 		try {
 			if (source.isOk()) return ok(project(source.value));
-			throw new Error("Unreachable: Result is neither Ok nor Err");
+			throw new InvalidResultStateError("tryMap");
 		} catch (error) {
 			return err(errorMapper ? errorMapper(error) : error);
 		}
@@ -326,7 +408,7 @@ function collectFirstOk(results) {
 			errors.push(result.error);
 			continue;
 		}
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("collectFirstOk");
 	}
 	return err(errors);
 }
@@ -404,7 +486,7 @@ function matchAsync(handlers) {
 	return async (source) => {
 		if (source.isOk()) return await handlers.ok(source.value);
 		if (source.isErr()) return await handlers.err(source.error);
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("matchAsync");
 	};
 }
 
@@ -434,7 +516,7 @@ function tryMapAsync(project, errorMapper) {
 		if (source.isErr()) return source;
 		try {
 			if (source.isOk()) return ok(await project(source.value));
-			throw new Error("Unreachable: Result is neither Ok nor Err");
+			throw new InvalidResultStateError("tryMapAsync");
 		} catch (error) {
 			return err(errorMapper ? errorMapper(error) : error);
 		}
@@ -459,7 +541,7 @@ var ResultBase = class extends Pipeable {
 	fold(onOk, onErr) {
 		if (this._tag === "Ok") return onOk(this.value);
 		if (this._tag === "Err") return onErr(this.error);
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("Result.fold");
 	}
 	/**
 	* Enables `yield* result` in generators (Do-notation).
@@ -479,7 +561,7 @@ var ResultBase = class extends Pipeable {
 	*/
 	match() {
 		if (this._tag === "Err") return new ErrorMatchBuilder(this.error);
-		throw new Error("match() can only be called on Err results. Use `if (result.isErr()) { ... }` first.");
+		throw new MatchOnOkError();
 	}
 	/**
 	* Matcht auf den Err-Wert, aber normalisiert jeden Branch zu einem `Result`:
@@ -614,7 +696,7 @@ async function task(makeGenerator, onThrow) {
 			return err(onThrow(caught));
 		}
 		const yielded = step.value;
-		if (!isResult(yielded)) throw new TypeError("task() expected yielded values to be Result. Use `yield*` on a Result.");
+		if (!isResult(yielded)) throw new TaskYieldNotResultError(yielded);
 		if (yielded.isOk()) {
 			input = yielded.value;
 			continue;
@@ -628,7 +710,7 @@ async function task(makeGenerator, onThrow) {
 			}
 			return yielded;
 		}
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("task");
 	}
 }
 const gen = task;
@@ -645,7 +727,7 @@ function fold(handlers) {
 	return (source) => {
 		if (source.isOk()) return handlers.ok(source.value);
 		if (source.isErr()) return handlers.err(source.error);
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("fold");
 	};
 }
 
@@ -661,7 +743,7 @@ function foldAsync(handlers) {
 	return async (source) => {
 		if (source.isOk()) return await handlers.ok(source.value);
 		if (source.isErr()) return await handlers.err(source.error);
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("foldAsync");
 	};
 }
 
@@ -673,8 +755,8 @@ function foldAsync(handlers) {
 */
 function unwrap(result) {
 	if (result.isOk()) return result.value;
-	if (result.isErr()) throw new Error(`Called unwrap() on Err: ${String(result.error)}`);
-	throw new Error("Unreachable: Result is neither Ok nor Err");
+	if (result.isErr()) throw new UnwrapOnErrError(result.error);
+	throw new InvalidResultStateError("unwrap");
 }
 
 //#endregion
@@ -697,7 +779,7 @@ function unwrapOr(result, defaultValue) {
 function unwrapOrElse(result, fn) {
 	if (result.isOk()) return result.value;
 	if (result.isErr()) return fn(result.error);
-	throw new Error("Unreachable: Result is neither Ok nor Err");
+	throw new InvalidResultStateError("unwrapOrElse");
 }
 
 //#endregion
@@ -719,7 +801,7 @@ function unwrapOrDefault(result, defaultValue) {
 function unwrapOrThrow(result) {
 	if (result.isOk()) return result.value;
 	if (result.isErr()) throw result.error;
-	throw new Error("Unreachable: Result is neither Ok nor Err");
+	throw new InvalidResultStateError("unwrapOrThrow");
 }
 
 //#endregion
@@ -730,8 +812,8 @@ function unwrapOrThrow(result) {
 */
 function unwrapErr(result) {
 	if (result.isErr()) return result.error;
-	if (result.isOk()) throw new Error(`Called unwrapErr() on Ok: ${String(result.value)}`);
-	throw new Error("Unreachable: Result is neither Ok nor Err");
+	if (result.isOk()) throw new UnwrapErrOnOkError(result.value);
+	throw new InvalidResultStateError("unwrapErr");
 }
 
 //#endregion
@@ -742,7 +824,7 @@ function unwrapErr(result) {
 */
 function expectResult(result, message) {
 	if (result.isOk()) return result.value;
-	throw new Error(message);
+	throw new ExpectOkError(message);
 }
 
 //#endregion
@@ -753,7 +835,7 @@ function expectResult(result, message) {
 */
 function expectErr(result, message) {
 	if (result.isErr()) return result.error;
-	throw new Error(message);
+	throw new ExpectErrError(message);
 }
 
 //#endregion
@@ -785,7 +867,7 @@ function or(result, other) {
 function orElse(result, fn) {
 	if (result.isOk()) return result;
 	if (result.isErr()) return fn(result.error);
-	throw new Error("Unreachable: Result is neither Ok nor Err");
+	throw new InvalidResultStateError("orElse");
 }
 
 //#endregion
@@ -808,7 +890,7 @@ function mapOr(result, defaultValue, fn) {
 function mapOrElse(result, defaultFn, fn) {
 	if (result.isOk()) return fn(result.value);
 	if (result.isErr()) return defaultFn(result.error);
-	throw new Error("Unreachable: Result is neither Ok nor Err");
+	throw new InvalidResultStateError("mapOrElse");
 }
 
 //#endregion
@@ -826,7 +908,7 @@ function sequence(results) {
 			continue;
 		}
 		if (result.isErr()) return result;
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("sequence");
 	}
 	return ok(values);
 }
@@ -853,7 +935,7 @@ function sequenceRecord(record) {
 			continue;
 		}
 		if (result.isErr()) return result;
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("sequenceRecord");
 	}
 	return ok(out);
 }
@@ -876,7 +958,7 @@ async function collectFirstOkAsync(inputs) {
 			errors.push(result.error);
 			continue;
 		}
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("collectFirstOkAsync");
 	} catch (error) {
 		errors.push(error);
 	}
@@ -884,53 +966,36 @@ async function collectFirstOkAsync(inputs) {
 }
 
 //#endregion
-//#region src/core/collectFirstOkRaceAsync.ts
+//#region src/core/collectFirstOkParallelAsync.ts
 /**
-* Parallel/Race-Variante von `collectFirstOkAsync`.
+* Parallel-Variante von `collectFirstOkAsync`.
 *
 * - Startet alle Inputs sofort (Promises oder Thunks).
 * - Gibt das erste `Ok` zurück, sobald es verfügbar ist.
 * - Wenn kein `Ok` gefunden wird, gibt ein `Err` mit allen Error-Werten (in Input-Reihenfolge) zurück.
+* - Rejections werden als `ErrValue` behandelt (`caught as ErrValue`).
+* - Wenn mehrere Inputs ein `Ok` liefern, gewinnt das zuerst abgeschlossene Ergebnis.
+*   Bei gleichzeitiger Completion gewinnt das zuerst beobachtete Ergebnis.
+* - Wenn kein `Ok` kommt und mindestens ein Input nie settled, bleibt das Promise offen.
 */
-async function collectFirstOkRaceAsync(inputs) {
+async function collectFirstOkParallelAsync(inputs) {
 	if (inputs.length === 0) return err([]);
-	const UNSET = Symbol("unset");
-	const errorsByIndex = Array(inputs.length).fill(UNSET);
-	return new Promise((resolve) => {
-		let done = false;
-		let remaining = inputs.length;
-		const finishAllErr = () => {
-			const errors = [];
-			for (const entry of errorsByIndex) if (entry !== UNSET) errors.push(entry);
-			resolve(err(errors));
-		};
-		const settleError = (index, errorValue) => {
-			if (done) return;
-			errorsByIndex[index] = errorValue;
-			remaining -= 1;
-			if (remaining === 0) {
-				done = true;
-				finishAllErr();
-			}
-		};
-		inputs.forEach((input, index) => {
-			Promise.resolve().then(() => typeof input === "function" ? input() : input).then((result) => {
-				if (done) return;
-				if (result.isOk()) {
-					done = true;
-					resolve(ok(result.value));
-					return;
-				}
-				if (result.isErr()) {
-					settleError(index, result.error);
-					return;
-				}
-				settleError(index, /* @__PURE__ */ new Error("Unreachable: Result is neither Ok nor Err"));
-			}).catch((caught) => {
-				settleError(index, caught);
-			});
-		});
+	const started = inputs.map((input) => typeof input === "function" ? Promise.resolve().then(input) : input);
+	const firstOk = new Promise((resolve) => {
+		for (const promise of started) promise.then((result) => {
+			if (result.isOk()) resolve(ok(result.value));
+		}).catch(() => {});
+	});
+	const allErrors = Promise.allSettled(started).then((settled) => {
+		const errors = [];
+		for (const entry of settled) if (entry.status === "fulfilled") {
+			const result = entry.value;
+			if (result.isErr()) errors.push(result.error);
+			else if (!result.isOk()) errors.push(new InvalidResultStateError("collectFirstOkParallelAsync"));
+		} else errors.push(entry.reason);
+		return err(errors);
 	});
+	return Promise.race([firstOk, allErrors]);
 }
 
 //#endregion
@@ -951,7 +1016,7 @@ function collectAllErrors(results) {
 			errors.push(result.error);
 			continue;
 		}
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("collectAllErrors");
 	}
 	return errors.length === 0 ? ok(values) : err(errors);
 }
@@ -973,7 +1038,7 @@ function partition(results) {
 			errs.push(result.error);
 			continue;
 		}
-		throw new Error("Unreachable: Result is neither Ok nor Err");
+		throw new InvalidResultStateError("partition");
 	}
 	return [oks, errs];
 }
@@ -999,7 +1064,7 @@ function flatten(result) {
 function toPromise(result) {
 	if (result.isOk()) return Promise.resolve(result.value);
 	if (result.isErr()) return Promise.reject(result.error);
-	throw new Error("Unreachable: Result is neither Ok nor Err");
+	throw new InvalidResultStateError("toPromise");
 }
 
 //#endregion
@@ -1056,16 +1121,32 @@ function containsErr(result, error) {
 }
 
 //#endregion
+exports.ERR_EXPECT_ERR = ERR_EXPECT_ERR;
+exports.ERR_EXPECT_OK = ERR_EXPECT_OK;
+exports.ERR_INVALID_STATE = ERR_INVALID_STATE;
+exports.ERR_MATCH_ON_OK = ERR_MATCH_ON_OK;
+exports.ERR_TASK_YIELD_NOT_RESULT = ERR_TASK_YIELD_NOT_RESULT;
+exports.ERR_UNWRAP_ERR_ON_OK = ERR_UNWRAP_ERR_ON_OK;
+exports.ERR_UNWRAP_ON_ERR = ERR_UNWRAP_ON_ERR;
 exports.Err = Err;
+exports.ExpectErrError = ExpectErrError;
+exports.ExpectOkError = ExpectOkError;
+exports.InvalidResultStateError = InvalidResultStateError;
+exports.MatchOnOkError = MatchOnOkError;
 exports.Ok = Ok;
 exports.Result = Result;
+exports.ResultError = ResultError;
+exports.ResultTypeError = ResultTypeError;
+exports.TaskYieldNotResultError = TaskYieldNotResultError;
+exports.UnwrapErrOnOkError = UnwrapErrOnOkError;
+exports.UnwrapOnErrError = UnwrapOnErrError;
 exports.all = all;
 exports.and = and;
 exports.bimap = bimap;
 exports.collectAllErrors = collectAllErrors;
 exports.collectFirstOk = collectFirstOk;
 exports.collectFirstOkAsync = collectFirstOkAsync;
-exports.collectFirstOkRaceAsync = collectFirstOkRaceAsync;
+exports.collectFirstOkParallelAsync = collectFirstOkParallelAsync;
 exports.combine = combine;
 exports.contains = contains;
 exports.containsErr = containsErr;