@shkumbinhsn/try-catch 0.0.6 → 0.0.8

package/README.md

@@ -0,0 +1,185 @@
+# @shkumbinhsn/try-catch
+
+[![npm version](https://img.shields.io/npm/v/@shkumbinhsn/try-catch.svg)](https://www.npmjs.com/package/@shkumbinhsn/try-catch)
+[![npm downloads](https://img.shields.io/npm/dm/@shkumbinhsn/try-catch.svg)](https://www.npmjs.com/package/@shkumbinhsn/try-catch)
+
+Type-safe error handling for TypeScript using a functional `[data, error]` tuple pattern.
+
+## Installation
+
+```bash
+npm install @shkumbinhsn/try-catch
+```
+
+## Features
+
+- **Type Safety**: Explicitly declare what errors your functions can throw
+- **Zero Runtime Overhead**: Types are compile-time only
+- **Async/Sync Support**: Works with both synchronous and asynchronous functions
+- **Lightweight**: No dependencies, minimal footprint
+- **Tuple-based**: Returns `[data, error]` for explicit error handling
+
+## Usage
+
+### Basic Example
+
+```typescript
+import { tryCatch, type Throws } from "@shkumbinhsn/try-catch";
+
+class CustomError extends Error {
+  name = "CustomError" as const;
+}
+
+function riskyOperation(): string & Throws<CustomError> {
+  if (Math.random() > 0.5) {
+    throw new CustomError("Something went wrong");
+  }
+  return "success";
+}
+
+const [data, error] = tryCatch(() => riskyOperation());
+
+if (error) {
+  // TypeScript knows: error is Error | CustomError
+  console.error("Failed:", error.message);
+} else {
+  // TypeScript knows: data is string
+  console.log("Success:", data);
+}
+```
+
+### Async Functions
+
+```typescript
+import { tryCatch, type Throws } from "@shkumbinhsn/try-catch";
+
+class ValidationError extends Error {}
+class NetworkError extends Error {}
+
+async function fetchUser(id: string): Promise<User> & Throws<ValidationError | NetworkError> {
+  if (!id) {
+    throw new ValidationError("User ID is required");
+  }
+  
+  const response = await fetch(`/api/users/${id}`);
+  if (!response.ok) {
+    throw new NetworkError("Failed to fetch user");
+  }
+  
+  return response.json();
+}
+
+// Async usage
+const [user, error] = await tryCatch(() => fetchUser("123"));
+
+if (error) {
+  if (error instanceof ValidationError) {
+    console.error("Validation failed:", error.message);
+  } else if (error instanceof NetworkError) {
+    console.error("Network failed:", error.message);
+  }
+} else {
+  console.log("User:", user.name);
+}
+```
+
+### Using `tc()` for Inferred Return Types
+
+When you want TypeScript to infer your return type but still declare possible errors, use the `tc()` helper:
+
+```typescript
+import { tryCatch, tc } from "@shkumbinhsn/try-catch";
+
+class APIError extends Error {}
+class NetworkError extends Error {}
+
+function fetchUser() {
+  const user = { id: "1", name: "Ada", email: "ada@example.com" };
+  // Return type is inferred as { id: string; name: string; email: string } & Throws<APIError | NetworkError>
+  return tc(user).mightThrow<APIError | NetworkError>();
+}
+
+const [data, error] = tryCatch(fetchUser);
+
+if (error) {
+  // TypeScript knows: error is Error | APIError | NetworkError
+  console.error("Failed:", error.message);
+} else {
+  // TypeScript knows: data is { id: string; name: string; email: string }
+  console.log("User email:", data.email);
+}
+```
+
+### Without Explicit Error Types
+
+When you don't specify error types, the library falls back to standard TypeScript inference:
+
+```typescript
+function regularFunction() {
+  return "success";
+}
+
+const [data, error] = tryCatch(regularFunction);
+
+if (error) {
+  // TypeScript knows: error is Error
+  console.error("Failed:", error.message);
+} else {
+  // TypeScript knows: data is string
+  console.log("Success:", data);
+}
+```
+
+## API Reference
+
+### `tryCatch<T>(fn: () => T): TryCatchReturn<T>`
+
+Executes a function within a try-catch block and returns a result tuple.
+
+**Parameters:**
+- `fn`: Function to execute (can be sync or async)
+
+**Returns:**
+- `[data, null]` on success
+- `[null, error]` on failure
+
+### `Throws<T extends Error>`
+
+Type utility for declaring error types in function signatures.
+
+```typescript
+function myFunction(): ReturnType & Throws<MyError> {
+  // implementation
+}
+```
+
+### `tc<T>(value: T): TcBuilder<T>`
+
+Creates a builder for branding return values with error types.
+
+```typescript
+function myFunction() {
+  const result = computeSomething();
+  return tc(result).mightThrow<ErrorA | ErrorB>();
+}
+```
+
+## Limitations
+
+- **Duplicate Definitions**: Error types must be declared in both the throw statement and return type
+- **Runtime Validation**: No runtime enforcement of declared error types
+- **Learning Curve**: Requires understanding of TypeScript's structural typing
+
+## ESLint Plugin
+
+For automated enforcement of best practices, use the companion ESLint plugin:
+
+```bash
+npm install -D @shkumbinhsn/try-catch-eslint
+```
+
+See [@shkumbinhsn/try-catch-eslint](https://www.npmjs.com/package/@shkumbinhsn/try-catch-eslint) for details.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shkumbinhsn/try-catch",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "description": "A utility package for handling try-catch blocks in TypeScript with full type inference.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",