@zireal/result-kit 1.0.0 → 1.0.2

package/dist/index-SLgCKCJe.d.mts

@@ -0,0 +1,482 @@
+import { n as Result, r as Success, t as Failure } from "./result-hklHYniG.mjs";
+
+//#region src/core/error.d.ts
+/**
+ * Structured application error shape used throughout the package.
+ *
+ * `TypedError` gives failures a stable string discriminator through `type`
+ * while preserving a human-readable `message` and optional machine-readable
+ * metadata.
+ */
+interface TypedError<TType extends string = string> {
+  /**
+   * Stable error discriminator used for narrowing, branching, and mapping.
+   */
+  readonly type: TType;
+  /**
+   * Human-readable description of the failure.
+   */
+  readonly message: string;
+  /**
+   * Optional serializable metadata describing the failure context.
+   */
+  readonly details?: Record<string, unknown>;
+  /**
+   * Optional original cause for debugging or tracing.
+   */
+  readonly cause?: unknown;
+}
+/**
+ * Alias that makes it explicit that a typed error is constrained to one
+ * concrete discriminator.
+ */
+type TypedErrorOf<TType extends string> = TypedError<TType>;
+/**
+ * Produces a union of {@link TypedError} variants from a union of string
+ * discriminators.
+ *
+ * This is useful for defining domain-specific error unions such as
+ * `"not_found" | "validation_error"`.
+ */
+type TypedErrorUnion<TType extends string> = TType extends string ? TypedError<TType> : never;
+/**
+ * Determines whether an unknown value satisfies the runtime contract of
+ * {@link TypedError}.
+ *
+ * A valid typed error must be an object with string `type` and `message`
+ * fields. When present, `details` must be a plain object-like record rather
+ * than `null` or an array.
+ *
+ * @param error Value to validate at runtime.
+ * @returns `true` when `error` matches the expected structured error shape.
+ */
+declare const isTypedError: (error: unknown) => error is TypedError<string>;
+//#endregion
+//#region src/core/result-kit.d.ts
+/**
+ * Static utilities for creating, transforming, inspecting, and consuming
+ * {@link Result} values.
+ *
+ * The class is intentionally abstract because it acts as a namespaced toolbox
+ * rather than a type meant to be instantiated.
+ */
+declare abstract class ResultKit {
+  /**
+   * Determines whether a result contains a successful value.
+   *
+   * Use this as a type guard when branching manually over a {@link Result}.
+   *
+   * @param result Result to inspect.
+   * @returns `true` when `result` is a {@link Success}.
+   */
+  static isSuccess<T, E>(result: Result<T, E>): result is Success<T>;
+  /**
+   * Determines whether a result contains a failure value.
+   *
+   * Use this as a type guard when branching manually over a {@link Result}.
+   *
+   * @param result Result to inspect.
+   * @returns `true` when `result` is a {@link Failure}.
+   */
+  static isFailure<T, E>(result: Result<T, E>): result is Failure<E>;
+  /**
+   * Constructs a successful result.
+   *
+   * Prefer this helper over hand-writing `{ ok: true, value }` so result
+   * creation stays uniform across the codebase.
+   *
+   * @param value Successful value to wrap.
+   * @returns A {@link Success} containing `value`.
+   */
+  static success<T>(value: T): Success<T>;
+  /**
+   * Constructs a failed result with any error payload.
+   *
+   * This is the generic failure constructor for non-`TypedError` failures.
+   *
+   * @param error Error payload to wrap.
+   * @returns A {@link Failure} containing `error`.
+   */
+  static failure<E>(error: E): Failure<E>;
+  /**
+   * Constructs a failed result from a {@link TypedError}.
+   *
+   * This is a convenience wrapper around {@link ResultKit.failure} for the
+   * package's structured error convention.
+   *
+   * @param error Structured error payload to wrap.
+   * @returns A failed result carrying the provided typed error.
+   */
+  static fail<T extends string>(error: TypedError<T>): Failure<TypedError<T>>;
+  /**
+   * Determines whether an unknown value satisfies the runtime shape of
+   * {@link TypedError}.
+   *
+   * @param error Value to validate.
+   * @returns `true` when `error` looks like a typed error object.
+   */
+  static isTypedError(error: unknown): error is TypedError<string>;
+  /**
+   * Transforms the success value of a result while leaving failures untouched.
+   *
+   * Use this when you want to project successful data without changing the
+   * failure channel.
+   *
+   * @param result Result whose success value may be transformed.
+   * @param fn Mapping function applied only when `result` is successful.
+   * @returns A new successful result with the mapped value, or the original
+   * failure when `result` is unsuccessful.
+   */
+  static map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+  /**
+   * Transforms both branches of a result in one operation.
+   *
+   * Use this when success and failure values both need projection into new
+   * shapes.
+   *
+   * @param result Result to transform.
+   * @param onSuccess Mapper applied when `result` is successful.
+   * @param onFailure Mapper applied when `result` is failed.
+   * @returns A result whose success and failure payloads have been mapped into
+   * the target types.
+   */
+  static bimap<T, U, E, F>(result: Result<T, E>, onSuccess: (value: T) => U, onFailure: (error: E) => F): Result<U, F>;
+  /**
+   * Asynchronously transforms the success value of a result.
+   *
+   * Failures are returned unchanged and `fn` is never invoked for them.
+   *
+   * @param result Result whose success value may be transformed.
+   * @param fn Async mapping function applied only when `result` is successful.
+   * @returns A promise resolving to a mapped success result or the original
+   * failure.
+   */
+  static mapAsync<T, U, E>(result: Result<T, E>, fn: (value: T) => Promise<U>): Promise<Result<U, E>>;
+  /**
+   * Transforms the failure value of a result while leaving successes untouched.
+   *
+   * @param result Result whose error may be transformed.
+   * @param fn Mapping function applied only when `result` is failed.
+   * @returns The original success result or a new failed result containing the
+   * mapped error.
+   */
+  static mapError<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+  /**
+   * Asynchronously transforms the failure value of a result.
+   *
+   * Success values are returned unchanged and `fn` is never invoked for them.
+   *
+   * @param result Result whose error may be transformed.
+   * @param fn Async mapping function applied only when `result` is failed.
+   * @returns A promise resolving to the original success result or a new failed
+   * result containing the mapped error.
+   */
+  static mapErrorAsync<T, E, F>(result: Result<T, E>, fn: (error: E) => Promise<F>): Promise<Result<T, F>>;
+  /**
+   * Chains another result-producing operation onto a successful result.
+   *
+   * This is the standard flat-mapping operation for the success branch and is
+   * useful for sequencing dependent computations without nesting `Result`
+   * values.
+   *
+   * @param result Result to continue from.
+   * @param fn Function invoked only when `result` is successful.
+   * @returns The chained result, or the original failure unchanged.
+   */
+  static andThen<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+  /**
+   * Asynchronously chains another result-producing operation onto a successful
+   * result.
+   *
+   * @param result Result to continue from.
+   * @param fn Async function invoked only when `result` is successful.
+   * @returns A promise resolving to the chained result or the original failure.
+   */
+  static andThenAsync<T, U, E>(result: Result<T, E>, fn: (value: T) => Promise<Result<U, E>>): Promise<Result<U, E>>;
+  /**
+   * Recovers from a failed result by mapping it into a new result.
+   *
+   * Use this to provide fallback logic, error translation, or alternate
+   * retrieval paths for the failure branch.
+   *
+   * @param result Result to recover from.
+   * @param fn Recovery function invoked only when `result` is failed.
+   * @returns The original success result or the recovery result.
+   */
+  static orElse<T, E, F>(result: Result<T, E>, fn: (error: E) => Result<T, F>): Result<T, F>;
+  /**
+   * Asynchronously recovers from a failed result by mapping it into a new
+   * result.
+   *
+   * @param result Result to recover from.
+   * @param fn Async recovery function invoked only when `result` is failed.
+   * @returns A promise resolving to the original success result or the recovery
+   * result.
+   */
+  static orElseAsync<T, E, F>(result: Result<T, E>, fn: (error: E) => Promise<Result<T, F>>): Promise<Result<T, F>>;
+  /**
+   * Extracts the success value from a result when present.
+   *
+   * This helper is intentionally non-throwing. Failures resolve to
+   * `undefined`, making it suitable when absence is acceptable.
+   *
+   * @param result Result to unwrap.
+   * @returns The success value, or `undefined` when the result is failed.
+   */
+  static unwrap<T, E>(result: Result<T, E>): T | undefined;
+  /**
+   * Extracts the value from a known {@link Success}.
+   *
+   * Use this when the success branch has already been narrowed and you want a
+   * small semantic wrapper around direct property access.
+   *
+   * @param result Successful result to unwrap.
+   * @returns The contained success value.
+   */
+  static unwrapSuccess<T>(result: Success<T>): T;
+  /**
+   * Extracts the error from a known {@link Failure}.
+   *
+   * Use this when the failure branch has already been narrowed and you want a
+   * small semantic wrapper around direct property access.
+   *
+   * @param result Failed result to unwrap.
+   * @returns The contained error value.
+   */
+  static unwrapFailure<E>(result: Failure<E>): E;
+  /**
+   * Extracts the success value or returns a provided fallback.
+   *
+   * The fallback is evaluated eagerly before the call, so use
+   * {@link ResultKit.unwrapOrElse} when computing the fallback is expensive.
+   *
+   * @param result Result to unwrap.
+   * @param defaultValue Value to return when `result` is failed.
+   * @returns The success value or `defaultValue`.
+   */
+  static unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
+  /**
+   * Extracts the success value or computes a fallback from the failure.
+   *
+   * The fallback callback is evaluated lazily and receives the failure value.
+   *
+   * @param result Result to unwrap.
+   * @param fn Function used to derive a fallback from the error.
+   * @returns The success value or the callback result.
+   */
+  static unwrapOrElse<T, E>(result: Result<T, E>, fn: (error: E) => T): T;
+  /**
+   * Asynchronously extracts the success value or computes a fallback from the
+   * failure.
+   *
+   * @param result Result to unwrap.
+   * @param fn Async function used to derive a fallback from the error.
+   * @returns A promise resolving to the success value or the callback result.
+   */
+  static unwrapOrElseAsync<T, E>(result: Result<T, E>, fn: (error: E) => Promise<T>): Promise<T>;
+  /**
+   * Folds a result into a single output value.
+   *
+   * This is useful at application boundaries where both branches need to
+   * produce the same final shape.
+   *
+   * @param result Result to match against.
+   * @param handlers Branch handlers for success and failure.
+   * @returns The value returned by the matching handler.
+   */
+  static match<T, E, U>(result: Result<T, E>, handlers: {
+    onSuccess: (value: T) => U;
+    onFailure: (error: E) => U;
+  }): U;
+  /**
+   * Asynchronously folds a result into a single output value.
+   *
+   * @param result Result to match against.
+   * @param handlers Async branch handlers for success and failure.
+   * @returns A promise resolving to the value returned by the matching handler.
+   */
+  static matchAsync<T, E, U>(result: Result<T, E>, handlers: {
+    onSuccess: (value: T) => Promise<U>;
+    onFailure: (error: E) => Promise<U>;
+  }): Promise<U>;
+  /**
+   * Runs side effects for a result branch and returns the original result.
+   *
+   * Use this for logging, metrics, tracing, or other observational work that
+   * should not change the result payload.
+   *
+   * @param result Result to observe.
+   * @param handlers Optional side-effect handlers for either branch.
+   * @returns The original `result` instance.
+   */
+  static tap<T, E>(result: Result<T, E>, handlers: {
+    onSuccess?: (value: T) => void;
+    onFailure?: (error: E) => void;
+  }): Result<T, E>;
+  /**
+   * Asynchronously runs side effects for a result branch and returns the
+   * original result.
+   *
+   * @param result Result to observe.
+   * @param handlers Optional async side-effect handlers for either branch.
+   * @returns A promise resolving to the original `result` instance after side
+   * effects complete.
+   */
+  static tapAsync<T, E>(result: Result<T, E>, handlers: {
+    onSuccess?: (value: T) => Promise<void>;
+    onFailure?: (error: E) => Promise<void>;
+  }): Promise<Result<T, E>>;
+  /**
+   * Combines an array of results into a single result of an array.
+   *
+   * Combination short-circuits on the first failure encountered. When every
+   * result succeeds, the returned success contains the collected values in the
+   * same order as the input array.
+   *
+   * @param results Results to combine.
+   * @returns A success containing all values, or the first failure encountered.
+   */
+  static combine<T, E>(results: Result<T, E>[]): Result<T[], E>;
+  /**
+   * Asynchronously combines multiple promised results into one result.
+   *
+   * All promises are awaited before combination, so this helper does not stop
+   * pending asynchronous work after an eventual failure.
+   *
+   * @param results Promises resolving to results.
+   * @returns A promise resolving to the same output as {@link ResultKit.combine}.
+   */
+  static combineAsync<T, E>(results: Promise<Result<T, E>>[]): Promise<Result<T[], E>>;
+  /**
+   * Combines an array of results while collecting every failure.
+   *
+   * Successful values are preserved in order. If one or more failures occur,
+   * the returned failure contains an array of all collected errors rather than
+   * only the first one.
+   *
+   * @param results Results to combine.
+   * @returns A success containing all values when every result succeeds, or a
+   * failure containing all collected errors.
+   */
+  static combineWithAllErrors<T, E>(results: Result<T, E>[]): Result<T[], E[]>;
+  /**
+   * Asynchronously combines multiple promised results while collecting every
+   * failure.
+   *
+   * As with {@link ResultKit.combineAsync}, all promises are awaited before
+   * reduction.
+   *
+   * @param results Promises resolving to results.
+   * @returns A promise resolving to the same output as
+   * {@link ResultKit.combineWithAllErrors}.
+   */
+  static combineWithAllErrorsAsync<T, E>(results: Promise<Result<T, E>>[]): Promise<Result<T[], E[]>>;
+  /**
+   * Removes one layer of `Result` nesting from the success branch.
+   *
+   * This is useful after operations that already return a `Result` have been
+   * wrapped in another success result.
+   *
+   * @param result Nested result to flatten.
+   * @returns The inner result when successful, or the outer failure unchanged.
+   */
+  static flatten<T, E>(result: Result<Result<T, E>, E>): Result<T, E>;
+  /**
+   * Converts a promise that may reject into a promise of `Result`.
+   *
+   * Rejections are caught and normalized through `errorFn`, allowing async
+   * exception sources to participate in explicit result-based control flow.
+   *
+   * @param promise Promise to execute.
+   * @param errorFn Function used to convert an unknown rejection reason into
+   * the desired error type.
+   * @returns A promise resolving to a successful result for fulfilled values or
+   * a failed result for rejected values.
+   */
+  static fromPromise<T, E>(promise: Promise<T>, errorFn: (error: unknown) => E): Promise<Result<T, E>>;
+  /**
+   * Wraps a synchronous function so thrown exceptions are returned as failures.
+   *
+   * The resulting function preserves the original parameter list while
+   * converting thrown errors with `errorFn`.
+   *
+   * @param fn Function that may throw.
+   * @param errorFn Function used to map an unknown thrown value into the
+   * desired error type.
+   * @returns A new function that returns `Result` instead of throwing.
+   */
+  static fromThrowable<Args extends unknown[], T, E>(fn: (...args: Args) => T, errorFn: (error: unknown) => E): (...args: Args) => Result<T, E>;
+  /**
+   * Wraps an asynchronous function so thrown exceptions and rejected promises
+   * are returned as failures.
+   *
+   * @param fn Async function that may throw or reject.
+   * @param errorFn Function used to map an unknown failure reason into the
+   * desired error type.
+   * @returns A new function that resolves to `Result` instead of propagating
+   * exceptions.
+   */
+  static fromThrowableAsync<Args extends unknown[], T, E>(fn: (...args: Args) => Promise<T>, errorFn: (error: unknown) => E): (...args: Args) => Promise<Result<T, E>>;
+  /**
+   * Converts a nullable value into a result.
+   *
+   * `null` and `undefined` become failures carrying the provided error. Any
+   * other value becomes a success and is narrowed to `NonNullable<T>`.
+   *
+   * @param value Value to check for nullability.
+   * @param error Error to return when `value` is nullish.
+   * @returns A success for non-nullish values or a failure for nullish values.
+   */
+  static fromNullable<T, E>(value: T | null | undefined, error: E): Result<NonNullable<T>, E>;
+  /**
+   * Converts a predicate check into a result.
+   *
+   * @param value Value to validate.
+   * @param predicate Predicate that determines whether `value` is acceptable.
+   * @param error Error to return when the predicate fails.
+   * @returns A success containing `value` when the predicate passes, otherwise
+   * a failure containing `error`.
+   */
+  static fromPredicate<T, E>(value: T, predicate: (value: T) => boolean, error: E): Result<T, E>;
+  /**
+   * Converts a result into a nullable value.
+   *
+   * Use this when crossing into APIs that model absence with `null` rather
+   * than an explicit failure channel.
+   *
+   * @param result Result to convert.
+   * @returns The success value or `null` when the result is failed.
+   */
+  static toNullable<T, E>(result: Result<T, E>): T | null;
+  /**
+   * Splits an array of results into parallel arrays of successes and failures.
+   *
+   * Ordering is preserved independently within each returned array.
+   *
+   * @param results Results to partition.
+   * @returns A tuple containing successful values at index `0` and failure
+   * values at index `1`.
+   */
+  static partition<T, E>(results: Result<T, E>[]): [T[], E[]];
+  /**
+   * Collects only the success values from an array of results.
+   *
+   * Failures are discarded.
+   *
+   * @param results Results to filter.
+   * @returns An array of success values in input order.
+   */
+  static filterSuccesses<T, E>(results: Result<T, E>[]): T[];
+  /**
+   * Collects only the failure values from an array of results.
+   *
+   * Successes are discarded.
+   *
+   * @param results Results to filter.
+   * @returns An array of failure values in input order.
+   */
+  static filterFailures<T, E>(results: Result<T, E>[]): E[];
+}
+//#endregion
+export { isTypedError as a, TypedErrorUnion as i, TypedError as n, TypedErrorOf as r, ResultKit as t };
+//# sourceMappingURL=index-SLgCKCJe.d.mts.map

