resultar 3.3.0 → 3.4.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);
@@ -537,32 +547,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 +635,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,9 +651,19 @@ 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
@@ -1060,13 +1117,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;
@@ -1155,24 +1223,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,6 +1276,12 @@ 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 leftTask = startRaceTask(left, 0);
@@ -1205,6 +1307,9 @@ var ResultAsync = class ResultAsync extends Pipeable {
 			});
 		}));
 	}
+	/**
+	* Runs a cooperative ResultAsync task with a typed timeout error.
+	*/
 	static timeout(task, options) {
 		const timeoutTask = (signal) => {
 			return new ResultAsync(new Promise((resolve) => {
@@ -1227,6 +1332,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 +1342,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 +1376,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 +1390,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 +1449,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 +1477,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 +1505,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 +1524,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 +1537,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 +1550,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 +1562,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 +1624,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 +1641,31 @@ 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;
+/**
+* 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,6 +1675,13 @@ 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
@@ -1494,27 +1691,48 @@ const formatRedacted = (label) => label === void 0 ? "<redacted>" : `<redacted:$
 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 = /\$([a-zA-Z_][a-zA-Z0-9_]*)/gu;
+const templateVariableMatcher = /\$(?<name>[a-zA-Z_][a-zA-Z0-9_]*)/gu;
 const reservedTemplateVariables = new Set([
 	"_tag",
 	"cause",
@@ -1550,7 +1768,7 @@ const compileMessageInterpolator = (template) => (values) => template.replaceAll
 });
 const getTemplateVariableNames = (template) => {
 	templateVariableMatcher.lastIndex = 0;
-	return [...template.matchAll(templateVariableMatcher)].map((match) => String(match[1]));
+	return [...template.matchAll(templateVariableMatcher)].map((match) => String(match.groups?.["name"]));
 };
 const assertNoReservedTemplateVariables = (tag, template) => {
 	if (template === defaultMessageTemplate) return;
@@ -1584,6 +1802,9 @@ const serializeCause = (cause, seen = /* @__PURE__ */ new Set()) => {
 	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;
@@ -1594,6 +1815,19 @@ const findCause = (error, ErrorClass) => {
 		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;
@@ -1612,15 +1846,27 @@ function createTaggedError(options) {
 				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,
@@ -1636,6 +1882,9 @@ function createTaggedError(options) {
 	}
 	return GeneratedTaggedError;
 }
+/**
+* Creates a small tagged-union factory with member constructors, `$is`, and `$match`.
+*/
 const taggedEnum = () => {
 	return new Proxy({
 		$is(tag, value) {
@@ -1658,6 +1907,11 @@ const taggedEnum = () => {
 		};
 	} });
 };
+/**
+* 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];
@@ -1666,6 +1920,9 @@ const matchError = (error, handlers) => {
 	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];
@@ -1675,6 +1932,6 @@ const matchErrorPartial = (error, handlers, fallback) => {
 	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 };
+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, runPromise, runSync, safeTry, taggedEnum, tryResultAsync as tryAsync, tryResultAsync, tryCatch, tryCatchAsync, unit, unitAsync };
 
 //# sourceMappingURL=index.js.map