^p-safe

p-safe provides a clean and elegant way to safely handle promise rejections and function errors without messy try/catch blocks.

Benefits

• Avoid Scoping Issues: Keep variables in local scope using const instead of declaring let outside try/catch blocks.
• Better Type Inference: Strictly type your errors instead of dealing with any or unknown in catch blocks.
• Clean Control Flow: Promotes a "fail-fast" pattern with flatter, more readable code that's easier to maintain.
• Flexible Patterns: Support for both Result pattern (trySafe) and Optional pattern (tryIgnore) depending on your needs.
• Async Native: Fully capable of wrapping both synchronous and asynchronous functions elegantly.

• Benefits
• Installation
• Usage
• Documentation
• Contributing
• License

Installation

npm install p-safe

pnpm install p-safe

yarn add p-safe

Usage

Result Pattern (trySafe)

Safely execute an operation and get back a structured object. This is best when you need to handle the error specifically.

import { trySafe } from 'p-safe';

const { data, error } = await trySafe(() => fetchUser(id));

if (error) {
  return console.error('Failed to load user:', error.message);
}

console.log('User name:', data.name);

Optional Pattern (tryIgnore)

Use this for "nice-to-have" operations where you don't care why it failed, you just want the result or null.

import { tryIgnore } from 'p-safe';

// If JSON is invalid, config will simply be null
const config = await tryIgnore(() => JSON.parse(maybeJson));

// If the file doesn't exist, it returns null instead of throwing
const stats = await tryIgnore(() => fs.promises.stat('./optional-file.txt'));

Manual Resolve/Reject

Use the resolve and reject callbacks for granular control, similar to the Promise constructor.

const { data, error } = await trySafe(async (resolve, reject) => {
  const resp = await fetch(url);
  if (!resp.ok) return reject(new Error('Fetch failed'));
  resolve(await resp.json());
});

Strict Typing

Leverage TypeScript to ensure your error handling is robust and type-safe by defining custom error types.

class MathError extends Error {}

const { data, error } = await trySafe<number, MathError>(
  async (resolve, reject) => {
    if (num < 0) return reject(new MathError('Negative number'));
    resolve(Math.sqrt(num));
  }
);

// error is typed as MathError | undefined
// data is typed as number | undefined

Documentation

For all configuration options, please see the API docs.

Contributing

Want to contribute? Awesome! To show your support is to star the project, or to raise issues on GitHub.

Thanks again for your support, it is much appreciated!

License

MIT Shahrad Elahi and contributors.