package/dist/index.cjs

@@ -1,5 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_result_kit = require("./result-kit-Ck1xAp-J.cjs");
+const require_result_kit = require("./result-kit-DdhY1ph2.cjs");
 require("./core/index.cjs");
 exports.ResultKit = require_result_kit.ResultKit;
 exports.isTypedError = require_result_kit.isTypedError;

package/dist/index.d.cts

@@ -1,3 +1,3 @@
-import { a as isTypedError, i as TypedErrorUnion, n as TypedError, r as TypedErrorOf, t as ResultKit } from "./index-EJ_Ol5Fu.cjs";
-import { n as Result, r as Success, t as Failure } from "./result-DbQ8o1Cs.cjs";
+import { a as isTypedError, i as TypedErrorUnion, n as TypedError, r as TypedErrorOf, t as ResultKit } from "./index-DioLW1WH.cjs";
+import { n as Result, r as Success, t as Failure } from "./result-DdlZMLaP.cjs";
 export { Failure, Result, ResultKit, Success, TypedError, TypedErrorOf, TypedErrorUnion, isTypedError };

package/dist/index.d.mts

@@ -1,3 +1,3 @@
-import { a as isTypedError, i as TypedErrorUnion, n as TypedError, r as TypedErrorOf, t as ResultKit } from "./index-Ch6k0lVU.mjs";
-import { n as Result, r as Success, t as Failure } from "./result-CI_HBDHK.mjs";
+import { a as isTypedError, i as TypedErrorUnion, n as TypedError, r as TypedErrorOf, t as ResultKit } from "./index-SLgCKCJe.mjs";
+import { n as Result, r as Success, t as Failure } from "./result-hklHYniG.mjs";
 export { Failure, Result, ResultKit, Success, TypedError, TypedErrorOf, TypedErrorUnion, isTypedError };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { n as isTypedError, t as ResultKit } from "./result-kit-C5ZY61pO.mjs";
