JSPM

  • ESM via JSPM
  • ES Module Entrypoint
  • Export Map
  • Keywords
  • License
  • Repository URL
  • TypeScript Types
  • README
  • Created
  • Published
  • Downloads 1
  • Score
    100M100P100Q33426F
  • License MIT

Lightweight TypeScript utilities for safe async/sync error handling

Package Exports

  • soft-error
  • soft-error/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 (soft-error) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

soft-error

A tiny TypeScript utility to wrap synchronous or asynchronous functions in safe try/catch logic, returning null (for _try) or a structured result (for _catch) instead of throwing.

Features

  • _try: Executes code, catches errors or promise rejections, and returns either the result or null.
  • _catch: Executes code, catches errors or promise rejections, and returns { value, error, ok } for easier pattern matching.
  • Works seamlessly with both sync and async handlers.
  • Optional per-call error callbacks.

Installation

npm install soft-error
# or
yarn add soft-error

Usage

import { _try, _catch } from "soft-error";

_try

Signature

// Sync
function _try<T, E extends Error = Error>(opts: {
  handler: () => T;
  onError?: (err: E) => void;
}): T | null;

// Async
function _try<T, E extends Error = Error>(opts: {
  handler: () => Promise<T>;
  onError?: (err: E) => void;
}): Promise<T | null>;
  • handler: Your function (sync or async).
  • onError (optional): A callback invoked with the caught error; return value is ignored.

Returns the handler’s return value, or null if any exception/rejection occurred.

Examples
// Sync example
const result = _try({
  handler: () => JSON.parse('{"foo": 1}'),
  onError: (err) => console.error("Failed to parse:", err),
});
// result === { foo: 1 }

// Sync with error
const bad = _try({
  handler: () => JSON.parse("not valid"),
  onError: (err) => console.warn("Parse error"),
});
// bad === null

// Async example
(async () => {
  const data = await _try({
    handler: () => fetch("/api/data").then((r) => r.json()),
    onError: (err) => alert("Network error"),
  });
  // data is parsed JSON or null
})();

_try

Signature

// Sync
function _catch<T, E extends Error = Error>(
  handler: () => T
): { value: T; error: null; ok: true } | { value: null; error: E; ok: false };

// Async
function _catch<T, E extends Error = Error>(
  handler: () => Promise<T>
): Promise<
  { value: T; error: null; ok: true } | { value: null; error: E; ok: false }
>;

Returns an object:

  • ok: true on success, with value: T and error: null.
  • ok: false on failure, with value: null and error: E.
Examples
// Sync success
const result = _catch(() => 2 + 2);
// => { ok: true, value: 4, error: null }

// Sync failure
const failed = _catch(() => {
  throw new TypeError("oops");
});
// => { ok: false, value: null, error: TypeError("oops") }

// Async success
(async () => {
  const res = await _catch(() => Promise.resolve("hello"));
  // => { ok: true, value: "hello", error: null }
})();

// Async failure
(async () => {
  const res = await _catch(() => Promise.reject(new Error("fail")));
  // => { ok: false, value: null, error: Error("fail") }
})();

API Reference

Function Returns Description
isPromise(obj) obj is Promise<T> Type-guard to detect Promise-like values.
_try(opts) T | nullorPromise<T | null> Execute handler safely, return null on error.
_catch(fn) CatchResult<T, E> or Promise<CatchResult> Execute handler, return structured success/failure.

License

MIT © Rayen Boussayed