@zireal/result-kit 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ali Farooq
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,143 @@
+# @zireal/result-kit
+
+Type-safe result and structured error utilities for TypeScript, with optional NestJS adapters.
+
+## Packages
+
+- `@zireal/result-kit`
+- `@zireal/result-kit/core`
+- `@zireal/result-kit/nest`
+
+The package root re-exports the framework-agnostic core only. Nest-specific helpers live in `@zireal/result-kit/nest`.
+
+## Installation
+
+```bash
+pnpm add @zireal/result-kit
+```
+
+If you use the Nest adapter:
+
+```bash
+pnpm add @nestjs/common
+```
+
+## Core Concepts
+
+### `Result<T, E>`
+
+```ts
+type Result<T, E> = Success<T> | Failure<E>;
+```
+
+Use `Result` to model success and failure explicitly rather than throwing through your service layer.
+
+### `TypedError`
+
+```ts
+interface TypedError<TType extends string = string> {
+  type: TType;
+  message: string;
+  details?: Record<string, unknown>;
+  cause?: unknown;
+}
+```
+
+`TypedError` is the package’s structured error convention. You can still use any `E` with `Result<T, E>`, but `TypedError` works well for application and domain failures.
+
+## Core Usage
+
+```ts
+import {
+  ResultKit,
+  type Result,
+  type TypedErrorUnion,
+} from "@zireal/result-kit";
+
+type UserError = TypedErrorUnion<"not_found" | "validation_error">;
+
+const findUser = (id: string): Result<{ id: string }, UserError> => {
+  if (!id.trim()) {
+    return ResultKit.fail({
+      type: "validation_error",
+      message: "id is required",
+    });
+  }
+
+  if (id !== "123") {
+    return ResultKit.fail({
+      type: "not_found",
+      message: "User not found",
+      details: { id },
+    });
+  }
+
+  return ResultKit.success({ id });
+};
+```
+
+## Nest Usage
+
+```ts
+import { Controller, Get, Param } from "@nestjs/common";
+import { unwrapOrThrow } from "@zireal/result-kit/nest";
+
+@Controller("users")
+export class UserController {
+  constructor(private readonly service: UserService) {}
+
+  @Get(":id")
+  async getUser(@Param("id") id: string) {
+    return unwrapOrThrow(await this.service.findUser(id));
+  }
+}
+```
+
+Use a mapper when your domain error types need custom HTTP status behavior:
+
+```ts
+import { BadRequestException, NotFoundException } from "@nestjs/common";
+import { unwrapOrThrow } from "@zireal/result-kit/nest";
+import { ResultKit } from "@zireal/result-kit";
+
+const user = unwrapOrThrow(result, {
+  mapError: (error) => {
+    if (!ResultKit.isTypedError(error)) return undefined;
+    if (error.type === "validation_error") {
+      return new BadRequestException(error.message);
+    }
+    if (error.type === "not_found") {
+      return new NotFoundException(error.message);
+    }
+
+    return undefined;
+  },
+});
+```
+
+## API Surface
+
+### Core
+
+- `TypedError`, `TypedErrorOf`, `TypedErrorUnion`
+- `Success`, `Failure`, `Result`
+- `ResultKit.success`, `failure`, `fail`
+- `ResultKit.isSuccess`, `isFailure`, `isTypedError`
+- `ResultKit.map`, `mapAsync`, `mapError`, `mapErrorAsync`
+- `ResultKit.andThen`, `andThenAsync`, `orElse`, `orElseAsync`
+- `ResultKit.match`, `matchAsync`
+- `ResultKit.unwrap`, `unwrapSuccess`, `unwrapFailure`, `unwrapOr`, `unwrapOrElse`, `unwrapOrElseAsync`
+- `ResultKit.combine`, `combineAsync`, `combineWithAllErrors`, `combineWithAllErrorsAsync`
+- `ResultKit.fromNullable`, `fromPredicate`, `fromPromise`, `fromThrowable`, `fromThrowableAsync`
+- `ResultKit.partition`, `filterSuccesses`, `filterFailures`, `toNullable`, `flatten`
+
+### Nest
+
+- `toHttpException`
+- `unwrapOrThrow`
+- `unwrapPromise`
+
+## Examples
+
+- [`examples/core.ts`](./examples/core.ts)
+- [`examples/nest.ts`](./examples/nest.ts)

package/dist/core/index.cjs

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

package/dist/core/index.d.cts

@@ -0,0 +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";
+export { Failure, Result, ResultKit, Success, TypedError, TypedErrorOf, TypedErrorUnion, isTypedError };

package/dist/core/index.d.mts

@@ -0,0 +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";
+export { Failure, Result, ResultKit, Success, TypedError, TypedErrorOf, TypedErrorUnion, isTypedError };