+import { n as isTypedError, t as ResultKit } from "./result-kit-pgireOSz.mjs";
 import "./core/index.mjs";
 export { ResultKit, isTypedError };

package/dist/nest/index.cjs

@@ -1,10 +1,30 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
-const require_result_kit = require("../result-kit-Ck1xAp-J.cjs");
+const require_result_kit = require("../result-kit-DdhY1ph2.cjs");
 let _nestjs_common = require("@nestjs/common");
 //#region src/nest/http.ts
+/**
+* Default message used when the incoming error value does not expose a usable
+* message.
+*/
 const DEFAULT_UNKNOWN_MESSAGE = "An unknown error occurred";
+/**
+* Default application error code used for internal server failures.
+*/
 const DEFAULT_ERROR_CODE = "INTERNAL_SERVER_ERROR";
+/**
+* Normalizes an arbitrary error type string into an uppercase code suitable
+* for HTTP responses.
+*
+* @param value Raw error type value.
+* @returns A sanitized, uppercase error code or the internal default code.
+*/
 const normalizeErrorCode = (value) => value.trim().replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase() || DEFAULT_ERROR_CODE;
+/**
+* Builds a Nest `HttpException` from a lightweight descriptor object.
+*
+* @param descriptor Response descriptor to convert.
+* @returns A concrete `HttpException` with normalized payload defaults.
+*/
 const toHttpExceptionFromDescriptor = (descriptor) => {
 	const status = descriptor.status ?? _nestjs_common.HttpStatus.INTERNAL_SERVER_ERROR;
 	return new _nestjs_common.HttpException({
@@ -14,6 +34,21 @@ const toHttpExceptionFromDescriptor = (descriptor) => {
 		...descriptor.error ? { error: descriptor.error } : {}
 	}, status);
 };
+/**
+* Converts an arbitrary error value into a Nest `HttpException`.
+*
+* Resolution order is:
+* 1. `options.mapError` returning a `HttpException`
+* 2. `options.mapError` returning a {@link HttpExceptionDescriptor}
+* 3. An incoming `HttpException`
+* 4. A core typed error
+* 5. A generic JavaScript `Error`
+* 6. An unknown fallback internal server error
+*
+* @param error Error value to convert.
+* @param options Optional mapping and fallback configuration.
+* @returns A Nest `HttpException` representing the provided error.
+*/
 const toHttpException = (error, options) => {
 	const mapped = options?.mapError?.(error);
 	if (mapped instanceof _nestjs_common.HttpException) return mapped;
@@ -33,10 +68,33 @@ const toHttpException = (error, options) => {
 		message: options?.fallbackMessage || DEFAULT_UNKNOWN_MESSAGE
 	});
 };
