Package Exports

@pidchashyi/try-catch
@pidchashyi/try-catch/dist/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (@pidchashyi/try-catch) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

`@pidchashyi/try-catch`

🧰 Type-safe try/catch wrapper for async operations — returns structured Result<T, E> objects instead of throwing errors.

Eliminate unhandled exceptions and simplify async error handling with a clean, typed interface. Features optional logging, lifecycle hooks, retry mechanisms, and full type inference.

📦 Installation

npm install @pidchashyi/try-catch

⚙️ Core Types

`Result<T, E>`

type Result<T, E = Error> = Success<T> | Failure<E>;

Success Type

type Success<T> = {
  status: "success";
  data: T;
  error: null;
  performance?: number;
};

Failure Type

type Failure<E> = {
  status: "failure";
  data: null;
  error: E;
  performance?: number;
};

Configuration Types

RetryOptions

type RetryOptions = {
  retries: number; // Number of retry attempts
  delayMs?: number; // Delay between retries in milliseconds
};

BaseTryCatchOptions

type BaseTryCatchOptions<E = Error> = {
  logError?: boolean; // Enable error logging to console
  onError?: (error: E) => void; // Custom error handler callback
  onFinally?: () => void; // Callback executed after try-catch
  performance?: boolean; // Enable performance tracking
};

TryCatchOptions

type TryCatchOptions<E = Error> = BaseTryCatchOptions<E> & {
  retry?: RetryOptions;
};

TryCatchAllOptions

type TryCatchAllOptions<E = Error> = BaseTryCatchOptions<E> & {
  failFast?: boolean; // If true, fails on first error (default)
};

PartialResults

type PartialResults<T, E = Error> = {
  successes: T[]; // Array of successful results
  errors: E[]; // Array of errors that occurred
  successIndices: number[]; // Original indices of successes
  errorIndices: number[]; // Original indices of failures
};

🛠️ Core Functions

`tryCatchSync<T, S = T, E = Error>`

Synchronous try-catch wrapper for non-async operations.

const result = tryCatchSync(() => someOperation(), {
  select: (data) => transformData(data),
  logError: true,
  onError: (err) => handleError(err),
  onFinally: () => cleanup(),
});

`tryCatch<T, S = T, E = Error>`

Asynchronous try-catch wrapper with retry capabilities.

const result = await tryCatch(fetchData(), {
  retry: { retries: 3, delayMs: 1000 },
  select: (data) => transformData(data),
  logError: true,
  onError: (err) => handleError(err),
  onFinally: () => cleanup(),
});

`tryCatchAll<T, E = Error>`

Execute multiple promises concurrently with fail-fast behavior.

const result = await tryCatchAll([promise1, promise2, promise3], {
  logError: true,
  onError: (err) => handleError(err),
  onFinally: () => cleanup(),
});

`tryCatchAllSafe<T, E = Error>`

Execute multiple promises concurrently with fail-soft behavior.

const result = await tryCatchAllSafe([promise1, promise2, promise3], {
  logError: true,
  onError: (err) => handleError(err),
  onFinally: () => cleanup(),
});

🔍 Utility Functions

Type Guards

isSuccess<T, E>(result: Result<T, E>): result is Success<T>
isFailure<T, E>(result: Result<T, E>): result is Failure<E>

Helper Functions

sleep(ms: number): Promise<void>                 // Delay execution
toError(error: unknown): Error                   // Convert unknown to Error
getErrorMessage(error: unknown): string          // Extract error message
map<T, U, E>(result: Result<T, E>, fn: (value: T) => U): Result<U, E>  // Transform success value

📝 Examples

Basic Usage

import { tryCatch, isSuccess } from "@pidchashyi/try-catch";

const result = await tryCatch(
  fetch("https://api.example.com/data").then((res) => res.json()),
  {
    select: (data) => data.items,
    logError: true,
  }
);

if (isSuccess(result)) {
  console.log("Data:", result.data);
} else {
  console.error("Error:", result.error);
}

With Retry Logic

const result = await tryCatch(fetchWithPotentialFailure(), {
  retry: {
    retries: 3,
    delayMs: 1000,
  },
  logError: true,
  onError: (err) => notifyUser(err),
  performance: true,
});

if (isSuccess(result)) {
  console.log(`Operation succeeded in ${result.performance} seconds`);
}

Parallel Operations

const result = await tryCatchAll([fetchUser(1), fetchUser(2), fetchUser(3)]);

if (isSuccess(result)) {
  console.log("All users:", result.data);
}

Safe Parallel Operations

const result = await tryCatchAllSafe([
  fetchUser(1),
  fetchUser(2),
  fetchUser(3),
]);

if (isSuccess(result)) {
  console.log("Successful fetches:", result.data.successes);
  console.log("Failed fetches:", result.data.errors);
  console.log("Success indices:", result.data.successIndices);
}

🛡️ Features & Benefits

✅ Fully typed Success<T> / Failure<E> results ✅ Comprehensive retry mechanism ✅ Performance tracking ✅ Parallel execution support ✅ Safe error handling with type inference ✅ Optional logging and lifecycle hooks ✅ Transform results with selectors ✅ No dependencies ✅ Framework agnostic

👤 Author

Built with safety-first philosophy by Pidchashyi