@mkvlrn/result 2.0.0 → 4.0.0

package/README.md

@@ -1,43 +1,94 @@
-# Result
+# Result Pattern
 
-A lightweight, zero-dependency TypeScript utility for type-safe error handling using the Result pattern.
+Type-safe Result pattern for TypeScript representing success or error. Anything to avoid try/catch hell.
 
 ## Installation
 
 ```bash
-# Using yarn
-yarn add @mkvlrn/result
+npm add @mkvlrn/result
 ```
 
 ## Usage
 
-```ts
-import { Result } from "@mkvlrn/result";
+```typescript
+import { Result, AsyncResult, R } from "@mkvlrn/result";
 
-// Success case
-const success = Result.success(42);
-if (success.ok) {
-  console.log(success.value); // 42
+// Success
+const success = R.ok(42);
+
+// Error
+const failure = R.error(new Error("Something went wrong"));
+
+// Check result
+const result = R.ok(42);
+if (result.error) {
+  console.log("Error:", result.error.message);
+} else {
+  console.log("Value:", result.value);
+}
+```
+
+## Examples
+
+### Basic Function
+
+```typescript
+function divide(a: number, b: number): Result<number, Error> {
+  if (b === 0) {
+    return R.error(new Error("Division by zero"));
+  }
+  return R.ok(a / b);
 }
 
-// Error case
-const error = Result.error(new Error("Something went wrong"));
-if (!error.ok) {
-  console.log(error.error.message); // "Something went wrong"
+const result = divide(10, 2);
+if (!result.error) {
+  console.log(result.value); // 5
 }
+```
 
-// Custom error type
-type ValidationError = { field: string; message: string };
-const validationError = Result.error<ValidationError>({
-  field: "email",
-  message: "Invalid email format",
-});
+### Async Operations
+
+```typescript
+async function fetchUser(id: number): AsyncResult<User, Error> {
+  try {
+    const response = await fetch(`/api/users/${id}`);
+    if (!response.ok) {
+      return R.error(new Error(`HTTP ${response.status}`));
+    }
+    const user = await response.json();
+    return R.ok(user);
+  } catch (error) {
+    return R.error(error instanceof Error ? error : new Error("Unknown error"));
+  }
+}
+```
+
+### Custom Error Types
+
+```typescript
+class ValidationError extends Error {
+  readonly customField: number;
+
+  constructor(customField: number, message: string) {
+    super(message);
+    this.name = "ValidationError";
+    this.customField = customField;
+  }
+}
+
+function validateEmail(email: string): Result<string, ValidationError> {
+  if (!email.includes("@")) {
+    return Result.error(new ValidationError(400, "custom"));
+  }
+  return Result.ok(email);
+}
+
+const result = validateEmail("invalid-email");
+if (result.error) {
+  console.log(`${result.error.customField}: ${result.error.message}`);
+}
 ```
 
-## Features
+## License
 
-- Type-safe error handling
-- Zero dependencies
-- Simple API
-- Full TypeScript support
-- Tiny bundle size
+MIT

package/build/index.d.ts

@@ -1,18 +1,35 @@
 /**
  * Result type to represent the outcome of an operation.
- * It can either be a success with a value or an error with an error message.
- * This is a generic type that can be used with any type of value and error.
+ * It can either be a success with a value or an error.
+ * This is a generic type that can be used with any type of value and error (should extend Error).
  *
  * It is also an alias object containing the ok and error functions to
  * make it easier to create Result objects.
  */
-export type Result<T, E = Error> = {
+export type Result<T, E extends Error> = {
     readonly error: undefined;
     readonly value: T;
 } | {
     readonly error: E;
 };
-export declare const Result: {
+/**
+ * Async version of Result type that wraps a Result in a Promise.
+ */
+export type AsyncResult<T, E extends Error> = Promise<Result<T, E>>;
+/**
+ * Result utility functions for creating Result objects.
+ */
+export declare const R: {
+    /**
+     * Creates a successful Result with the given value.
+     * @param value The success value
+     * @returns A Result object representing success
+     */
     ok<T>(value: T): Result<T, never>;
-    error<E = Error>(error: E): Result<never, E>;
+    /**
+     * Creates an error Result with the given error.
+     * @param error The error value
+     * @returns A Result object representing error
+     */
+    error<E extends Error>(error: E): Result<never, E>;
 };

package/build/index.js

@@ -1,14 +1,7 @@
-export const Result = {
-    /**
-     * Creates a successful Result with the given value.
-     * @param value The success value
-     * @returns A Result object representing success
-     */
+/**
+ * Result utility functions for creating Result objects.
+ */
+export const R = {
     ok: (value) => ({ error: undefined, value }),
-    /**
-     * Creates an error Result with the given error.
-     * @param error The error value
-     * @returns A Result object representing error
-     */
     error: (error) => ({ error }),
 };

package/build/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/build/index.test.js

@@ -0,0 +1,53 @@
+// biome-ignore lint/correctness/noNodejsModules: need the timer
+import { setTimeout } from "node:timers/promises";
+import { assert, describe, it } from "vitest";
+import { R } from "./index.js";
+class CustomError extends Error {
+    customField;
+    constructor(customField, message) {
+        super(message);
+        this.name = "CustomField";
+        this.customField = customField;
+    }
+}
+function division(a, b) {
+    if (b === 0) {
+        return R.error(new Error("cannot divide by zero"));
+    }
+    return R.ok(a / b);
+}
+async function longRunning(shouldFail) {
+    await setTimeout(1);
+    return shouldFail ? R.error(new CustomError(42, "wrong")) : R.ok(3);
+}
+describe("creates a valid result", () => {
+    describe("default Error type", () => {
+        it("ok result", () => {
+            const result = division(4, 2);
+            assert.isUndefined(result.error);
+            assert.isDefined(result.value);
+            assert.strictEqual(result.value, 2);
+        });
+        it("error result", () => {
+            const result = division(4, 0);
+            assert.isDefined(result.error);
+            assert.instanceOf(result.error, Error);
+            assert.strictEqual(result.error.message, "cannot divide by zero");
+        });
+    });
+    describe("custom error", () => {
+        it("ok result", async () => {
+            const result = await longRunning(false);
+            assert.isUndefined(result.error);
+            assert.isDefined(result.value);
+            assert.strictEqual(result.value, 3);
+        });
+        it("error result", async () => {
+            const result = await longRunning(true);
+            assert.isDefined(result.error);
+            assert.instanceOf(result.error, CustomError);
+            assert.strictEqual(result.error.message, "wrong");
+            assert.strictEqual(result.error.customField, 42);
+        });
+    });
+});

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@mkvlrn/result",
   "description": "Result type for TypeScript",
-  "version": "2.0.0",
+  "version": "4.0.0",
   "license": "MIT",
   "type": "module",
   "publishConfig": {
@@ -16,10 +16,13 @@
     "build"
   ],
   "scripts": {
+    "test": "vitest",
     "build": "rm -rf build && tsc"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.0.6",
-    "typescript": "^5.8.3"
+    "@biomejs/biome": "^2.1.2",
+    "@types/node": "^24.1.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
   }
 }