+/**
+* Extracts the success value from a result or throws an HTTP exception derived
+* from the failure.
+*
+* This is intended for Nest controller and adapter boundaries where a result
+* should be converted into framework-native exception flow.
+*
+* @param result Result to unwrap.
+* @param options Optional error mapping and fallback configuration.
+* @returns The successful value when `result` is successful.
+* @throws {HttpException} When `result` is failed.
+*/
 const unwrapOrThrow = (result, options) => {
 	if (require_result_kit.ResultKit.isSuccess(result)) return result.value;
 	throw toHttpException(result.error, options);
 };
+/**
+* Awaits a promised result and extracts its success value or throws a mapped
+* HTTP exception.
+*
+* Use this when service methods already resolve to `Promise<Result<...>>`.
+*
+* @param promise Promise resolving to a result.
+* @param options Optional error mapping and fallback configuration.
+* @returns A promise resolving to the successful value.
+* @throws {HttpException} When the resolved result is failed.
+*/
 const unwrapPromise = async (promise, options) => unwrapOrThrow(await promise, options);
 //#endregion
 exports.toHttpException = toHttpException;

package/dist/nest/index.d.cts

@@ -1,20 +1,91 @@
-import { n as Result } from "../result-DbQ8o1Cs.cjs";
+import { n as Result } from "../result-DdlZMLaP.cjs";
 import { HttpException } from "@nestjs/common";
 
 //#region src/nest/http.d.ts
