@firtoz/maybe-error 1.5.1 → 1.6.0

package/README.md

@@ -4,7 +4,12 @@
 [![npm downloads](https://img.shields.io/npm/dm/%40firtoz%2Fmaybe-error.svg)](https://www.npmjs.com/package/@firtoz/maybe-error)
 [![license](https://img.shields.io/npm/l/%40firtoz%2Fmaybe-error.svg)](https://github.com/firtoz/fullstack-toolkit/blob/main/LICENSE)
 
-Type-safe result handling with the MaybeError pattern for TypeScript. Perfect for elegant error handling without exceptions.
+[![TypeScript](https://img.shields.io/badge/TypeScript-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![zero dependencies](https://img.shields.io/badge/deps-zero-22c55e)](https://github.com/firtoz/fullstack-toolkit/tree/main/packages/maybe-error)
+
+**`MaybeError` results without exceptions** — discriminated unions, tree-shakeable, zero runtime dependencies.
+
+> **⚠️ Early WIP Notice:** This package is in very early development and is **not production-ready**. It is TypeScript-only and may have breaking changes. While I (the maintainer) have limited time, I'm open to PRs for features, bug fixes, or additional support (like JS builds). Please feel free to try it out and contribute! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for details.
 
 ## Features
 

package/dist/MaybeError.d.ts

@@ -0,0 +1,135 @@
+/**
+ * @fileoverview Type-safe error handling utilities using discriminated unions
+ *
+ * This module provides a Result-like pattern for handling operations that may fail,
+ * inspired by Rust's Result type and functional programming error handling patterns.
+ *
+ * @example
+ * ```typescript
+ * // Basic usage
+ * const result = success(42);
+ * const error = fail("Something went wrong");
+ *
+ * // Type-safe error handling
+ * function divide(a: number, b: number): MaybeError<number> {
+ *   if (b === 0) return fail("Division by zero");
+ *   return success(a / b);
+ * }
+ *
+ * const result = divide(10, 2);
+ * if (result.success) {
+ *   console.log(result.result); // 5
+ * } else {
+ *   console.error(result.error); // "Division by zero"
+ * }
+ * ```
+ */
+/**
+ * Represents a failed operation with an error value.
+ *
+ * @template TError - The type of the error value (defaults to string)
+ * @example
+ * ```typescript
+ * const error: DefiniteError<string> = { success: false, error: "Not found" };
+ * const customError: DefiniteError<{code: number, message: string}> = {
+ *   success: false,
+ *   error: { code: 404, message: "Resource not found" }
+ * };
+ * ```
+ */
+type DefiniteError<TError = string> = {
+    success: false;
+    error: TError;
+};
+/**
+ * Represents a successful operation with an optional result value.
+ *
+ * Uses conditional types to make the result field optional when T is undefined,
+ * but required when T has a concrete type.
+ *
+ * @template T - The type of the success value (defaults to undefined)
+ * @example
+ * ```typescript
+ * const voidSuccess: DefiniteSuccess = { success: true };
+ * const valueSuccess: DefiniteSuccess<number> = { success: true, result: 42 };
+ * ```
+ */
+type DefiniteSuccess<T = undefined> = {
+    success: true;
+} & (T extends undefined ? {
+    result?: T;
+} : {
+    result: T;
+});
+/**
+ * A discriminated union representing either a successful result or an error.
+ *
+ * This is the main type for operations that may fail. The `success` field
+ * acts as a discriminant, allowing TypeScript to narrow the type in conditionals.
+ *
+ * @template T - The type of the success value (defaults to undefined)
+ * @template TError - The type of the error value (defaults to string)
+ * @example
+ * ```typescript
+ * function fetchUser(id: string): MaybeError<User, ApiError> {
+ *   // Implementation that returns either success(user) or fail(apiError)
+ * }
+ *
+ * const result = fetchUser("123");
+ * if (result.success) {
+ *   // TypeScript knows result.result is User
+ *   console.log(result.result.name);
+ * } else {
+ *   // TypeScript knows result.error is ApiError
+ *   console.error(result.error.message);
+ * }
+ * ```
+ */
+type MaybeError<T = undefined, TError = string> = DefiniteSuccess<T> | DefiniteError<TError>;
+/**
+ * Utility type to extract the success value type from a MaybeError type.
+ *
+ * Useful for type manipulation when you need to work with the success type
+ * without the error handling wrapper.
+ *
+ * @template T - A MaybeError type
+ * @example
+ * ```typescript
+ * type UserResult = MaybeError<User, string>;
+ * type UserType = AssumeSuccess<UserResult>; // User
+ * ```
+ */
+type AssumeSuccess<T extends MaybeError<unknown>> = Exclude<T, undefined> extends MaybeError<infer U> ? U : never;
+/**
+ * Creates a successful result with an optional value.
+ *
+ * Uses function overloading to provide different signatures based on whether
+ * a value is provided or not.
+ *
+ * @template T - The type of the success value
+ * @param params - The success value (optional for void operations)
+ * @returns A DefiniteSuccess instance
+ * @example
+ * ```typescript
+ * const voidResult = success(); // DefiniteSuccess<undefined>
+ * const valueResult = success(42); // DefiniteSuccess<number>
+ * const stringResult = success("hello"); // DefiniteSuccess<string>
+ * ```
+ */
+declare const success: <T = undefined>(...params: T extends undefined ? [] : [T]) => DefiniteSuccess<T>;
+/**
+ * Creates a failed result with an error value.
+ *
+ * @template TError - The type of the error value
+ * @param error - The error value
+ * @returns A DefiniteError instance
+ * @example
+ * ```typescript
+ * const stringError = fail("Something went wrong");
+ * const objectError = fail({ code: 500, message: "Internal server error" });
+ * const customError = fail(new Error("Custom error"));
+ * ```
+ */
+declare const fail: <TError = string>(error: TError) => DefiniteError<TError>;
+
+export { type AssumeSuccess, type DefiniteError, type DefiniteSuccess, type MaybeError, fail, success };

package/dist/MaybeError.js

@@ -0,0 +1,3 @@
+export { fail, success } from './chunk-FAVWW3FP.js';
+//# sourceMappingURL=MaybeError.js.map
+//# sourceMappingURL=MaybeError.js.map

package/dist/MaybeError.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"MaybeError.js"}

package/dist/chunk-FAVWW3FP.js

@@ -0,0 +1,20 @@
+// src/MaybeError.ts
+var success = (...params) => {
+  if (params.length === 0) {
+    return { success: true };
+  }
+  return {
+    success: true,
+    result: params[0]
+  };
+};
+var fail = (error) => {
+  return {
+    success: false,
+    error
+  };
+};
+
+export { fail, success };
+//# sourceMappingURL=chunk-FAVWW3FP.js.map
+//# sourceMappingURL=chunk-FAVWW3FP.js.map

package/dist/chunk-FAVWW3FP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/MaybeError.ts"],"names":[],"mappings":";AAgIO,IAAM,OAAA,GAAU,IACnB,MAAA,KACqB;AACxB,EAAA,IAAI,MAAA,CAAO,WAAW,CAAA,EAAG;AACxB,IAAA,OAAO,EAAE,SAAS,IAAA,EAAK;AAAA,EACxB;AAEA,EAAA,OAAO;AAAA,IACN,OAAA,EAAS,IAAA;AAAA,IACT,MAAA,EAAQ,OAAO,CAAC;AAAA,GACjB;AACD;AAeO,IAAM,IAAA,GAAO,CAAkB,KAAA,KAAyC;AAC9E,EAAA,OAAO;AAAA,IACN,OAAA,EAAS,KAAA;AAAA,IACT;AAAA,GACD;AACD","file":"chunk-FAVWW3FP.js","sourcesContent":["/**\n * @fileoverview Type-safe error handling utilities using discriminated unions\n *\n * This module provides a Result-like pattern for handling operations that may fail,\n * inspired by Rust's Result type and functional programming error handling patterns.\n *\n * @example\n * ```typescript\n * // Basic usage\n * const result = success(42);\n * const error = fail(\"Something went wrong\");\n *\n * // Type-safe error handling\n * function divide(a: number, b: number): MaybeError<number> {\n *   if (b === 0) return fail(\"Division by zero\");\n *   return success(a / b);\n * }\n *\n * const result = divide(10, 2);\n * if (result.success) {\n *   console.log(result.result); // 5\n * } else {\n *   console.error(result.error); // \"Division by zero\"\n * }\n * ```\n */\n\n/**\n * Represents a failed operation with an error value.\n *\n * @template TError - The type of the error value (defaults to string)\n * @example\n * ```typescript\n * const error: DefiniteError<string> = { success: false, error: \"Not found\" };\n * const customError: DefiniteError<{code: number, message: string}> = {\n *   success: false,\n *   error: { code: 404, message: \"Resource not found\" }\n * };\n * ```\n */\nexport type DefiniteError<TError = string> = {\n\tsuccess: false;\n\terror: TError;\n};\n\n/**\n * Represents a successful operation with an optional result value.\n *\n * Uses conditional types to make the result field optional when T is undefined,\n * but required when T has a concrete type.\n *\n * @template T - The type of the success value (defaults to undefined)\n * @example\n * ```typescript\n * const voidSuccess: DefiniteSuccess = { success: true };\n * const valueSuccess: DefiniteSuccess<number> = { success: true, result: 42 };\n * ```\n */\nexport type DefiniteSuccess<T = undefined> = {\n\tsuccess: true;\n} & (T extends undefined\n\t? {\n\t\t\tresult?: T;\n\t\t}\n\t: {\n\t\t\tresult: T;\n\t\t});\n\n/**\n * A discriminated union representing either a successful result or an error.\n *\n * This is the main type for operations that may fail. The `success` field\n * acts as a discriminant, allowing TypeScript to narrow the type in conditionals.\n *\n * @template T - The type of the success value (defaults to undefined)\n * @template TError - The type of the error value (defaults to string)\n * @example\n * ```typescript\n * function fetchUser(id: string): MaybeError<User, ApiError> {\n *   // Implementation that returns either success(user) or fail(apiError)\n * }\n *\n * const result = fetchUser(\"123\");\n * if (result.success) {\n *   // TypeScript knows result.result is User\n *   console.log(result.result.name);\n * } else {\n *   // TypeScript knows result.error is ApiError\n *   console.error(result.error.message);\n * }\n * ```\n */\nexport type MaybeError<T = undefined, TError = string> =\n\t| DefiniteSuccess<T>\n\t| DefiniteError<TError>;\n\n/**\n * Utility type to extract the success value type from a MaybeError type.\n *\n * Useful for type manipulation when you need to work with the success type\n * without the error handling wrapper.\n *\n * @template T - A MaybeError type\n * @example\n * ```typescript\n * type UserResult = MaybeError<User, string>;\n * type UserType = AssumeSuccess<UserResult>; // User\n * ```\n */\nexport type AssumeSuccess<T extends MaybeError<unknown>> =\n\tExclude<T, undefined> extends MaybeError<infer U> ? U : never;\n\n/**\n * Creates a successful result with an optional value.\n *\n * Uses function overloading to provide different signatures based on whether\n * a value is provided or not.\n *\n * @template T - The type of the success value\n * @param params - The success value (optional for void operations)\n * @returns A DefiniteSuccess instance\n * @example\n * ```typescript\n * const voidResult = success(); // DefiniteSuccess<undefined>\n * const valueResult = success(42); // DefiniteSuccess<number>\n * const stringResult = success(\"hello\"); // DefiniteSuccess<string>\n * ```\n */\nexport const success = <T = undefined>(\n\t...params: T extends undefined ? [] : [T]\n): DefiniteSuccess<T> => {\n\tif (params.length === 0) {\n\t\treturn { success: true } as unknown as DefiniteSuccess<T>;\n\t}\n\n\treturn {\n\t\tsuccess: true,\n\t\tresult: params[0],\n\t} as unknown as DefiniteSuccess<T>;\n};\n\n/**\n * Creates a failed result with an error value.\n *\n * @template TError - The type of the error value\n * @param error - The error value\n * @returns A DefiniteError instance\n * @example\n * ```typescript\n * const stringError = fail(\"Something went wrong\");\n * const objectError = fail({ code: 500, message: \"Internal server error\" });\n * const customError = fail(new Error(\"Custom error\"));\n * ```\n */\nexport const fail = <TError = string>(error: TError): DefiniteError<TError> => {\n\treturn {\n\t\tsuccess: false,\n\t\terror,\n\t};\n};\n"]}

package/dist/chunk-Z5JSMWNM.js

@@ -0,0 +1,8 @@
+// src/exhaustiveGuard.ts
+function exhaustiveGuard(value) {
+  throw new Error(`Exhaustive guard triggered with value: ${value}`);
+}
+
+export { exhaustiveGuard };
+//# sourceMappingURL=chunk-Z5JSMWNM.js.map
+//# sourceMappingURL=chunk-Z5JSMWNM.js.map

package/dist/chunk-Z5JSMWNM.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/exhaustiveGuard.ts"],"names":[],"mappings":";AAAO,SAAS,gBAAgB,KAAA,EAAqB;AACpD,EAAA,MAAM,IAAI,KAAA,CAAM,CAAA,uCAAA,EAA0C,KAAK,CAAA,CAAE,CAAA;AAClE","file":"chunk-Z5JSMWNM.js","sourcesContent":["export function exhaustiveGuard(value: never): never {\n\tthrow new Error(`Exhaustive guard triggered with value: ${value}`);\n}\n"]}

package/dist/exhaustiveGuard.d.ts

@@ -0,0 +1,3 @@
+declare function exhaustiveGuard(value: never): never;
+
+export { exhaustiveGuard };

package/dist/exhaustiveGuard.js

@@ -0,0 +1,3 @@
+export { exhaustiveGuard } from './chunk-Z5JSMWNM.js';
+//# sourceMappingURL=exhaustiveGuard.js.map
+//# sourceMappingURL=exhaustiveGuard.js.map

package/dist/exhaustiveGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"exhaustiveGuard.js"}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { AssumeSuccess, DefiniteError, DefiniteSuccess, MaybeError, fail, success } from './MaybeError.js';
+export { exhaustiveGuard } from './exhaustiveGuard.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { fail, success } from './chunk-FAVWW3FP.js';
+export { exhaustiveGuard } from './chunk-Z5JSMWNM.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/package.json

@@ -1,24 +1,29 @@
 {
 	"name": "@firtoz/maybe-error",
-	"version": "1.5.1",
+	"version": "1.6.0",
 	"description": "Type-safe result handling with MaybeError pattern",
-	"main": "./src/index.ts",
-	"module": "./src/index.ts",
-	"types": "./src/index.ts",
+	"type": "module",
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
 	"exports": {
 		".": {
-			"types": "./src/index.ts",
-			"import": "./src/index.ts",
-			"require": "./src/index.ts"
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
 		}
 	},
 	"files": [
+		"dist/**/*.js",
+		"dist/**/*.js.map",
+		"dist/**/*.d.ts",
 		"src/**/*.ts",
 		"!src/**/*.test.ts",
 		"README.md"
 	],
 	"scripts": {
-		"typecheck": "tsc --noEmit -p ./tsconfig.json",
+		"build": "tsup",
+		"prepack": "bun run build",
+		"typecheck": "tsgo --noEmit -p ./tsconfig.json",
 		"lint": "biome check --write src",
 		"lint:ci": "biome ci src",
 		"format": "biome format src --write",
@@ -50,6 +55,6 @@
 		"access": "public"
 	},
 	"devDependencies": {
-		"bun-types": "^1.3.0"
+		"bun-types": "^1.3.11"
 	}
 }

package/src/MaybeError.ts

@@ -107,12 +107,8 @@ export type MaybeError<T = undefined, TError = string> =
  * type UserType = AssumeSuccess<UserResult>; // User
  * ```
  */
-export type AssumeSuccess<T extends MaybeError<unknown>> = Exclude<
-	T,
-	undefined
-> extends MaybeError<infer U>
-	? U
-	: never;
+export type AssumeSuccess<T extends MaybeError<unknown>> =
+	Exclude<T, undefined> extends MaybeError<infer U> ? U : never;
 
 /**
  * Creates a successful result with an optional value.

package/src/exhaustiveGuard.ts

@@ -0,0 +1,3 @@
+export function exhaustiveGuard(value: never): never {
+	throw new Error(`Exhaustive guard triggered with value: ${value}`);
+}

package/src/index.ts

@@ -1 +1,9 @@
-export * from "./MaybeError";
+export {
+	type MaybeError,
+	success,
+	fail,
+	type AssumeSuccess,
+	type DefiniteError,
+	type DefiniteSuccess,
+} from "./MaybeError";
+export { exhaustiveGuard } from "./exhaustiveGuard";