https://github.com/andreasnicolaou/safe
A simple utility for handling synchronous and asynchronous errors without relying on try-catch blocks.
https://github.com/andreasnicolaou/safe
exponential-backoff retry-strategies try-catch utility-library
Last synced: 2 months ago
JSON representation
A simple utility for handling synchronous and asynchronous errors without relying on try-catch blocks.
- Host: GitHub
- URL: https://github.com/andreasnicolaou/safe
- Owner: andreasnicolaou
- License: mit
- Created: 2025-03-30T11:59:50.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-04-06T08:57:49.000Z (3 months ago)
- Last Synced: 2026-04-06T10:26:49.518Z (3 months ago)
- Topics: exponential-backoff, retry-strategies, try-catch, utility-library
- Language: TypeScript
- Homepage:
- Size: 614 KB
- Stars: 3
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: .github/CODEOWNERS
Awesome Lists containing this project
README
# @andreasnicolaou/safe — Say Goodbye to Try-Catch Blocks!
[](https://snyk.io/test/github/andreasnicolaou/safe)
[](https://codecov.io/gh/andreasnicolaou/safe)
### **Tired of writing `try...catch` everywhere?**
Let `@andreasnicolaou/safe` handle it for you. This tiny, library automatically wraps your functions and promises in a safe execution environment.
## Features
- **No more try-catch everywhere:** Clean up your code by handling errors in one place.
- **Works with sync and async:** One API for both synchronous and asynchronous code.
- **TypeScript-first:** Full type inference and guards for safer code.
- **Customizable logging:** Plug in your own logger or error reporting.
- **Framework-agnostic:** Use in Node.js, browsers, React and more.
### Package Managers
```bash
# npm
npm install @andreasnicolaou/safe
# yarn
yarn add @andreasnicolaou/safe
# pnpm
pnpm add @andreasnicolaou/safe
```
## CDN Usage
For direct browser usage without a build step:
```html
```
The library will be available as `safe` on the global scope:
```html
// Example: use safe utilities from the global `safe` object
const { safe: safeFn, isSuccess, isFailure } = safe;
const [error, result] = safeFn(() => JSON.parse('{"foo": 123}'));
if (isSuccess([error, result])) {
console.log('Parsed:', result);
}
```
## Usage
You can use this library in any modern JavaScript environment:
### ESM (ECMAScript Modules)
```js
import { safe, isSuccess, isFailure } from '@andreasnicolaou/safe';
const [error, result] = safe(() => JSON.parse('{"foo": 123}'));
if (isSuccess([error, result])) {
console.log('Parsed:', result);
}
```
### CommonJS (Node.js require)
```js
const { safe, isSuccess, isFailure } = require('@andreasnicolaou/safe');
const [error, result] = safe(() => JSON.parse('{"foo": 123}'));
if (isSuccess([error, result])) {
console.log('Parsed:', result);
}
```
### UMD (CDN/Browser)
```html
const { safe: safeFn, isSuccess, isFailure } = safe;
const [error, result] = safeFn(() => JSON.parse('{"foo": 123}'));
if (isSuccess([error, result])) {
console.log('Parsed:', result);
}
```
## Basic Usage
```typescript
import { safe, isSuccess, isFailure } from '@andreasnicolaou/safe';
const [error, result] = safe(() => {
throw new Error('An error Occured!');
});
console.log(error); // An error Occured!
console.log(result); // undefined
console.log(isSuccess([error, result])); // false
console.log(isFailure([error, result])); // true
```
## Advanced Error Handling
```typescript
const { safe, safeWithRetries } = createSafeUtils({
logger: (error) => sentry.captureException(error),
logErrors: process.env.NODE_ENV === 'production',
});
```
## Architecture Benefits
- **Functional Programming Friendly**
Compose operations without error handling noise
- **TypeScript Optimized**
Full type inference and guards
- **Framework Agnostic**
Works with React, Node.js, Deno, etc.
## Related
- [Error Handling in TypeScript](https://www.typescriptlang.org/docs/handbook/release-notes/typescript-4-0.html#unknown-on-catch-clause-bindings)
- [RxJS Error Handling](https://rxjs.dev/guide/operators#error-handling-operators)
## Contributing
Contributions are welcome! If you encounter issues or have ideas to enhance the library, feel free to submit an issue or pull request.