+/**
+ * Describes the HTTP exception payload that should be produced for a failure.
+ *
+ * Returning this shape from `mapError` lets callers control HTTP status and
+ * response body without constructing a Nest `HttpException` instance
+ * themselves.
+ */
 interface HttpExceptionDescriptor {
+  /**
+   * HTTP status code to use for the generated exception.
+   */
   readonly status?: number;
+  /**
+   * Stable application error code included in the response body.
+   */
   readonly code?: string | number;
+  /**
+   * Human-readable error message included in the response body.
+   */
   readonly message?: string;
+  /**
+   * Optional structured metadata added to the response body.
+   */
   readonly details?: Record<string, unknown>;
+  /**
+   * Optional top-level Nest-style error label.
+   */
   readonly error?: string;
 }
+/**
+ * Configures how result failures should be mapped into Nest HTTP exceptions.
+ */
 interface NestErrorOptions<E> {
+  /**
+   * Optional custom mapper for converting a domain error into either a ready
+   * `HttpException` or a descriptor used to build one.
+   */
   readonly mapError?: (error: E) => HttpException | HttpExceptionDescriptor | undefined;
+  /**
+   * Fallback message used for unknown failures when a better message cannot be
+   * derived from the error value.
+   */
   readonly fallbackMessage?: string;
 }
