trycatchless 1.0.0

package/README.md

@@ -0,0 +1,118 @@
+# tryit
+
+> A tiny, type-safe utility for linear async error handling in TypeScript and JavaScript.
+
+`tryit` simplifies error handling by converting Promises into a standardized `[error, result]` tuple, inspired by Go. It helps you write cleaner, more readable code by eliminating nested `try/catch` blocks and variable scoping issues.
+
+## Features
+
+- 📦 **Zero dependencies**: Lightweight and fast.
+- 🛡️ **Type-safe**: Full TypeScript support with generics.
+- 🧹 **Clean Syntax**: Linear control flow without nesting.
+- 🔧 **Error Normalization**: Automatically converts non-Error throws (like strings or objects) into proper `Error` objects, preserving the original data.
+- 🔒 **Safe**: Validates inputs and handles edge cases gracefully.
+
+## Installation
+
+```bash
+npm install tryit
+```
+
+## Quick Start
+
+### Basic Usage
+
+**Before:** Standard `try/catch` often leads to nested logic and "let" variables defined outside blocks.
+
+```ts
+let data;
+try {
+  data = await fetchData();
+} catch (err) {
+  console.error(err);
+  return;
+}
+console.log(data);
+```
+
+**After:** With `tryit`, handle errors linearly.
+
+```ts
+import { tryit } from 'tryit';
+
+const [err, data] = await tryit(fetchData());
+
+if (err) {
+  console.error('Something went wrong:', err);
+  return;
+}
+
+// TypeScript knows 'data' is safe and defined here
+console.log(data);
+```
+
+## Advanced Usage
+
+### TypeScript Generics
+
+`tryit` infers the return type automatically, but you can also pass a generic type explicitly.
+
+```ts
+interface User {
+  id: number;
+  name: string;
+}
+
+const [err, user] = await tryit<User>(api.getUser(1));
+
+if (!err) {
+  // 'user' is typed as User
+  console.log(user.name);
+}
+```
+
+### Handling Non-Standard Errors
+
+Some libraries throw strings or plain objects instead of proper `Error` instances. `tryit` handles this by normalizing them into an `Error` object. The original thrown value is preserved as a JSON string in the `.meta` property.
+
+```ts
+// Suppose a library does this: Promise.reject({ code: "UNAUTH", msg: "Stop!" })
+
+const [err, data] = await tryit(riskyOperation());
+
+if (err) {
+  console.error(err.message); // "[object Object]"
+  
+  // Access the original payload via .meta
+  if ((err as any).meta) {
+    const raw = JSON.parse((err as any).meta);
+    console.log(raw.code); // "UNAUTH"
+  }
+}
+```
+
+### Invalid Inputs
+
+If you accidentally pass something that isn't a Promise (like `null` or a string) to `tryit`, it won't crash. It resolves safely with an error.
+
+```ts
+const [err, data] = await tryit(null as any);
+// err: Error("Argument must be a Promise or thenable")
+```
+
+## API
+
+### `tryit<T>(promise: Promise<T>)`
+
+Wraps a Promise and returns a tuple.
+
+- **Parameters**:
+  - `promise`: A `Promise` or thenable object to resolve.
+
+- **Returns**: `Promise<[Error, null] | [null, T]>`
+  - Index `0`: An `Error` object if failed, otherwise `null`.
+  - Index `1`: The result data `T` if successful, otherwise `null`.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Represents the result tuple of the tryit function.
+ * Index 0 is the Error (or null if successful).
+ * Index 1 is the Result (or null if failed).
+ */
+export type TryitResult<T> = [Error, null] | [null, T];
+/**
+ * A functional utility that wraps a Promise in a try-catch block and returns a standardized
+ * tuple of [Error, Result].
+ *
+ * - Checks if input is a valid Promise or thenable.
+ * - Catches all errors, ensuring the function never throws synchronously.
+ * - Normalizes non-Error throws into Error objects, preserving metadata in `error.meta` as a JSON string.
+ *
+ * @template T The type of the value resolved by the promise.
+ * @param {Promise<T>} promise The promise to execute.
+ * @returns {Promise<TryitResult<T>>} A promise resolving to [Error, null] or [null, Result].
+ */
+export declare function tryit<T>(promise: Promise<T>): Promise<TryitResult<T>>;

package/dist/index.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tryit = tryit;
+/**
+ * A functional utility that wraps a Promise in a try-catch block and returns a standardized
+ * tuple of [Error, Result].
+ *
+ * - Checks if input is a valid Promise or thenable.
+ * - Catches all errors, ensuring the function never throws synchronously.
+ * - Normalizes non-Error throws into Error objects, preserving metadata in `error.meta` as a JSON string.
+ *
+ * @template T The type of the value resolved by the promise.
+ * @param {Promise<T>} promise The promise to execute.
+ * @returns {Promise<TryitResult<T>>} A promise resolving to [Error, null] or [null, Result].
+ */
+async function tryit(promise) {
+    if (!promise || typeof promise.then !== 'function') {
+        return [new Error("Argument must be a Promise or thenable"), null];
+    }
+    try {
+        const data = await promise;
+        return [null, data];
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            return [err, null];
+        }
+        const error = new Error(String(err));
+        try {
+            error.meta = JSON.stringify(err);
+        }
+        catch {
+            // Ignore serialization errors (e.g., circular structures)
+        }
+        return [error, null];
+    }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "trycatchless",
+  "version": "1.0.0",
+  "description": "A tiny, functional try-catch wrapper for promises that returns a [error, data] tuple.",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "ts-node test/index.test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "promise",
+    "async",
+    "await",
+    "try",
+    "catch",
+    "error-handling",
+    "functional",
+    "utility"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.0.0",
+    "ts-node": "^10.9.0",
+    "@types/node": "^20.0.0"
+  },
+  "engines": {
+    "node": ">=14"
+  }
+}