@shkumbinhsn/try-catch 0.0.1

package/README.md

@@ -0,0 +1,100 @@
+# Type-Safe Try-Catch Pattern for TypeScript
+
+This repository demonstrates an experimental approach to handling try-catch blocks in TypeScript with enhanced type safety and flexibility. This pattern allows developers to explicitly define the types of errors that can be thrown while maintaining compatibility with traditional try-catch usage.
+
+## Key Features
+
+1. **Full TypeScript Flexibility**: 
+   - Use the `Throws` utility to define the types of errors a function might throw.
+   - If type definitions are not needed, the function works like a traditional try-catch and returns a tuple `[data, error]`.
+
+2. **Explicit Error Types**:
+   - For functions throwing multiple errors (e.g., `CustomError`, `Error`), use `Throws` to explicitly declare them.
+
+3. **Ease of Use**:
+   - Handle returned tuples with an `if` statement to separate success from failure cases.
+
+## Limitations
+
+- **Duplicate Definitions**: 
+  - Errors need to be defined twice: once for throwing them and once in the return type. This is a design choice to ensure type safety, but it does not affect runtime behavior.
+
+---
+
+## Example Code
+
+### Defining a Function with Error Handling
+
+```typescript
+import { tryCatch, type Throws } from "./lib/try-catch";
+
+class CustomError extends Error {}
+
+function iMightFail(): string & Throws<CustomError> {
+  const random = Math.random();
+  if (random > 0.2) {
+    return "success";
+  } else if (random > 0.5) {
+    throw new CustomError();
+  }
+  throw new Error();
+}
+
+const [data, error] = tryCatch(() => iMightFail());
+
+if (error1) {
+  console.log("i Might fail failed", error.message);
+  //                                  ^? Error | CustomError
+} else {
+  console.log("i succeeded", data);
+  //                            ^? string
+}
+
+```
+
+### Async Functions with Errors
+
+```typescript
+function sleep(ms: number) {
+  return new Promise(resolve => setTimeout(resolve, ms));
+}
+
+async function iMightFailAsync(): Promise<string & Throws<CustomError>> {
+  await sleep(200);
+  const random = Math.random();
+  if (random > 0.2) {
+    return "success";
+  } else if (random > 0.5) {
+    throw new CustomError();
+  }
+  throw new Error();
+}
+
+const [data, error] = await tryCatch(() => iMightFailAsync());
+
+if (error2) {
+  console.log("i Might fail async failed", error.message);
+  //                                          ^? Error | CustomError
+} else {
+  console.log("i Might fail async succeeded", data);
+    //                                         ^? string
+}
+```
+
+### With normal typescript inference
+
+```typescript
+function iMightFailOrNot() {
+    return "success"
+}
+
+const [data3, error3] = tryCatch(iMightFailOrNot);
+
+if (error3) {
+    console.log("i Might fail or not failed", error3.message)
+    //                                          ^? Error
+} else {
+    console.log("i Might fail or not succeeded", data3)
+    //                                            ^? string
+}
+```

package/lib/try-catch.d.ts

@@ -0,0 +1,26 @@
+const errorSymbol = Symbol();
+type ErrorSymbol = typeof errorSymbol;
+
+export type Throws<T extends Error> = {
+  [errorSymbol]?: T
+};
+
+type ExtractErrors<T> = T extends Throws<infer E> ? E : never;
+
+type Simplify<T> = T extends any ? { [K in keyof T]: T[K] } : never;
+
+type ExtractData<T> =
+    T extends string ? string :
+        T extends number ? number :
+            T extends boolean ? boolean :
+                T extends symbol ? symbol :
+                    T extends bigint ? bigint :
+                        T extends null ? null :
+                            T extends undefined ? undefined :
+                                T extends Function ? T :
+                                    Simplify<Omit<T, ErrorSymbol>>;
+
+type DataError<T> = [ExtractData<T>, null] | [null, Error | ExtractErrors<T>];
+type TryCatchReturn<T> = T extends Promise<infer R> ? Promise<DataError<R>> : DataError<T>;
+
+export declare function tryCatch<T>(fn: () => T): TryCatchReturn<T>;

package/lib/try-catch.js

@@ -0,0 +1,29 @@
+/**
+ * Executes a function within a try-catch block and returns a tuple [data, error].
+ * 
+ * @param {Function} fn - The function to execute. Can be synchronous or return a Promise.
+ * @returns {Array|Promise<Array>} A tuple where:
+ *   - For success: [data, null] where data is the function's return value
+ *   - For failure: [null, error] where error is the caught exception
+ * 
+ * @example
+ * // Synchronous usage
+ * const [data, error] = tryCatch(() => riskyFunction());
+ * 
+ * @example  
+ * // Asynchronous usage
+ * const [data, error] = await tryCatch(() => asyncRiskyFunction());
+ */
+export function tryCatch(fn) {
+    try {
+        const result = fn();
+        if(result instanceof Promise) {
+            return new Promise((resolve) => {
+                result.then((data) => resolve([data, null])).catch((error) => resolve([null, error]))
+            })
+        }
+        return [result, null];
+    } catch (e) {
+        return [null, e]
+    }
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@shkumbinhsn/try-catch",
+  "version": "0.0.1",
+  "description": "A utility package for handling try-catch blocks in TypeScript.",
+  "main": "./lib/try-catch.js",
+  "module": "./lib/try-catch.js",
+  "types": "./lib/try-catch.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/try-catch.d.ts",
+      "import": "./lib/try-catch.js",
+      "require": "./lib/try-catch.js"
+    }
+  },
+  "files": [
+    "lib"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "echo \"No test specified\" && exit 0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/shkumbinhasani/ts-try-catch"
+  },
+  "keywords": [
+    "typescript",
+    "try-catch",
+    "error-handling",
+    "type-safe",
+    "utility",
+    "exception-handling",
+    "functional-programming",
+    "result-type"
+  ],
+  "author": "Shkumbin Hasani",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0"
+  }
+}