resultar 3.3.1 → 3.5.0

package/dist/index.js

@@ -1,5 +1,11 @@
 //#region src/abort-error.ts
+/**
+* Standard cancellation error used by ResultAsync retry, race, timeout, and resource helpers.
+*/
 var AbortError = class extends Error {
+	/**
+	* Creates an AbortError.
+	*/
 	constructor(message = "Operation aborted", options) {
 		super(message, options);
 		this.name = "AbortError";
@@ -7,6 +13,9 @@ var AbortError = class extends Error {
 };
 const hasAbortName = (value) => typeof value === "object" && value !== null && "name" in value && value.name === "AbortError";
 const hasAbortCode = (value) => typeof value === "object" && value !== null && "code" in value && value.code === "ABORT_ERR";
+/**
+* Checks whether a value is an AbortError or abort-shaped platform error.
+*/
 const isAbortError = (value) => value instanceof AbortError || hasAbortName(value) || hasAbortCode(value);
 //#endregion
 //#region src/pipe.ts
@@ -64,8 +73,9 @@ const callTaggedHandler = (value, handlers) => {
 	return { value: handler(value) };
 };
 const callErrorHandler = (error, handlers) => {
-	if (handlers.Error === void 0) return noTaggedHandlerMatch;
-	return { value: handlers.Error(error) };
+	const handler = handlers.Error;
+	if (handler === void 0) return noTaggedHandlerMatch;
+	return { value: handler(error) };
 };
 const callTaggedOrErrorHandler = (error, handlers) => {
 	const tagged = callTaggedHandler(error, handlers);
@@ -243,7 +253,8 @@ var ResultNamespace = class {
 	}
 	static validateAll(resultListOrItems, f) {
 		if (f === void 0) return combineResultListWithAllErrors(resultListOrItems);
-		return combineResultListWithAllErrors(Array.from(resultListOrItems, f));
+		const resultList = Array.from(resultListOrItems, f);
+		return combineResultListWithAllErrors(resultList);
 	}
 	static zip(left, right) {
 		return combineResultList([left, right]);
@@ -537,32 +548,64 @@ var Err = class extends ResultVariant {
 var DisposableResult = class {
 	disposed = false;
 	finalizer;
+	/**
+	* Wrapped Result value.
+	*/
 	result;
+	/**
+	* Creates a disposable wrapper around a Result.
+	*/
 	constructor(result, finalizer) {
 		this.result = result;
 		this.finalizer = finalizer;
 	}
+	/**
+	* Ok value when present, otherwise undefined cast to `T` for compatibility.
+	*/
 	get value() {
 		return this.result.isOk() ? this.result.value : void 0;
 	}
+	/**
+	* Err value when present, otherwise undefined cast to `E` for compatibility.
+	*/
 	get error() {
 		return this.result.isErr() ? this.result.error : void 0;
 	}
+	/**
+	* Delegates to the wrapped Result `_unsafeUnwrap`.
+	*/
 	_unsafeUnwrap(config) {
 		return this.result._unsafeUnwrap(config);
 	}
+	/**
+	* Delegates to the wrapped Result `_unsafeUnwrapErr`.
+	*/
 	_unsafeUnwrapErr(config) {
 		return this.result._unsafeUnwrapErr(config);
 	}
+	/**
+	* Returns whether the wrapped Result is Ok.
+	*/
 	isOk() {
 		return this.result.isOk();
 	}
+	/**
+	* Returns whether the wrapped Result is Err.
+	*/
 	isErr() {
 		return this.result.isErr();
 	}
+	/**
+	* Returns the wrapped Ok value, or `defaultValue` when Err.
+	*/
 	unwrapOr(defaultValue) {
 		return this.result.unwrapOr(defaultValue);
 	}
+	/**
+	* Runs the finalizer once.
+	*
+	* Finalizer exceptions are intentionally swallowed.
+	*/
 	[Symbol.dispose]() {
 		if (this.disposed) return;
 		this.disposed = true;
@@ -593,6 +636,11 @@ function ok(value) {
 function err(error) {
 	return new Err(error);
 }
+/**
+* Wraps a throwing synchronous function so every later call returns a Result.
+*
+* Prefer `tryResult` when you want to run the operation immediately.
+*/
 const fromThrowable = Result.fromThrowable;
 function tryResult(input, errorFn) {
 	const fn = typeof input === "function" ? input : input.try;
@@ -604,12 +652,269 @@ function tryResult(input, errorFn) {
 		return err(error);
 	}
 }
+/**
+* Creates an Ok result with `undefined`.
+*/
 function unit() {
 	return ok(void 0);
 }
+/**
+* Runs a `Result` at an application boundary and returns the success value.
+*
+* If the result is `Err`, this throws the error. Use it at final framework, CLI, test, or bootstrap
+* boundaries after the error channel has already been modeled with Resultar.
+*/
+const runSync = (result) => result.unwrapOrThrow();
 /** Compatibility alias. Prefer `tryResult` in new code. */
 const tryCatch = tryResult;
 //#endregion
+//#region src/redacted.ts
+const redactedValues = /* @__PURE__ */ new WeakMap();
+const formatRedacted = (label) => label === void 0 ? "<redacted>" : `<redacted:${label}>`;
+var RedactedValue = class {
+	__resultarRedacted = true;
+	label;
+	/**
+	* Stores a sensitive value behind a redacted string wrapper.
+	*/
+	constructor(value, label) {
+		this.label = label;
+		redactedValues.set(this, value);
+	}
+	/**
+	* Serializes to the redacted placeholder.
+	*/
+	toJSON() {
+		return this.toString();
+	}
+	/**
+	* Converts to the redacted placeholder.
+	*/
+	toString() {
+		return formatRedacted(this.label);
+	}
+};
+/**
+* Wraps a sensitive value so tagged-error messages and JSON output show only a placeholder.
+*/
+const redact = (value, label) => new RedactedValue(value, label);
+/**
+* Checks whether a value was created by `redact`.
+*/
+const isRedacted = (value) => typeof value === "object" && value !== null && redactedValues.has(value);
+/**
+* Returns the original sensitive value from a Redacted wrapper.
+*/
+const revealRedacted = (value) => redactedValues.get(value);
+/**
+* Converts a Redacted wrapper to its placeholder string.
+*/
+const stringifyRedacted = (value) => value.toString();
+//#endregion
+//#region src/tagged-error.ts
+const defaultBaseError = Error;
+const defaultMessageTemplate = "$message";
+const nativeError = Error;
+const templateVariableMatcher = /\$(?<name>[a-zA-Z_][a-zA-Z0-9_]*)/gu;
+const reservedTemplateVariables = /* @__PURE__ */ new Set([
+	"_tag",
+	"cause",
+	"fingerprint",
+	"message",
+	"messageTemplate",
+	"name",
+	"stack"
+]);
+function isError(value) {
+	return nativeError.isError?.(value) ?? value instanceof Error;
+}
+const stringifyDirectTemplateValue = String;
+const stringifySymbolTemplateValue = (value) => {
+	const symbol = value;
+	return symbol.description ?? symbol.toString();
+};
+const stringifyFunctionTemplateValue = (value) => value.name;
+const stringifyObjectTemplateValue = (value) => JSON.stringify(value) ?? Object.prototype.toString.call(value);
+const templateValueStringifiers = {
+	bigint: stringifyDirectTemplateValue,
+	boolean: stringifyDirectTemplateValue,
+	function: stringifyFunctionTemplateValue,
+	number: stringifyDirectTemplateValue,
+	object: stringifyObjectTemplateValue,
+	string: stringifyDirectTemplateValue,
+	symbol: stringifySymbolTemplateValue
+};
+const stringifyTemplateValue = (value) => isRedacted(value) ? stringifyRedacted(value) : templateValueStringifiers[typeof value](value);
+const compileMessageInterpolator = (template) => (values) => template.replaceAll(templateVariableMatcher, (variable, key) => {
+	const value = values?.[key];
+	return value === void 0 ? variable : stringifyTemplateValue(value);
+});
+const getTemplateVariableNames = (template) => {
+	templateVariableMatcher.lastIndex = 0;
+	return [...template.matchAll(templateVariableMatcher)].map((match) => String(match[1]));
+};
+const assertNoReservedTemplateVariables = (tag, template) => {
+	if (template === defaultMessageTemplate) return;
+	const reservedVariables = getTemplateVariableNames(template).filter((variable) => reservedTemplateVariables.has(variable));
+	if (reservedVariables.length > 0) throw new Error(`createTaggedError(${tag}): reserved template variable $${reservedVariables[0]} is not allowed`);
+};
+const getErrorOptions = (cause) => cause === void 0 ? {} : { cause };
+const assignReadonly = (target, key, value) => {
+	Object.defineProperty(target, key, {
+		configurable: true,
+		enumerable: true,
+		value,
+		writable: false
+	});
+};
+const serializeTaggedValue = (value) => isRedacted(value) ? stringifyRedacted(value) : value;
+const serializeCause = (cause, seen = /* @__PURE__ */ new Set()) => {
+	if (!isError(cause)) return serializeTaggedValue(cause);
+	if (seen.has(cause)) return {
+		cause: "[Circular]",
+		message: cause.message,
+		name: cause.name,
+		stack: cause.stack
+	};
+	seen.add(cause);
+	const json = {
+		message: cause.message,
+		name: cause.name,
+		stack: cause.stack
+	};
+	if (cause.cause !== void 0) json["cause"] = serializeCause(cause.cause, seen);
+	return json;
+};
+/**
+* Finds the first cause in an Error cause chain that is an instance of `ErrorClass`.
+*/
+const findCause = (error, ErrorClass) => {
+	const seen = /* @__PURE__ */ new Set();
+	let current = error;
+	while (isError(current)) {
+		if (seen.has(current)) break;
+		seen.add(current);
+		if (current instanceof ErrorClass) return current;
+		current = current.cause;
+	}
+};
+/**
+* Creates an Error class with a stable `_tag`, typed template props, cause support, and JSON output.
+*
+* Prefer tagged errors for domain failures that travel through Resultar error channels.
+*
+* @example
+* ```ts
+* class UserNotFoundError extends createTaggedError({
+*   name: "UserNotFoundError",
+*   message: "User $id was not found",
+* }) {}
+* ```
+*/
+function createTaggedError(options) {
+	const BaseError = options.extends ?? defaultBaseError;
+	const messageTemplate = options.message ?? defaultMessageTemplate;
+	assertNoReservedTemplateVariables(options.name, messageTemplate);
+	const interpolate = compileMessageInterpolator(messageTemplate);
+	class GeneratedTaggedError extends BaseError {
+		static tag = options.name;
+		_tag = options.name;
+		fingerprint = [options.name, messageTemplate];
+		messageTemplate = messageTemplate;
+		constructor(props) {
+			const message = interpolate(props);
+			super(message, getErrorOptions(props?.cause));
+			this.name = options.name;
+			if (props) {
+				for (const [key, value] of Object.entries(props)) if (!reservedTemplateVariables.has(key)) assignReadonly(this, key, value);
+			}
+		}
+		/**
+		* Narrows a value to this tagged error class.
+		*/
+		static is(value) {
+			return value instanceof this;
+		}
+		/**
+		* Creates an Err containing this tagged error.
+		*/
+		static err(...args) {
+			return err(new this(...args));
+		}
+		/**
+		* Finds a matching cause in this error's cause chain.
+		*/
+		findCause(ErrorClass) {
+			return findCause(this, ErrorClass);
+		}
+		/**
+		* Serializes the tagged error, metadata, and cause chain.
+		*/
+		toJSON() {
+			const json = {
+				_tag: this._tag,
+				fingerprint: this.fingerprint,
+				message: this.message,
+				messageTemplate: this.messageTemplate,
+				name: this.name
+			};
+			if (this.cause !== void 0) json["cause"] = serializeCause(this.cause);
+			for (const [key, value] of Object.entries(this)) if (!(key in json) && key !== "cause" && key !== "stack") json[key] = serializeTaggedValue(value);
+			return json;
+		}
+	}
+	return GeneratedTaggedError;
+}
+/**
+* Creates a small tagged-union factory with member constructors, `$is`, and `$match`.
+*/
+const taggedEnum = () => {
+	return new Proxy({
+		$is(tag, value) {
+			return typeof value === "object" && value !== null && "_tag" in value && value._tag === tag;
+		},
+		$match(value, handlers) {
+			const handler = handlers[value._tag];
+			if (handler === void 0) throw new Error(`No tagged enum handler for ${String(value._tag)}`);
+			return handler(value);
+		}
+	}, { get(base, property, receiver) {
+		if (property in base) return Reflect.get(base, property, receiver);
+		if (typeof property !== "string") return;
+		return (props) => {
+			const value = { _tag: property };
+			if (props !== void 0) {
+				for (const [key, propValue] of Object.entries(props)) if (key !== "_tag") value[key] = propValue;
+			}
+			return Object.freeze(value);
+		};
+	} });
+};
+/**
+* Matches an Error by tagged `_tag`, with optional native `Error` fallback.
+*
+* Throws the original error when no handler matches.
+*/
+const matchError = (error, handlers) => {
+	if ("_tag" in error && typeof error._tag === "string" && error._tag in handlers) {
+		const handler = handlers[error._tag];
+		return handler(error);
+	}
+	if (handlers.Error) return handlers.Error(error);
+	throw error;
+};
+/**
+* Matches an Error by tagged `_tag`, then native `Error`, then the provided fallback.
+*/
+const matchErrorPartial = (error, handlers, fallback) => {
+	if ("_tag" in error && typeof error._tag === "string" && error._tag in handlers) {
+		const handler = handlers[error._tag];
+		if (handler) return handler(error);
+	}
+	if (handlers.Error) return handlers.Error(error);
+	return fallback(error);
+};
+//#endregion
 //#region src/result-async.ts
 function isTryResultAsyncOptions(input) {
 	return typeof input === "object" && input !== null && "try" in input;
@@ -725,11 +1030,84 @@ const runConcurrentResultAsyncItems = (options) => Promise.try(async () => {
 });
 const createResultAsyncRetryAbortError = (signal) => signal.reason === void 0 ? new AbortError("ResultAsync retry aborted") : new AbortError("ResultAsync retry aborted", { cause: signal.reason });
 const createResultAsyncResourceAbortError = (signal) => signal.reason === void 0 ? new AbortError("ResultAsync resource scope aborted") : new AbortError("ResultAsync resource scope aborted", { cause: signal.reason });
-const validateResultAsyncRetryTimes = (times) => {
-	if (!Number.isInteger(times) || times < 0) throw createIllegalArgumentException("ResultAsync retry times must be a non-negative integer");
+const createResultAsyncCallbackAbortError = (signal) => signal.reason === void 0 ? new AbortError("ResultAsync callback aborted") : new AbortError("ResultAsync callback aborted", { cause: signal.reason });
+const emptyResultAsyncCallbackCleanup = () => void 0;
+const callResultAsyncCallbackCleanup = (cleanup) => {
+	try {
+		cleanup();
+	} catch {}
 };
-const validateResultAsyncRetryDelayValue = (delayMs) => {
-	if (!Number.isFinite(delayMs) || delayMs < 0) throw createIllegalArgumentException("ResultAsync retry delayMs must be a non-negative finite number");
+const normalizeResultAsyncCallbackUnexpectedError = (error) => isError(error) ? error : new Error("ResultAsync callback error mapper threw a non-Error value", { cause: error });
+const completeResultAsyncCallback = (completion) => {
+	if ("error" in completion.settlement) {
+		completion.rejectResult(normalizeResultAsyncCallbackUnexpectedError(completion.settlement.error));
+		return;
+	}
+	completion.resolveResult(completion.settlement.result);
+};
+const fromResultAsyncCallback = (options) => {
+	const signal = options.signal ?? new AbortController().signal;
+	return new ResultAsync(new Promise((resolveResult, rejectResult) => {
+		if (signal.aborted) {
+			resolveResult(Result.err(createResultAsyncCallbackAbortError(signal)));
+			return;
+		}
+		let cleanup = emptyResultAsyncCallbackCleanup;
+		let settlement = void 0;
+		let subscribed = false;
+		const finalize = () => {
+			if (!subscribed) return;
+			const completed = settlement;
+			if (completed === void 0) return;
+			signal.removeEventListener("abort", abort);
+			callResultAsyncCallbackCleanup(cleanup);
+			completeResultAsyncCallback({
+				rejectResult,
+				resolveResult,
+				settlement: completed
+			});
+		};
+		const settle = (result) => {
+			if (settlement !== void 0) return;
+			settlement = { result };
+			finalize();
+		};
+		const rejectUnexpected = (error) => {
+			settlement = { error };
+			finalize();
+		};
+		const abort = () => {
+			settle(Result.err(createResultAsyncCallbackAbortError(signal)));
+		};
+		const context = {
+			reject: (cause) => {
+				if (settlement !== void 0) return;
+				try {
+					settle(Result.err(options.catch(cause)));
+				} catch (error) {
+					rejectUnexpected(error);
+				}
+			},
+			resolve: (value) => {
+				settle(Result.ok(value));
+			},
+			signal
+		};
+		signal.addEventListener("abort", abort);
+		try {
+			cleanup = options.subscribe(context) ?? emptyResultAsyncCallbackCleanup;
+		} catch (error) {
+			context.reject(error);
+		}
+		subscribed = true;
+		finalize();
+	}));
+};
+const validateResultAsyncRetryTimes = (times) => {
+	if (!Number.isInteger(times) || times < 0) throw createIllegalArgumentException("ResultAsync retry times must be a non-negative integer");
+};
+const validateResultAsyncRetryDelayValue = (delayMs) => {
+	if (!Number.isFinite(delayMs) || delayMs < 0) throw createIllegalArgumentException("ResultAsync retry delayMs must be a non-negative finite number");
 };
 const validateResultAsyncRetryJittered = (jittered) => {
 	if (!Number.isFinite(jittered) || jittered < 0) throw createIllegalArgumentException("ResultAsync retry jittered must be a non-negative finite number");
@@ -1020,14 +1398,16 @@ const toResultAsync = (result) => {
 };
 const ifResultAsync = (condition, options) => {
 	return new ResultAsync(Promise.try(async () => {
-		return await toResultAsync(resolveResultAsyncBooleanCondition(condition) ? options.onTrue() : options.onFalse());
+		const result = resolveResultAsyncBooleanCondition(condition) ? options.onTrue() : options.onFalse();
+		return await toResultAsync(result);
 	}));
 };
 const ifResultAsyncWithCondition = (condition, options) => {
 	return new ResultAsync(Promise.try(async () => {
 		const conditionResult = await toResultAsync(condition);
 		if (conditionResult.isErr()) return Result.err(conditionResult.error);
-		return await toResultAsync(conditionResult.value ? options.onTrue() : options.onFalse());
+		const result = conditionResult.value ? options.onTrue() : options.onFalse();
+		return await toResultAsync(result);
 	}));
 };
 const whenResultAsync = (condition, body) => {
@@ -1060,13 +1440,24 @@ var DisposableResultAsync = class {
 	innerPromise;
 	finalizer;
 	disposed = false;
+	/**
+	* Creates an async disposable wrapper around a ResultAsync promise.
+	*/
 	constructor(res, finalizer) {
 		this.innerPromise = res;
 		this.finalizer = finalizer;
 	}
+	/**
+	* PromiseLike integration. Resolves to the wrapped Result.
+	*/
 	then(successCallback, failureCallback) {
 		return this.innerPromise.then(successCallback, failureCallback);
 	}
+	/**
+	* Runs the finalizer once after the wrapped Result resolves.
+	*
+	* Finalizer exceptions and rejections are intentionally swallowed.
+	*/
 	async [Symbol.asyncDispose]() {
 		if (this.disposed) return;
 		this.disposed = true;
@@ -1107,7 +1498,7 @@ var DisposableResultAsync = class {
 * but operating in an asynchronous context.
 *
 * The class includes methods for:
-* - Creating ResultAsync instances (okAsync, errAsync, fromPromise)
+* - Creating ResultAsync instances (okAsync, errAsync, fromPromise, fromCallback)
 * - Transforming values (map, mapErr)
 * - Chaining operations (andThen, orElse)
 * - Error handling (tapError)
@@ -1130,16 +1521,28 @@ var ResultAsync = class ResultAsync extends Pipeable {
 		return new ResultAsync(Promise.resolve(err(error)));
 	}
 	static tryCatch(fn, errorFn) {
-		return new ResultAsync((typeof fn === "function" ? Promise.try(fn) : fn).then((value) => ok(value)).catch((error) => {
+		const newPromise = (typeof fn === "function" ? Promise.try(fn) : fn).then((value) => ok(value)).catch((error) => {
 			if (errorFn) return err(errorFn(error));
 			return err(error);
-		}));
+		});
+		return new ResultAsync(newPromise);
 	}
 	static fromSafePromise(promise) {
-		return new ResultAsync(promise.then((value) => ok(value)));
+		const newPromise = promise.then((value) => ok(value));
+		return new ResultAsync(newPromise);
 	}
 	static fromPromise(promise, errorFn) {
-		return new ResultAsync(promise.then((value) => ok(value)).catch((error) => err(errorFn(error))));
+		const newPromise = promise.then((value) => ok(value)).catch((error) => err(errorFn(error)));
+		return new ResultAsync(newPromise);
+	}
+	/**
+	* Adapts a callback or subscription API into a cancellable ResultAsync.
+	*
+	* The returned cleanup function runs once after resolve, reject, cancellation, or synchronous
+	* subscription failure. Cleanup errors are ignored.
+	*/
+	static fromCallback(options) {
+		return fromResultAsyncCallback(options);
 	}
 	static combine(input) {
 		if (Array.isArray(input)) return combineResultAsyncList(input);
@@ -1155,24 +1558,52 @@ var ResultAsync = class ResultAsync extends Pipeable {
 		if (f === void 0) return combineResultAsyncListWithAllErrors(asyncResultListOrItems);
 		return validateAllResultAsyncItems(asyncResultListOrItems, f, options);
 	}
+	/**
+	* Combines exactly two ResultAsync values into an Ok tuple or the first Err.
+	*/
 	static zip(left, right) {
 		return combineResultAsyncList([left, right]);
 	}
+	/**
+	* Retries a ResultAsync task according to a typed retry policy.
+	*
+	* The returned error channel includes the task error and `AbortError`.
+	*/
 	static retry(task, options) {
 		return retryResultAsyncTask(task, options);
 	}
+	/**
+	* Retries a ResultAsync task and falls back to another Resultar operation after retry exhaustion.
+	*/
 	static retryOrElse(task, options) {
 		return retryOrElseResultAsyncTask(task, options);
 	}
+	/**
+	* Acquires, uses, and releases a resource with cleanup on every path.
+	*
+	* Release errors are intentionally not part of the success/error channel; model cleanup failures
+	* in `use` when they should affect control flow.
+	*/
 	static withResource(options) {
 		return withResultAsyncResource(options);
 	}
+	/**
+	* Races two cooperative ResultAsync tasks and returns the first settled Result.
+	*/
 	static race(left, right) {
 		return raceResultAsyncTasks([left, right]);
 	}
+	/**
+	* Races multiple cooperative ResultAsync tasks and returns the first settled Result.
+	*/
 	static raceAll(tasks) {
 		return raceResultAsyncTasks(tasks);
 	}
+	/**
+	* Races two cooperative ResultAsync tasks and returns the first successful Ok.
+	*
+	* If both fail, the returned error is the final observed Err.
+	*/
 	static raceFirst(left, right) {
 		return observeRaceResultAsyncTasks([left, right], (resolve, startedTasks) => ({
 			resolve,
@@ -1180,8 +1611,14 @@ var ResultAsync = class ResultAsync extends Pipeable {
 			state: { settled: false }
 		}), observeRaceFirstTask);
 	}
+	/**
+	* Races two cooperative ResultAsync tasks and lets handlers decide what to do when either side
+	* settles first.
+	*
+	* Handlers receive the settled Result and a handle to the still-running opposite task.
+	*/
 	static raceWith(left, right, handlers) {
-		return new ResultAsync(new Promise((resolve) => {
+		const promise = new Promise((resolve) => {
 			const leftTask = startRaceTask(left, 0);
 			const rightTask = startRaceTask(right, 1);
 			const leftHandle = createRaceHandle(leftTask);
@@ -1203,18 +1640,23 @@ var ResultAsync = class ResultAsync extends Pipeable {
 					resolve(handledResult);
 				});
 			});
-		}));
+		});
+		return new ResultAsync(promise);
 	}
+	/**
+	* Runs a cooperative ResultAsync task with a typed timeout error.
+	*/
 	static timeout(task, options) {
 		const timeoutTask = (signal) => {
-			return new ResultAsync(new Promise((resolve) => {
+			const promise = new Promise((resolve) => {
 				const timeout = setTimeout(() => {
 					resolve(Result.err(options.onTimeout()));
 				}, options.timeoutMs);
 				signal.addEventListener("abort", () => {
 					clearTimeout(timeout);
 				});
-			}));
+			});
+			return new ResultAsync(promise);
 		};
 		return ResultAsync.raceWith(task, timeoutTask, {
 			onLeftDone: (result, timeoutHandle) => {
@@ -1227,6 +1669,9 @@ var ResultAsync = class ResultAsync extends Pipeable {
 			}
 		});
 	}
+	/**
+	* Runs async candidates until the first Ok and returns the last Err if every candidate fails.
+	*/
 	static firstSuccessOf(candidates) {
 		return firstSuccessOfAsyncCandidates(candidates);
 	}
@@ -1234,15 +1679,27 @@ var ResultAsync = class ResultAsync extends Pipeable {
 		if (typeof condition === "boolean" || typeof condition === "function") return ifResultAsync(condition, options);
 		return ifResultAsyncWithCondition(condition, options);
 	}
+	/**
+	* Runs `body` only when the condition is true; otherwise returns Ok(undefined).
+	*/
 	static when(condition, body) {
 		return whenResultAsync(condition, body);
 	}
+	/**
+	* Runs `body` only when a Resultar boolean condition is Ok(true).
+	*/
 	static whenResult(condition, body) {
 		return whenResultAsyncWithCondition(condition, body);
 	}
+	/**
+	* Runs `body` only when the condition is false; otherwise returns Ok(undefined).
+	*/
 	static unless(condition, body) {
 		return unlessResultAsync(condition, body);
 	}
+	/**
+	* Runs `body` only when a Resultar boolean condition is Ok(false).
+	*/
 	static unlessResult(condition, body) {
 		return unlessResultAsyncWithCondition(condition, body);
 	}
@@ -1256,12 +1713,9 @@ var ResultAsync = class ResultAsync extends Pipeable {
 		return forEachResultAsync(items, f, options);
 	}
 	/**
-	* Wraps a async function with a try catch, creating a new function with the same
-	* arguments but returning `Ok` if successful, `Err` if the function throws
+	* Wraps an async function so every later call returns a ResultAsync.
 	*
-	* @param fn function to wrap with ok on success or err on failure
-	* @param errorFn when an error is thrown, this will wrap the error result if provided
-	* @returns a new function that returns a `ResultAsync`
+	* Prefer `tryResultAsync` when you want to run the operation immediately.
 	*/
 	static fromThrowable(fn, errorFn) {
 		return (...args) => new ResultAsync((async () => {
@@ -1273,25 +1727,45 @@ var ResultAsync = class ResultAsync extends Pipeable {
 		})());
 	}
 	innerPromise;
+	/**
+	* Creates a ResultAsync from a Promise that resolves to a Result.
+	*
+	* Most application code should prefer `tryResultAsync`, `fromPromise`, `okAsync`, or `errAsync`.
+	*/
 	constructor(res) {
 		super();
 		this.innerPromise = res;
 	}
+	/**
+	* PromiseLike integration. Resolves to the underlying `Result<T, E>`.
+	*
+	* Prefer ResultAsync combinators for application flow; this exists so ResultAsync can be awaited
+	* and used by Promise APIs.
+	*/
 	then(successCallback, failureCallback) {
 		return this.innerPromise.then(successCallback, failureCallback);
 	}
+	/**
+	* Maps the Err value while preserving the Ok value.
+	*/
 	mapErr(f) {
 		return new ResultAsync(this.innerPromise.then(async (res) => {
 			if (res.isOk()) return ok(res.value);
 			return err(await f(res.error));
 		}));
 	}
+	/**
+	* Maps the Ok value while preserving the error channel.
+	*/
 	map(f) {
 		return new ResultAsync(this.innerPromise.then(async (res) => {
 			if (res.isErr()) return err(res.error);
 			return ok(await f(res.value));
 		}));
 	}
+	/**
+	* Replaces the Ok value with a constant while preserving the error channel.
+	*/
 	as(value) {
 		return new ResultAsync(this.innerPromise.then((res) => {
 			if (res.isErr()) return err(res.error);
@@ -1312,6 +1786,9 @@ var ResultAsync = class ResultAsync extends Pipeable {
 			return next instanceof ResultAsync ? next.innerPromise : next;
 		}));
 	}
+	/**
+	* Branches from the Ok value into one of two async fallible Result branches.
+	*/
 	if(fCondition) {
 		return { true: (fTrue) => ({ false: (fFalse) => new ResultAsync(this.innerPromise.then(async (res) => {
 			if (res.isOk()) return fCondition(res.value) ? fTrue(res.value) : fFalse(res.value);
@@ -1337,6 +1814,9 @@ var ResultAsync = class ResultAsync extends Pipeable {
 			return Result.err(res.error);
 		}));
 	}
+	/**
+	* Recovers from multiple tagged errors by `_tag`.
+	*/
 	catchTags(handlers) {
 		return new ResultAsync(this.innerPromise.then((res) => {
 			if (res.isOk()) return Result.ok(res.value);
@@ -1362,6 +1842,9 @@ var ResultAsync = class ResultAsync extends Pipeable {
 			return Result.err(res.error);
 		}));
 	}
+	/**
+	* Recovers from multiple nested tagged `reason` variants on a specific tagged error.
+	*/
 	catchReasons(errorTag, handlers) {
 		return new ResultAsync(this.innerPromise.then((res) => {
 			if (res.isOk()) return Result.ok(res.value);
@@ -1378,6 +1861,9 @@ var ResultAsync = class ResultAsync extends Pipeable {
 			return Result.err(res.error);
 		}));
 	}
+	/**
+	* Moves the nested `reason` of a tagged error into the ResultAsync error channel.
+	*/
 	unwrapReason(errorTag) {
 		return new ResultAsync(this.innerPromise.then((res) => {
 			if (res.isOk()) return Result.ok(res.value);
@@ -1388,6 +1874,9 @@ var ResultAsync = class ResultAsync extends Pipeable {
 	async match(input, fnErr) {
 		return this.innerPromise.then((res) => typeof input === "function" ? res.match(input, getMatchErrorHandler(input, fnErr)) : res.match(input));
 	}
+	/**
+	* Converts this ResultAsync into a Promise of a plain value with exhaustive tagged-error handlers.
+	*/
 	async matchTags(ok, handlers) {
 		return this.innerPromise.then((res) => matchResolvedResultTags({
 			result: res,
@@ -1398,6 +1887,10 @@ var ResultAsync = class ResultAsync extends Pipeable {
 			}
 		}));
 	}
+	/**
+	* Converts this ResultAsync into a Promise of a plain value with partial tagged-error handlers and
+	* a fallback.
+	*/
 	async matchTagsPartial(ok, handlers, fallback) {
 		return this.innerPromise.then((res) => matchResolvedResultTags({
 			result: res,
@@ -1406,9 +1899,17 @@ var ResultAsync = class ResultAsync extends Pipeable {
 			fallback
 		}));
 	}
+	/**
+	* Resolves to the Ok value, or `t` when this ResultAsync is Err.
+	*/
 	async unwrapOr(t) {
 		return this.innerPromise.then((res) => res.unwrapOr(t));
 	}
+	/**
+	* Resolves to the Ok value or rejects with the Err value.
+	*
+	* Use this at final application boundaries after the error channel has been modeled.
+	*/
 	async unwrapOrThrow() {
 		return this.innerPromise.then((res) => res.unwrapOrThrow());
 	}
@@ -1460,9 +1961,15 @@ var ResultAsync = class ResultAsync extends Pipeable {
 			return okAsync(res.value);
 		}));
 	}
+	/**
+	* Attaches an async disposal finalizer to this ResultAsync.
+	*/
 	toAsyncDisposable(f) {
 		return new DisposableResultAsync(this.innerPromise, f);
 	}
+	/**
+	* Enables `yield* resultAsync` inside async `safeTry` generators.
+	*/
 	async *[Symbol.asyncIterator]() {
 		const result = await this.innerPromise;
 		if (result.isOk()) return result.value;
@@ -1471,11 +1978,35 @@ var ResultAsync = class ResultAsync extends Pipeable {
 	}
 };
 registerResultAsyncFactory((promise) => new ResultAsync(promise));
+/**
+* Creates an Ok ResultAsync.
+*/
 const okAsync = ResultAsync.okAsync;
+/**
+* Creates an Err ResultAsync.
+*/
 const errAsync = ResultAsync.errAsync;
+/**
+* Adapts a callback or subscription API into a cancellable ResultAsync.
+*/
+const fromCallback = ResultAsync.fromCallback;
+/**
+* Converts an existing promise into a ResultAsync and maps rejection into a typed Err.
+*/
 const fromPromise = ResultAsync.fromPromise;
+/**
+* Converts an existing promise that is expected not to reject into a ResultAsync.
+*
+* Use `fromPromise` or `tryResultAsync` when rejection should become a typed Err.
+*/
 const fromSafePromise = ResultAsync.fromSafePromise;
+/**
+* Creates an Ok ResultAsync with `undefined`.
+*/
 const unitAsync = ResultAsync.unitAsync;
+/**
+* Wraps an async function so every later call returns a ResultAsync.
+*/
 const fromThrowableAsync = ResultAsync.fromThrowable;
 function tryResultAsync(input, errorFn) {
 	const promiseOrFn = isTryResultAsyncOptions(input) ? input.try : input;
@@ -1485,196 +2016,14 @@ function tryResultAsync(input, errorFn) {
 		return Result.err(error);
 	}));
 }
+/**
+* Runs a `ResultAsync` at an application boundary and returns the success value.
+*
+* If the result is `Err`, this rejects with the error. Use it at final framework, CLI, test, or
+* bootstrap boundaries after the error channel has already been modeled with Resultar.
+*/
+const runPromise = (result) => result.unwrapOrThrow();
 /** Compatibility alias. Prefer `tryResultAsync` in new code. */
 const tryCatchAsync = tryResultAsync;
 //#endregion
-//#region src/redacted.ts
-const redactedValues = /* @__PURE__ */ new WeakMap();
-const formatRedacted = (label) => label === void 0 ? "<redacted>" : `<redacted:${label}>`;
-var RedactedValue = class {
-	__resultarRedacted = true;
-	label;
-	constructor(value, label) {
-		this.label = label;
-		redactedValues.set(this, value);
-	}
-	toJSON() {
-		return this.toString();
-	}
-	toString() {
-		return formatRedacted(this.label);
-	}
-};
-const redact = (value, label) => new RedactedValue(value, label);
-const isRedacted = (value) => typeof value === "object" && value !== null && redactedValues.has(value);
-const revealRedacted = (value) => redactedValues.get(value);
-const stringifyRedacted = (value) => value.toString();
-//#endregion
-//#region src/tagged-error.ts
-const defaultBaseError = Error;
-const defaultMessageTemplate = "$message";
-const nativeError = Error;
-const templateVariableMatcher = /\$([a-zA-Z_][a-zA-Z0-9_]*)/gu;
-const reservedTemplateVariables = new Set([
-	"_tag",
-	"cause",
-	"fingerprint",
-	"message",
-	"messageTemplate",
-	"name",
-	"stack"
-]);
-function isError(value) {
-	return nativeError.isError?.(value) ?? value instanceof Error;
-}
-const stringifyDirectTemplateValue = String;
-const stringifySymbolTemplateValue = (value) => {
-	const symbol = value;
-	return symbol.description ?? symbol.toString();
-};
-const stringifyFunctionTemplateValue = (value) => value.name;
-const stringifyObjectTemplateValue = (value) => JSON.stringify(value) ?? Object.prototype.toString.call(value);
-const templateValueStringifiers = {
-	bigint: stringifyDirectTemplateValue,
-	boolean: stringifyDirectTemplateValue,
-	function: stringifyFunctionTemplateValue,
-	number: stringifyDirectTemplateValue,
-	object: stringifyObjectTemplateValue,
-	string: stringifyDirectTemplateValue,
-	symbol: stringifySymbolTemplateValue
-};
-const stringifyTemplateValue = (value) => isRedacted(value) ? stringifyRedacted(value) : templateValueStringifiers[typeof value](value);
-const compileMessageInterpolator = (template) => (values) => template.replaceAll(templateVariableMatcher, (variable, key) => {
-	const value = values?.[key];
-	return value === void 0 ? variable : stringifyTemplateValue(value);
-});
-const getTemplateVariableNames = (template) => {
-	templateVariableMatcher.lastIndex = 0;
-	return [...template.matchAll(templateVariableMatcher)].map((match) => String(match[1]));
-};
-const assertNoReservedTemplateVariables = (tag, template) => {
-	if (template === defaultMessageTemplate) return;
-	const reservedVariables = getTemplateVariableNames(template).filter((variable) => reservedTemplateVariables.has(variable));
-	if (reservedVariables.length > 0) throw new Error(`createTaggedError(${tag}): reserved template variable $${reservedVariables[0]} is not allowed`);
-};
-const getErrorOptions = (cause) => cause === void 0 ? {} : { cause };
-const assignReadonly = (target, key, value) => {
-	Object.defineProperty(target, key, {
-		configurable: true,
-		enumerable: true,
-		value,
-		writable: false
-	});
-};
-const serializeTaggedValue = (value) => isRedacted(value) ? stringifyRedacted(value) : value;
-const serializeCause = (cause, seen = /* @__PURE__ */ new Set()) => {
-	if (!isError(cause)) return serializeTaggedValue(cause);
-	if (seen.has(cause)) return {
-		cause: "[Circular]",
-		message: cause.message,
-		name: cause.name,
-		stack: cause.stack
-	};
-	seen.add(cause);
-	const json = {
-		message: cause.message,
-		name: cause.name,
-		stack: cause.stack
-	};
-	if (cause.cause !== void 0) json["cause"] = serializeCause(cause.cause, seen);
-	return json;
-};
-const findCause = (error, ErrorClass) => {
-	const seen = /* @__PURE__ */ new Set();
-	let current = error;
-	while (isError(current)) {
-		if (seen.has(current)) break;
-		seen.add(current);
-		if (current instanceof ErrorClass) return current;
-		current = current.cause;
-	}
-};
-function createTaggedError(options) {
-	const BaseError = options.extends ?? defaultBaseError;
-	const messageTemplate = options.message ?? defaultMessageTemplate;
-	assertNoReservedTemplateVariables(options.name, messageTemplate);
-	const interpolate = compileMessageInterpolator(messageTemplate);
-	class GeneratedTaggedError extends BaseError {
-		static tag = options.name;
-		_tag = options.name;
-		fingerprint = [options.name, messageTemplate];
-		messageTemplate = messageTemplate;
-		constructor(props) {
-			const message = interpolate(props);
-			super(message, getErrorOptions(props?.cause));
-			this.name = options.name;
-			if (props) {
-				for (const [key, value] of Object.entries(props)) if (!reservedTemplateVariables.has(key)) assignReadonly(this, key, value);
-			}
-		}
-		static is(value) {
-			return value instanceof this;
-		}
-		static err(...args) {
-			return err(new this(...args));
-		}
-		findCause(ErrorClass) {
-			return findCause(this, ErrorClass);
-		}
-		toJSON() {
-			const json = {
-				_tag: this._tag,
-				fingerprint: this.fingerprint,
-				message: this.message,
-				messageTemplate: this.messageTemplate,
-				name: this.name
-			};
-			if (this.cause !== void 0) json["cause"] = serializeCause(this.cause);
-			for (const [key, value] of Object.entries(this)) if (!(key in json) && key !== "cause" && key !== "stack") json[key] = serializeTaggedValue(value);
-			return json;
-		}
-	}
-	return GeneratedTaggedError;
-}
-const taggedEnum = () => {
-	return new Proxy({
-		$is(tag, value) {
-			return typeof value === "object" && value !== null && "_tag" in value && value._tag === tag;
-		},
-		$match(value, handlers) {
-			const handler = handlers[value._tag];
-			if (handler === void 0) throw new Error(`No tagged enum handler for ${String(value._tag)}`);
-			return handler(value);
-		}
-	}, { get(base, property, receiver) {
-		if (property in base) return Reflect.get(base, property, receiver);
-		if (typeof property !== "string") return;
-		return (props) => {
-			const value = { _tag: property };
-			if (props !== void 0) {
-				for (const [key, propValue] of Object.entries(props)) if (key !== "_tag") value[key] = propValue;
-			}
-			return Object.freeze(value);
-		};
-	} });
-};
-const matchError = (error, handlers) => {
-	if ("_tag" in error && typeof error._tag === "string" && error._tag in handlers) {
-		const handler = handlers[error._tag];
-		return handler(error);
-	}
-	if (handlers.Error) return handlers.Error(error);
-	throw error;
-};
-const matchErrorPartial = (error, handlers, fallback) => {
-	if ("_tag" in error && typeof error._tag === "string" && error._tag in handlers) {
-		const handler = handlers[error._tag];
-		if (handler) return handler(error);
-	}
-	if (handlers.Error) return handlers.Error(error);
-	return fallback(error);
-};
-//#endregion
-export { AbortError, DisposableResult, DisposableResultAsync, Result, ResultAsync, createTaggedError, tryResult as default, tryResult as try, tryResult, err, errAsync, findCause, fromPromise, fromSafePromise, fromThrowable, fromThrowableAsync, isAbortError, isError, isRedacted, matchError, matchErrorPartial, ok, okAsync, redact, revealRedacted, safeTry, taggedEnum, tryResultAsync as tryAsync, tryResultAsync, tryCatch, tryCatchAsync, unit, unitAsync };
-
-//# sourceMappingURL=index.js.map
+export { AbortError, DisposableResult, DisposableResultAsync, Result, ResultAsync, createTaggedError, tryResult as default, tryResult as try, tryResult, err, errAsync, findCause, fromCallback, fromPromise, fromSafePromise, fromThrowable, fromThrowableAsync, isAbortError, isError, isRedacted, matchError, matchErrorPartial, ok, okAsync, redact, revealRedacted, runPromise, runSync, safeTry, taggedEnum, tryResultAsync as tryAsync, tryResultAsync, tryCatch, tryCatchAsync, unit, unitAsync };