package/dist/core/index.mjs

@@ -0,0 +1,2 @@
+import { n as isTypedError, t as ResultKit } from "../result-kit-C5ZY61pO.mjs";
+export { ResultKit, isTypedError };

package/dist/index-Ch6k0lVU.d.mts

@@ -0,0 +1,70 @@
+import { n as Result, r as Success, t as Failure } from "./result-CI_HBDHK.mjs";
+
+//#region src/core/error.d.ts
+interface TypedError<TType extends string = string> {
+  readonly type: TType;
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+  readonly cause?: unknown;
+}
+type TypedErrorOf<TType extends string> = TypedError<TType>;
+type TypedErrorUnion<TType extends string> = TType extends string ? TypedError<TType> : never;
+declare const isTypedError: (error: unknown) => error is TypedError<string>;
+//#endregion
+//#region src/core/result-kit.d.ts
+declare abstract class ResultKit {
+  static isSuccess<T, E>(result: Result<T, E>): result is Success<T>;
+  static isFailure<T, E>(result: Result<T, E>): result is Failure<E>;
+  static success<T>(value: T): Success<T>;
+  static failure<E>(error: E): Failure<E>;
+  static fail<T extends string>(error: TypedError<T>): Failure<TypedError<T>>;
+  static isTypedError(error: unknown): error is TypedError<string>;
+  static map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+  static bimap<T, U, E, F>(result: Result<T, E>, onSuccess: (value: T) => U, onFailure: (error: E) => F): Result<U, F>;
+  static mapAsync<T, U, E>(result: Result<T, E>, fn: (value: T) => Promise<U>): Promise<Result<U, E>>;
+  static mapError<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+  static mapErrorAsync<T, E, F>(result: Result<T, E>, fn: (error: E) => Promise<F>): Promise<Result<T, F>>;
+  static andThen<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+  static andThenAsync<T, U, E>(result: Result<T, E>, fn: (value: T) => Promise<Result<U, E>>): Promise<Result<U, E>>;
+  static orElse<T, E, F>(result: Result<T, E>, fn: (error: E) => Result<T, F>): Result<T, F>;
+  static orElseAsync<T, E, F>(result: Result<T, E>, fn: (error: E) => Promise<Result<T, F>>): Promise<Result<T, F>>;
+  static unwrap<T, E>(result: Result<T, E>): T | undefined;
+  static unwrapSuccess<T>(result: Success<T>): T;
+  static unwrapFailure<E>(result: Failure<E>): E;
+  static unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
+  static unwrapOrElse<T, E>(result: Result<T, E>, fn: (error: E) => T): T;
+  static unwrapOrElseAsync<T, E>(result: Result<T, E>, fn: (error: E) => Promise<T>): Promise<T>;
+  static match<T, E, U>(result: Result<T, E>, handlers: {
+    onSuccess: (value: T) => U;
+    onFailure: (error: E) => U;
+  }): U;
+  static matchAsync<T, E, U>(result: Result<T, E>, handlers: {
+    onSuccess: (value: T) => Promise<U>;
+    onFailure: (error: E) => Promise<U>;
+  }): Promise<U>;
+  static tap<T, E>(result: Result<T, E>, handlers: {
+    onSuccess?: (value: T) => void;
+    onFailure?: (error: E) => void;
+  }): Result<T, E>;
+  static tapAsync<T, E>(result: Result<T, E>, handlers: {
+    onSuccess?: (value: T) => Promise<void>;
+    onFailure?: (error: E) => Promise<void>;
+  }): Promise<Result<T, E>>;
+  static combine<T, E>(results: Result<T, E>[]): Result<T[], E>;
+  static combineAsync<T, E>(results: Promise<Result<T, E>>[]): Promise<Result<T[], E>>;
+  static combineWithAllErrors<T, E>(results: Result<T, E>[]): Result<T[], E[]>;
+  static combineWithAllErrorsAsync<T, E>(results: Promise<Result<T, E>>[]): Promise<Result<T[], E[]>>;
+  static flatten<T, E>(result: Result<Result<T, E>, E>): Result<T, E>;
+  static fromPromise<T, E>(promise: Promise<T>, errorFn: (error: unknown) => E): Promise<Result<T, E>>;
+  static fromThrowable<Args extends unknown[], T, E>(fn: (...args: Args) => T, errorFn: (error: unknown) => E): (...args: Args) => Result<T, E>;
+  static fromThrowableAsync<Args extends unknown[], T, E>(fn: (...args: Args) => Promise<T>, errorFn: (error: unknown) => E): (...args: Args) => Promise<Result<T, E>>;
+  static fromNullable<T, E>(value: T | null | undefined, error: E): Result<NonNullable<T>, E>;
+  static fromPredicate<T, E>(value: T, predicate: (value: T) => boolean, error: E): Result<T, E>;
+  static toNullable<T, E>(result: Result<T, E>): T | null;
+  static partition<T, E>(results: Result<T, E>[]): [T[], E[]];
+  static filterSuccesses<T, E>(results: Result<T, E>[]): T[];
+  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-Ch6k0lVU.d.mts.map

package/dist/index-EJ_Ol5Fu.d.cts

@@ -0,0 +1,70 @@
+import { n as Result, r as Success, t as Failure } from "./result-DbQ8o1Cs.cjs";
+
+//#region src/core/error.d.ts
+interface TypedError<TType extends string = string> {
+  readonly type: TType;
+  readonly message: string;
+  readonly details?: Record<string, unknown>;
+  readonly cause?: unknown;
+}
+type TypedErrorOf<TType extends string> = TypedError<TType>;
+type TypedErrorUnion<TType extends string> = TType extends string ? TypedError<TType> : never;
+declare const isTypedError: (error: unknown) => error is TypedError<string>;
+//#endregion
+//#region src/core/result-kit.d.ts
+declare abstract class ResultKit {
+  static isSuccess<T, E>(result: Result<T, E>): result is Success<T>;
+  static isFailure<T, E>(result: Result<T, E>): result is Failure<E>;
+  static success<T>(value: T): Success<T>;
+  static failure<E>(error: E): Failure<E>;
+  static fail<T extends string>(error: TypedError<T>): Failure<TypedError<T>>;
+  static isTypedError(error: unknown): error is TypedError<string>;
+  static map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>;
+  static bimap<T, U, E, F>(result: Result<T, E>, onSuccess: (value: T) => U, onFailure: (error: E) => F): Result<U, F>;
+  static mapAsync<T, U, E>(result: Result<T, E>, fn: (value: T) => Promise<U>): Promise<Result<U, E>>;
+  static mapError<T, E, F>(result: Result<T, E>, fn: (error: E) => F): Result<T, F>;
+  static mapErrorAsync<T, E, F>(result: Result<T, E>, fn: (error: E) => Promise<F>): Promise<Result<T, F>>;
+  static andThen<T, U, E>(result: Result<T, E>, fn: (value: T) => Result<U, E>): Result<U, E>;
+  static andThenAsync<T, U, E>(result: Result<T, E>, fn: (value: T) => Promise<Result<U, E>>): Promise<Result<U, E>>;
+  static orElse<T, E, F>(result: Result<T, E>, fn: (error: E) => Result<T, F>): Result<T, F>;
+  static orElseAsync<T, E, F>(result: Result<T, E>, fn: (error: E) => Promise<Result<T, F>>): Promise<Result<T, F>>;
+  static unwrap<T, E>(result: Result<T, E>): T | undefined;
+  static unwrapSuccess<T>(result: Success<T>): T;
+  static unwrapFailure<E>(result: Failure<E>): E;
+  static unwrapOr<T, E>(result: Result<T, E>, defaultValue: T): T;
+  static unwrapOrElse<T, E>(result: Result<T, E>, fn: (error: E) => T): T;
+  static unwrapOrElseAsync<T, E>(result: Result<T, E>, fn: (error: E) => Promise<T>): Promise<T>;
+  static match<T, E, U>(result: Result<T, E>, handlers: {
+    onSuccess: (value: T) => U;
+    onFailure: (error: E) => U;
+  }): U;
+  static matchAsync<T, E, U>(result: Result<T, E>, handlers: {
+    onSuccess: (value: T) => Promise<U>;
+    onFailure: (error: E) => Promise<U>;
+  }): Promise<U>;
+  static tap<T, E>(result: Result<T, E>, handlers: {
+    onSuccess?: (value: T) => void;
+    onFailure?: (error: E) => void;
+  }): Result<T, E>;
+  static tapAsync<T, E>(result: Result<T, E>, handlers: {
+    onSuccess?: (value: T) => Promise<void>;
+    onFailure?: (error: E) => Promise<void>;
+  }): Promise<Result<T, E>>;
+  static combine<T, E>(results: Result<T, E>[]): Result<T[], E>;
+  static combineAsync<T, E>(results: Promise<Result<T, E>>[]): Promise<Result<T[], E>>;
+  static combineWithAllErrors<T, E>(results: Result<T, E>[]): Result<T[], E[]>;
+  static combineWithAllErrorsAsync<T, E>(results: Promise<Result<T, E>>[]): Promise<Result<T[], E[]>>;
+  static flatten<T, E>(result: Result<Result<T, E>, E>): Result<T, E>;
+  static fromPromise<T, E>(promise: Promise<T>, errorFn: (error: unknown) => E): Promise<Result<T, E>>;
+  static fromThrowable<Args extends unknown[], T, E>(fn: (...args: Args) => T, errorFn: (error: unknown) => E): (...args: Args) => Result<T, E>;
+  static fromThrowableAsync<Args extends unknown[], T, E>(fn: (...args: Args) => Promise<T>, errorFn: (error: unknown) => E): (...args: Args) => Promise<Result<T, E>>;
+  static fromNullable<T, E>(value: T | null | undefined, error: E): Result<NonNullable<T>, E>;
+  static fromPredicate<T, E>(value: T, predicate: (value: T) => boolean, error: E): Result<T, E>;
+  static toNullable<T, E>(result: Result<T, E>): T | null;
+  static partition<T, E>(results: Result<T, E>[]): [T[], E[]];
+  static filterSuccesses<T, E>(results: Result<T, E>[]): T[];
+  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-EJ_Ol5Fu.d.cts.map

package/dist/index.cjs

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

package/dist/index.d.cts

@@ -0,0 +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";
+export { Failure, Result, ResultKit, Success, TypedError, TypedErrorOf, TypedErrorUnion, isTypedError };

package/dist/index.d.mts

@@ -0,0 +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";
+export { Failure, Result, ResultKit, Success, TypedError, TypedErrorOf, TypedErrorUnion, isTypedError };

package/dist/index.mjs

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

package/dist/nest/index.cjs

@@ -0,0 +1,46 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_result_kit = require("../result-kit-Ck1xAp-J.cjs");
+let _nestjs_common = require("@nestjs/common");
+//#region src/nest/http.ts
+const DEFAULT_UNKNOWN_MESSAGE = "An unknown error occurred";
+const DEFAULT_ERROR_CODE = "INTERNAL_SERVER_ERROR";
+const normalizeErrorCode = (value) => value.trim().replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase() || DEFAULT_ERROR_CODE;
+const toHttpExceptionFromDescriptor = (descriptor) => {
+	const status = descriptor.status ?? _nestjs_common.HttpStatus.INTERNAL_SERVER_ERROR;
+	return new _nestjs_common.HttpException({
+		code: descriptor.code ?? (status === _nestjs_common.HttpStatus.INTERNAL_SERVER_ERROR ? DEFAULT_ERROR_CODE : String(status)),
+		message: descriptor.message ?? DEFAULT_UNKNOWN_MESSAGE,
+		...descriptor.details ? { details: descriptor.details } : {},
+		...descriptor.error ? { error: descriptor.error } : {}
+	}, status);
+};
+const toHttpException = (error, options) => {
+	const mapped = options?.mapError?.(error);
+	if (mapped instanceof _nestjs_common.HttpException) return mapped;
+	if (mapped) return toHttpExceptionFromDescriptor(mapped);
+	if (error instanceof _nestjs_common.HttpException) return error;
+	if (require_result_kit.isTypedError(error)) return new _nestjs_common.InternalServerErrorException({
+		code: normalizeErrorCode(error.type),
+		message: error.message,
+		...error.details ? { details: error.details } : {}
+	});
+	if (error instanceof Error) return new _nestjs_common.InternalServerErrorException({
+		code: DEFAULT_ERROR_CODE,
+		message: error.message || options?.fallbackMessage || DEFAULT_UNKNOWN_MESSAGE
+	});
+	return new _nestjs_common.InternalServerErrorException({
+		code: DEFAULT_ERROR_CODE,
+		message: options?.fallbackMessage || DEFAULT_UNKNOWN_MESSAGE
+	});
+};
+const unwrapOrThrow = (result, options) => {
+	if (require_result_kit.ResultKit.isSuccess(result)) return result.value;
+	throw toHttpException(result.error, options);
+};
+const unwrapPromise = async (promise, options) => unwrapOrThrow(await promise, options);
+//#endregion
+exports.toHttpException = toHttpException;
+exports.unwrapOrThrow = unwrapOrThrow;
+exports.unwrapPromise = unwrapPromise;
+
+//# sourceMappingURL=index.cjs.map

package/dist/nest/index.d.cts

@@ -0,0 +1,21 @@
+import { n as Result } from "../result-DbQ8o1Cs.cjs";
+import { HttpException } from "@nestjs/common";
+
+//#region src/nest/http.d.ts
+interface HttpExceptionDescriptor {
+  readonly status?: number;
+  readonly code?: string | number;
+  readonly message?: string;
+  readonly details?: Record<string, unknown>;
+  readonly error?: string;
+}
+interface NestErrorOptions<E> {
+  readonly mapError?: (error: E) => HttpException | HttpExceptionDescriptor | undefined;
+  readonly fallbackMessage?: string;
+}
+declare const toHttpException: <E>(error: E, options?: NestErrorOptions<E>) => HttpException;
+declare const unwrapOrThrow: <T, E>(result: Result<T, E>, options?: NestErrorOptions<E>) => T;
+declare const unwrapPromise: <T, E>(promise: Promise<Result<T, E>>, options?: NestErrorOptions<E>) => Promise<T>;
+//#endregion
+export { type HttpExceptionDescriptor, type NestErrorOptions, toHttpException, unwrapOrThrow, unwrapPromise };
+//# sourceMappingURL=index.d.cts.map

package/dist/nest/index.d.mts

@@ -0,0 +1,21 @@
+import { n as Result } from "../result-CI_HBDHK.mjs";
+import { HttpException } from "@nestjs/common";
+
+//#region src/nest/http.d.ts
+interface HttpExceptionDescriptor {
+  readonly status?: number;
+  readonly code?: string | number;
+  readonly message?: string;
+  readonly details?: Record<string, unknown>;
+  readonly error?: string;
+}
+interface NestErrorOptions<E> {
+  readonly mapError?: (error: E) => HttpException | HttpExceptionDescriptor | undefined;
+  readonly fallbackMessage?: string;
+}
+declare const toHttpException: <E>(error: E, options?: NestErrorOptions<E>) => HttpException;
+declare const unwrapOrThrow: <T, E>(result: Result<T, E>, options?: NestErrorOptions<E>) => T;
+declare const unwrapPromise: <T, E>(promise: Promise<Result<T, E>>, options?: NestErrorOptions<E>) => Promise<T>;
+//#endregion
+export { type HttpExceptionDescriptor, type NestErrorOptions, toHttpException, unwrapOrThrow, unwrapPromise };
+//# sourceMappingURL=index.d.mts.map

package/dist/nest/index.mjs

@@ -0,0 +1,43 @@
+import { n as isTypedError, t as ResultKit } from "../result-kit-C5ZY61pO.mjs";
+import { HttpException, HttpStatus, InternalServerErrorException } from "@nestjs/common";
+//#region src/nest/http.ts
+const DEFAULT_UNKNOWN_MESSAGE = "An unknown error occurred";
+const DEFAULT_ERROR_CODE = "INTERNAL_SERVER_ERROR";
+const normalizeErrorCode = (value) => value.trim().replace(/[^a-zA-Z0-9]+/g, "_").replace(/^_+|_+$/g, "").toUpperCase() || DEFAULT_ERROR_CODE;
+const toHttpExceptionFromDescriptor = (descriptor) => {
+	const status = descriptor.status ?? HttpStatus.INTERNAL_SERVER_ERROR;
+	return new HttpException({
+		code: descriptor.code ?? (status === HttpStatus.INTERNAL_SERVER_ERROR ? DEFAULT_ERROR_CODE : String(status)),
+		message: descriptor.message ?? DEFAULT_UNKNOWN_MESSAGE,
+		...descriptor.details ? { details: descriptor.details } : {},
+		...descriptor.error ? { error: descriptor.error } : {}
+	}, status);
+};
+const toHttpException = (error, options) => {
+	const mapped = options?.mapError?.(error);
+	if (mapped instanceof HttpException) return mapped;
+	if (mapped) return toHttpExceptionFromDescriptor(mapped);
+	if (error instanceof HttpException) return error;
+	if (isTypedError(error)) return new InternalServerErrorException({
+		code: normalizeErrorCode(error.type),
+		message: error.message,
+		...error.details ? { details: error.details } : {}
+	});
+	if (error instanceof Error) return new InternalServerErrorException({
+		code: DEFAULT_ERROR_CODE,
+		message: error.message || options?.fallbackMessage || DEFAULT_UNKNOWN_MESSAGE
+	});
+	return new InternalServerErrorException({
+		code: DEFAULT_ERROR_CODE,
+		message: options?.fallbackMessage || DEFAULT_UNKNOWN_MESSAGE
+	});
+};
+const unwrapOrThrow = (result, options) => {
+	if (ResultKit.isSuccess(result)) return result.value;
+	throw toHttpException(result.error, options);
+};
+const unwrapPromise = async (promise, options) => unwrapOrThrow(await promise, options);
+//#endregion
+export { toHttpException, unwrapOrThrow, unwrapPromise };
+
+//# sourceMappingURL=index.mjs.map

package/dist/result-CI_HBDHK.d.mts

@@ -0,0 +1,13 @@
+//#region src/core/result.d.ts
+interface Success<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+interface Failure<E> {
+  readonly ok: false;
+  readonly error: E;
+}
+type Result<T, E> = Success<T> | Failure<E>;
+//#endregion
+export { Result as n, Success as r, Failure as t };
+//# sourceMappingURL=result-CI_HBDHK.d.mts.map

package/dist/result-DbQ8o1Cs.d.cts

@@ -0,0 +1,13 @@
+//#region src/core/result.d.ts
+interface Success<T> {
+  readonly ok: true;
+  readonly value: T;
+}
+interface Failure<E> {
+  readonly ok: false;
+  readonly error: E;
+}
+type Result<T, E> = Success<T> | Failure<E>;
+//#endregion
+export { Result as n, Success as r, Failure as t };
+//# sourceMappingURL=result-DbQ8o1Cs.d.cts.map

package/dist/result-kit-C5ZY61pO.mjs

@@ -0,0 +1,172 @@
+//#region src/core/error.ts
+const isTypedError = (error) => {
+	if (!error || typeof error !== "object") return false;
+	const candidate = error;
+	if (typeof candidate.type !== "string" || typeof candidate.message !== "string") return false;
+	if ("details" in candidate && candidate.details !== void 0 && (candidate.details === null || typeof candidate.details !== "object" || Array.isArray(candidate.details))) return false;
+	return true;
+};
+//#endregion
+//#region src/core/result-kit.ts
+var ResultKit = class {
+	static isSuccess(result) {
+		return result.ok === true;
+	}
+	static isFailure(result) {
+		return result.ok === false;
+	}
+	static success(value) {
+		return {
+			ok: true,
+			value
+		};
+	}
+	static failure(error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+	static fail(error) {
+		return this.failure(error);
+	}
+	static isTypedError(error) {
+		return isTypedError(error);
+	}
+	static map(result, fn) {
+		return this.isSuccess(result) ? this.success(fn(result.value)) : result;
+	}
+	static bimap(result, onSuccess, onFailure) {
+		return this.isSuccess(result) ? this.success(onSuccess(result.value)) : this.failure(onFailure(result.error));
+	}
+	static async mapAsync(result, fn) {
+		return this.isSuccess(result) ? this.success(await fn(result.value)) : result;
+	}
+	static mapError(result, fn) {
+		return this.isFailure(result) ? this.failure(fn(result.error)) : result;
+	}
+	static async mapErrorAsync(result, fn) {
+		return this.isFailure(result) ? this.failure(await fn(result.error)) : result;
+	}
+	static andThen(result, fn) {
+		return this.isSuccess(result) ? fn(result.value) : result;
+	}
+	static async andThenAsync(result, fn) {
+		return this.isSuccess(result) ? fn(result.value) : result;
+	}
+	static orElse(result, fn) {
+		return this.isFailure(result) ? fn(result.error) : result;
+	}
+	static async orElseAsync(result, fn) {
+		return this.isFailure(result) ? fn(result.error) : result;
+	}
+	static unwrap(result) {
+		return this.isSuccess(result) ? result.value : void 0;
+	}
+	static unwrapSuccess(result) {
+		return result.value;
+	}
+	static unwrapFailure(result) {
+		return result.error;
+	}
+	static unwrapOr(result, defaultValue) {
+		return this.isSuccess(result) ? result.value : defaultValue;
+	}
+	static unwrapOrElse(result, fn) {
+		return this.isSuccess(result) ? result.value : fn(result.error);
+	}
+	static async unwrapOrElseAsync(result, fn) {
+		return this.isSuccess(result) ? result.value : fn(result.error);
+	}
+	static match(result, handlers) {
+		return this.isSuccess(result) ? handlers.onSuccess(result.value) : handlers.onFailure(result.error);
+	}
+	static async matchAsync(result, handlers) {
+		return this.isSuccess(result) ? handlers.onSuccess(result.value) : handlers.onFailure(result.error);
+	}
+	static tap(result, handlers) {
+		if (this.isSuccess(result)) handlers.onSuccess?.(result.value);
+		else handlers.onFailure?.(result.error);
+		return result;
+	}
+	static async tapAsync(result, handlers) {
+		if (this.isSuccess(result)) await handlers.onSuccess?.(result.value);
+		else await handlers.onFailure?.(result.error);
+		return result;
+	}
+	static combine(results) {
+		const values = [];
+		for (const result of results) {
+			if (this.isFailure(result)) return result;
+			values.push(result.value);
+		}
+		return this.success(values);
+	}
+	static async combineAsync(results) {
+		return this.combine(await Promise.all(results));
+	}
+	static combineWithAllErrors(results) {
+		const values = [];
+		const errors = [];
+		for (const result of results) if (this.isSuccess(result)) values.push(result.value);
+		else errors.push(result.error);
+		return errors.length > 0 ? this.failure(errors) : this.success(values);
+	}
+	static async combineWithAllErrorsAsync(results) {
+		return this.combineWithAllErrors(await Promise.all(results));
+	}
+	static flatten(result) {
+		return this.isSuccess(result) ? result.value : result;
+	}
+	static async fromPromise(promise, errorFn) {
+		try {
+			return this.success(await promise);
+		} catch (error) {
+			return this.failure(errorFn(error));
+		}
+	}
+	static fromThrowable(fn, errorFn) {
+		return (...args) => {
+			try {
+				return this.success(fn(...args));
+			} catch (error) {
+				return this.failure(errorFn(error));
+			}
+		};
+	}
+	static fromThrowableAsync(fn, errorFn) {
+		return async (...args) => {
+			try {
+				return this.success(await fn(...args));
+			} catch (error) {
+				return this.failure(errorFn(error));
+			}
+		};
+	}
+	static fromNullable(value, error) {
+		return value == null ? this.failure(error) : this.success(value);
+	}
+	static fromPredicate(value, predicate, error) {
+		return predicate(value) ? this.success(value) : this.failure(error);
+	}
+	static toNullable(result) {
+		return this.isSuccess(result) ? result.value : null;
+	}
+	static partition(results) {
+		const values = [];
+		const errors = [];
+		for (const result of results) if (this.isSuccess(result)) values.push(result.value);
+		else errors.push(result.error);
+		return [values, errors];
+	}
+	static filterSuccesses(results) {
+		return results.filter((result) => this.isSuccess(result)).map((result) => result.value);
+	}
+	static filterFailures(results) {
+		return results.filter((result) => this.isFailure(result)).map((result) => result.error);
+	}
+};
+//#endregion
+export { isTypedError as n, ResultKit as t };
+
+//# sourceMappingURL=result-kit-C5ZY61pO.mjs.map

package/dist/result-kit-Ck1xAp-J.cjs

@@ -0,0 +1,183 @@
+//#region src/core/error.ts
+const isTypedError = (error) => {
+	if (!error || typeof error !== "object") return false;
+	const candidate = error;
+	if (typeof candidate.type !== "string" || typeof candidate.message !== "string") return false;
+	if ("details" in candidate && candidate.details !== void 0 && (candidate.details === null || typeof candidate.details !== "object" || Array.isArray(candidate.details))) return false;
+	return true;
+};
+//#endregion
+//#region src/core/result-kit.ts
+var ResultKit = class {
+	static isSuccess(result) {
+		return result.ok === true;
+	}
+	static isFailure(result) {
+		return result.ok === false;
+	}
+	static success(value) {
+		return {
+			ok: true,
+			value
+		};
+	}
+	static failure(error) {
+		return {
+			ok: false,
+			error
+		};
+	}
+	static fail(error) {
+		return this.failure(error);
+	}
+	static isTypedError(error) {
+		return isTypedError(error);
+	}
+	static map(result, fn) {
+		return this.isSuccess(result) ? this.success(fn(result.value)) : result;
+	}
+	static bimap(result, onSuccess, onFailure) {
+		return this.isSuccess(result) ? this.success(onSuccess(result.value)) : this.failure(onFailure(result.error));
+	}
+	static async mapAsync(result, fn) {
+		return this.isSuccess(result) ? this.success(await fn(result.value)) : result;
+	}
+	static mapError(result, fn) {
+		return this.isFailure(result) ? this.failure(fn(result.error)) : result;
+	}
+	static async mapErrorAsync(result, fn) {
+		return this.isFailure(result) ? this.failure(await fn(result.error)) : result;
+	}
+	static andThen(result, fn) {
+		return this.isSuccess(result) ? fn(result.value) : result;
+	}
+	static async andThenAsync(result, fn) {
+		return this.isSuccess(result) ? fn(result.value) : result;
+	}
+	static orElse(result, fn) {
+		return this.isFailure(result) ? fn(result.error) : result;
+	}
+	static async orElseAsync(result, fn) {
+		return this.isFailure(result) ? fn(result.error) : result;
+	}
+	static unwrap(result) {
+		return this.isSuccess(result) ? result.value : void 0;
+	}
+	static unwrapSuccess(result) {
+		return result.value;
+	}
+	static unwrapFailure(result) {
+		return result.error;
+	}
+	static unwrapOr(result, defaultValue) {
+		return this.isSuccess(result) ? result.value : defaultValue;
+	}
+	static unwrapOrElse(result, fn) {
+		return this.isSuccess(result) ? result.value : fn(result.error);
+	}
+	static async unwrapOrElseAsync(result, fn) {
+		return this.isSuccess(result) ? result.value : fn(result.error);
+	}
+	static match(result, handlers) {
+		return this.isSuccess(result) ? handlers.onSuccess(result.value) : handlers.onFailure(result.error);
+	}
+	static async matchAsync(result, handlers) {
+		return this.isSuccess(result) ? handlers.onSuccess(result.value) : handlers.onFailure(result.error);
+	}
+	static tap(result, handlers) {
+		if (this.isSuccess(result)) handlers.onSuccess?.(result.value);
+		else handlers.onFailure?.(result.error);
+		return result;
+	}
+	static async tapAsync(result, handlers) {
+		if (this.isSuccess(result)) await handlers.onSuccess?.(result.value);
+		else await handlers.onFailure?.(result.error);
+		return result;
+	}
+	static combine(results) {
+		const values = [];
+		for (const result of results) {
+			if (this.isFailure(result)) return result;
+			values.push(result.value);
+		}
+		return this.success(values);
+	}
+	static async combineAsync(results) {
+		return this.combine(await Promise.all(results));
+	}
+	static combineWithAllErrors(results) {
+		const values = [];
+		const errors = [];
+		for (const result of results) if (this.isSuccess(result)) values.push(result.value);
+		else errors.push(result.error);
+		return errors.length > 0 ? this.failure(errors) : this.success(values);
+	}
+	static async combineWithAllErrorsAsync(results) {
+		return this.combineWithAllErrors(await Promise.all(results));
+	}
+	static flatten(result) {
+		return this.isSuccess(result) ? result.value : result;
+	}
+	static async fromPromise(promise, errorFn) {
+		try {
+			return this.success(await promise);
+		} catch (error) {
+			return this.failure(errorFn(error));
+		}
+	}
+	static fromThrowable(fn, errorFn) {
+		return (...args) => {
+			try {
+				return this.success(fn(...args));
+			} catch (error) {
+				return this.failure(errorFn(error));
+			}
+		};
+	}
+	static fromThrowableAsync(fn, errorFn) {
+		return async (...args) => {
+			try {
+				return this.success(await fn(...args));
+			} catch (error) {
+				return this.failure(errorFn(error));
+			}
+		};
+	}
+	static fromNullable(value, error) {
+		return value == null ? this.failure(error) : this.success(value);
+	}
+	static fromPredicate(value, predicate, error) {
+		return predicate(value) ? this.success(value) : this.failure(error);
+	}
+	static toNullable(result) {
+		return this.isSuccess(result) ? result.value : null;
+	}
+	static partition(results) {
+		const values = [];
+		const errors = [];
+		for (const result of results) if (this.isSuccess(result)) values.push(result.value);
+		else errors.push(result.error);
+		return [values, errors];
+	}
+	static filterSuccesses(results) {
+		return results.filter((result) => this.isSuccess(result)).map((result) => result.value);
+	}
+	static filterFailures(results) {
+		return results.filter((result) => this.isFailure(result)).map((result) => result.error);
+	}
+};
+//#endregion
+Object.defineProperty(exports, "ResultKit", {
+	enumerable: true,
+	get: function() {
+		return ResultKit;
+	}
+});
+Object.defineProperty(exports, "isTypedError", {
+	enumerable: true,
+	get: function() {
+		return isTypedError;
+	}
+});
+
+//# sourceMappingURL=result-kit-Ck1xAp-J.cjs.map

package/package.json

@@ -0,0 +1,69 @@
+{
+  "name": "@zireal/result-kit",
+  "version": "1.0.0",
+  "description": "Type-safe result and structured error utilities for TypeScript, with optional NestJS adapters.",
+  "license": "MIT",
+  "author": "Ali Farooq <alifarooq122@gmail.com>",
+  "type": "module",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alifarooq-zk/result-kit.git"
+  },
+  "keywords": [
+    "result",
+    "error-handling",
+    "result-type",
+    "result monad"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "clean": "rm -rf dist coverage",
+    "changeset": "changeset",
+    "changeset:version": "changeset version",
+    "changeset:publish": "changeset publish",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "test:cov": "vitest run --coverage",
+    "check": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^11.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@nestjs/common": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@arethetypeswrong/core": "^0.18.2",
+    "@changesets/cli": "^2.30.0",
+    "@nestjs/common": "^11.1.17",
+    "@types/node": "^22.19.15",
+    "publint": "^0.3.18",
+    "tsdown": "^0.21.4",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    },
+    "./core": {
+      "import": "./dist/core/index.mjs",
+      "require": "./dist/core/index.cjs"
+    },
+    "./nest": {
+      "import": "./dist/nest/index.mjs",
+      "require": "./dist/nest/index.cjs"
+    },
+    "./package.json": "./package.json"
+  }
+}