@zireal/result-kit 1.0.0 → 1.0.2

package/dist/nest/index.d.mts

@@ -1,20 +1,91 @@
-import { n as Result } from "../result-CI_HBDHK.mjs";
+import { n as Result } from "../result-hklHYniG.mjs";
 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 };

package/dist/nest/index.mjs

@@ -1,9 +1,29 @@
-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 { HttpException, HttpStatus, InternalServerErrorException } from "@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 ?? HttpStatus.INTERNAL_SERVER_ERROR;
 	return new HttpException({
@@ -13,6 +33,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 HttpException) return mapped;
@@ -32,10 +67,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 (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
 export { toHttpException, unwrapOrThrow, unwrapPromise };

package/dist/result-DdlZMLaP.d.cts

@@ -0,0 +1,44 @@
+//#region src/core/result.d.ts
+/**
+ * Represents the successful branch of a {@link Result}.
+ *
+ * Use this shape when an operation completed normally and produced a value
+ * that should continue through the rest of the pipeline.
+ */
+interface Success<T> {
+  /**
+   * Discriminant used to identify successful results at runtime.
+   */
+  readonly ok: true;
+  /**
+   * Value produced by the successful operation.
+   */
+  readonly value: T;
+}
+/**
+ * Represents the failed branch of a {@link Result}.
+ *
+ * Use this shape when an operation did not produce a value and instead
+ * returned domain, validation, transport, or infrastructure error data.
+ */
+interface Failure<E> {
+  /**
+   * Discriminant used to identify failed results at runtime.
+   */
+  readonly ok: false;
+  /**
+   * Error payload carried by the failed operation.
+   */
+  readonly error: E;
+}
+/**
+ * Models an operation that can either succeed with a value of `T`
+ * or fail with an error of `E`.
+ *
+ * This is the package's core transport type for explicit, exception-free
+ * control flow.
+ */
+type Result<T, E> = Success<T> | Failure<E>;
+//#endregion
+export { Result as n, Success as r, Failure as t };
+//# sourceMappingURL=result-DdlZMLaP.d.cts.map

package/dist/result-hklHYniG.d.mts

@@ -0,0 +1,44 @@
+//#region src/core/result.d.ts
+/**
+ * Represents the successful branch of a {@link Result}.
+ *
+ * Use this shape when an operation completed normally and produced a value
+ * that should continue through the rest of the pipeline.
+ */
+interface Success<T> {
+  /**
+   * Discriminant used to identify successful results at runtime.
+   */
+  readonly ok: true;
+  /**
+   * Value produced by the successful operation.
+   */
+  readonly value: T;
+}
+/**
+ * Represents the failed branch of a {@link Result}.
+ *
+ * Use this shape when an operation did not produce a value and instead
+ * returned domain, validation, transport, or infrastructure error data.
+ */
+interface Failure<E> {
+  /**
+   * Discriminant used to identify failed results at runtime.
+   */
+  readonly ok: false;
+  /**
+   * Error payload carried by the failed operation.
+   */
+  readonly error: E;
+}
+/**
+ * Models an operation that can either succeed with a value of `T`
+ * or fail with an error of `E`.
+ *
+ * This is the package's core transport type for explicit, exception-free
+ * control flow.
+ */
+type Result<T, E> = Success<T> | Failure<E>;
+//#endregion
+export { Result as n, Success as r, Failure as t };
+//# sourceMappingURL=result-hklHYniG.d.mts.map