+/**
+ * Converts an arbitrary error value into a Nest `HttpException`.
+ *
+ * Resolution order is:
+ * 1. `options.mapError` returning a `HttpException`
+ * 2. `options.mapError` returning a {@link HttpExceptionDescriptor}
+ * 3. An incoming `HttpException`
+ * 4. A core typed error
+ * 5. A generic JavaScript `Error`
+ * 6. An unknown fallback internal server error
+ *
+ * @param error Error value to convert.
+ * @param options Optional mapping and fallback configuration.
+ * @returns A Nest `HttpException` representing the provided error.
+ */
 declare const toHttpException: <E>(error: E, options?: NestErrorOptions<E>) => HttpException;
+/**
+ * Extracts the success value from a result or throws an HTTP exception derived
+ * from the failure.
+ *
+ * This is intended for Nest controller and adapter boundaries where a result
+ * should be converted into framework-native exception flow.
+ *
+ * @param result Result to unwrap.
+ * @param options Optional error mapping and fallback configuration.
+ * @returns The successful value when `result` is successful.
+ * @throws {HttpException} When `result` is failed.
+ */
 declare const unwrapOrThrow: <T, E>(result: Result<T, E>, options?: NestErrorOptions<E>) => T;
+/**
+ * Awaits a promised result and extracts its success value or throws a mapped
+ * HTTP exception.
+ *
+ * Use this when service methods already resolve to `Promise<Result<...>>`.
+ *
+ * @param promise Promise resolving to a result.
+ * @param options Optional error mapping and fallback configuration.
+ * @returns A promise resolving to the successful value.
+ * @throws {HttpException} When the resolved result is failed.
+ */
 declare const unwrapPromise: <T, E>(promise: Promise<Result<T, E>>, options?: NestErrorOptions<E>) => Promise<T>;
 //#endregion
 export { type HttpExceptionDescriptor, type NestErrorOptions, toHttpException, unwrapOrThrow, unwrapPromise };