Merge pull request #2 from maxmorozoff/dev

feat: enhance error handling and improve TypeScript support

Author: maxmorozoff

.changeset/warm-eggs-show.md

@@ -0,0 +1,20 @@
+---
+"@maxmorozoff/try-catch-tuple": minor
+---
+
+#### Added
+
+- Introduced `.errors<E>()` method to allow specifying expected error types.
+- Ensured non-Error thrown values are wrapped properly in an `Error` instance with `cause`.
+- Added more tests to cover edge cases and ensure robustness.
+
+#### Improved
+
+- Refactored `tryCatch`, `tryCatch.sync`, and `tryCatch.async` to support generic error types.
+- Introduced `TryCatchFunc` and `TryCatchResult` for improved type safety.
+- Updated `typescript` version range in `peerDependencies` to `^5.0.0`, supporting all 5.x versions.
+- Added `peerDependenciesMeta` to mark `typescript` as an optional dependency. This allows consumers of the package to choose not to install `typescript` while still ensuring compatibility with TypeScript 5.x.
+
+#### Fixed
+
+- `handleError` now correctly preserves the original thrown value under `cause`.

README.md

@@ -10,6 +10,8 @@ See [Theo's gist for more details](https://gist.github.com/t3dotgg/a486c4ae66d32
 - Returns a structured tuple `[data, error]`.
 - Provides named operations for better debugging.
 - Includes `tryCatch.sync` and `tryCatch.async` for explicit handling.
+- Allows custom error types via `.errors<E>()`
+- Ensures all thrown values become `Error` instances
 
 ## Installation
 
@@ -24,60 +26,150 @@ npm install @maxmorozoff/try-catch-tuple
 ```ts
 import { tryCatch } from "@maxmorozoff/try-catch-tuple";
 
-const [result, error] = tryCatch.sync(() => JSON.parse("73"));
-console.log(result); // 73
-console.log(error); // null
+function main() {
+  const [result, error] = tryCatch(() => JSON.parse("73") as number);
+  //     ^? const result: number | null
+
+  if (!error) return result; // ✅ result: number
+  console.log(error); // ❌ Error
+  //          ^? const error: Error
+}
 ```
 
-### Handling Errors
+### Named Operations for Debugging
 
 ```ts
 const [result, error] = tryCatch((): void => {
-  throw new Error("Something went wrong");
-});
+  throw new Error("Failed to fetch data");
+}, "Fetch Data");
+
+console.log(error?.message); // "Operation \"Fetch Data\" failed: Failed to fetch data"
+```
+
+### Using `tryCatch.sync`
 
-console.log(result); // null
-console.log(error?.message); // "Something went wrong"
+```ts
+function main() {
+  const [result, error] = tryCatch.sync(() => JSON.parse("73") as number);
+  //     ^? const result: number | null
+  if (!error) return result;
+  //                 ^? const result: number
+  error;
+  // ^? const error: Error
+  result;
+  // ^? const result: null
+}
 ```
 
-### Asynchronous Usage with Errors
+### Using `tryCatch.async`
 
 ```ts
-const [result, error] = await tryCatch(async () => {
-  throw new Error("Network request failed");
+async function main() {
+  const [result, error] = await tryCatch.async(
+    //   ^? const result: number | null
+    async () => JSON.parse("73") as number
+  );
+  if (!error) return result;
+  //                 ^? const result: number
+  error;
+  // ^? const error: Error
+  result;
+  // ^? const result: null
+}
+```
+
+### Handling Errors
+
+#### Ensuring All Thrown Values Are Error Instances
+
+If a thrown value is **not an instance of** `Error`, it gets wrapped:
+
+```ts
+const [result, error] = tryCatch((): void => {
+  throw "Something went wrong";
 });
 
-console.log(result); // null
-console.log(error?.message); // "Network request failed"
+console.log(error.message); // "Something went wrong"
+//          ^? const error: Error
+
+const [data, nullError] = tryCatch((): void => {
+  throw null;
+});
+
+console.log(nullError.message); // "null"
+//          ^? const error: Error
+console.log(nullError.cause); // null
 ```
 
-### Named Operations for Debugging
+This ensures tryCatch always provides a proper error object.
+
+#### Extending Error types
+
+##### Option 1: Manually Set Result and Error Type
 
 ```ts
-const [result, error] = tryCatch(() => {
-  throw new Error("Failed to fetch data");
-}, "Fetch Data");
+type User = { id: number; name: string };
 
-console.log(error?.message); // "Operation \"Fetch Data\" failed: Failed to fetch data"
+async function main() {
+  const [user, error] = await tryCatch<Promise<User>, SyntaxError>(
+    fetchUser(1)
+  );
+
+  if (!error) return user; // ✅ user: User
+  console.error(error); // ❌ SyntaxError | Error
+}
 ```
 
-### Using `tryCatch.sync`
+##### Option 2: Using `tryCatch.errors<E>()` Helper
 
 ```ts
-const [result, error] = tryCatch.sync(() => JSON.parse("INVALID_JSON"));
-console.log(result); // null
-console.log(error?.message); // "Unexpected token I in JSON"
+async function main() {
+  const [user, error] = await tryCatch.errors<SyntaxError>()(fetchUser(1));
+
+  if (!error) return user; // ✅ user: User
+  console.error(error); // ❌ Error | SyntaxError
+}
 ```
 
-### Using `tryCatch.async`
+### Wrapping Functions for Reuse
+
+To avoid repetitive tryCatch calls, you can wrap functions:
 
 ```ts
-const [result, error] = await tryCatch.async(async () => {
-  throw new Error("Async operation failed");
-});
+const getUser = (id: number) =>
+  tryCatch
+    .errors<RangeError>()
+    .errors<SyntaxError | TypeError | DOMException>()
+    .async(fetchUser(id));
+
+// Or simply:
+// const getUser = (id: number) => tryCatch(fetchUser(id));
+
+async function main() {
+  const [user, error] = await getUser(1);
+
+  if (!error) return user; // ✅ user: User
+  console.error(error); // ❌ Error | RangeError | SyntaxError | TypeError | DOMException
+}
+```
 
-console.log(result); // null
-console.log(error?.message); // "Async operation failed"
+### Using in React Server Components (RSC)
+
+```tsx
+const getUser = (id: number) =>
+  tryCatch.errors<SyntaxError | TypeError | DOMException>()(fetchUser(id));
+
+async function UserPage({ id }: { id: number }) {
+  const [user, error] = await getUser(id);
+
+  if (!error) return <div>Hello {user.name}!</div>;
+
+  if (error instanceof SyntaxError) {
+    return <div>Error: {error.message}</div>;
+  }
+
+  return <div>Not found</div>;
+}
 ```
 
 ### Comparing `tryCatch` with `try...catch`
@@ -89,11 +181,11 @@ async function goodFunc() {
 }
 
 async function badFunc() {
-  throw "no data";
-  return "";
+  if (true) throw "no data";
+  return "some data";
 }
 
-// Using tryCatch
+// ✅ Using tryCatch
 const getData = async () => {
   let [data, err] = await tryCatch(badFunc);
   if (!err) return Response.json({ data });
@@ -107,7 +199,7 @@ const getData = async () => {
   return Response.error();
 };
 
-// Using tryCatch with constants
+// ✅ Using tryCatch with constants
 const getDataConst = async () => {
   const [data1, err1] = await tryCatch(badFunc);
   if (!err1) return Response.json({ data: data1 });
@@ -121,7 +213,7 @@ const getDataConst = async () => {
   return Response.error();
 };
 
-// Using try...catch
+// ❌ Using traditional try...catch (deep nesting)
 const getDataStandard = async () => {
   try {
     const data = await badFunc();
@@ -144,22 +236,31 @@ const getDataStandard = async () => {
 
 ## API Reference
 
-### `tryCatch<T>(fn: (() => T) | T, operationName?: string): Result<T>`
+### Main Function
 
-Handles both values and functions that may throw errors.
+```ts
+tryCatch<T, E extends Error = never>(fn?: (() => T) | T | Promise<T> | (() => Promise<T>), operationName?: string): Result<T, E>
+```
 
-### `tryCatch.sync<T>(fn: () => T, operationName?: string): Result<T>`
+- Handles values, sync/async functions
+- Automatically detects Promises
 
-Explicitly handles synchronous operations.
+### Explicit Synchronous Handling
 
-### `tryCatch.async<T>(fn: Promise<T> | (() => Promise<T>), operationName?: string): Promise<Result<T>>`
+```ts
+tryCatch.sync<T, E extends Error = never>(fn: () => T, operationName?: string): Result<T, E>
+```
 
-Explicitly handles asynchronous operations.
+### Explicit Asynchronous Handling
+
+```ts
+tryCatch.async<T, E extends Error = never>(fn: Promise<T> | (() => Promise<T>), operationName?: string): Promise<Result<T, E>>
+```
 
 ## Result Type
 
 ```ts
-type Result<T, E = Error> = [data: T | null, error: E | null];
+type Result<T, E = Error> = [data: T, error: null] | [data: null, error: E];
 ```
 
 ## Edge Cases
@@ -169,7 +270,7 @@ tryCatch(); // Returns [undefined, null]
 tryCatch(null); // Returns [null, null]
 tryCatch(() => {
   throw new Error("Unexpected Error");
-}); // Handles thrown errors
+}); // Returns [null, Error]
 tryCatch(Promise.reject(new Error("Promise rejected"))); // Handles rejected promises
 ```
 

bun.lock

@@ -10,8 +10,11 @@
         "tsup": "^8.4.0",
       },
       "peerDependencies": {
-        "typescript": "^5.8.2",
+        "typescript": "^5.0.0",
       },
+      "optionalPeers": [
+        "typescript",
+      ],
     },
   },
   "packages": {

package.json

@@ -50,6 +50,11 @@
     "tsup": "^8.4.0"
   },
   "peerDependencies": {
-    "typescript": "^5.8.2"
+    "typescript": "^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "typescript": {
+      "optional": true
+    }
   }
 }