🎣 FreeTry

Stop the try/catch hell. Handle async & sync errors like a pro.
En finissez avec l'enfer des try/catch. Gérez vos erreurs async & sync comme un pro.

💡 Why FreeTry? / Pourquoi FreeTry ?

🇬🇧 EN

Handling errors in JavaScript/TypeScript often leads to deeply nested try/catch blocks, unreadable flows, and inconsistent error handling.

FreeTry introduces the "Error as Data" pattern (inspired by Go & Rust), returning a simple tuple:

[data, error]

This keeps your code:

• Linear\
• Predictable\
• Fully type-safe

🇫🇷 FR

La gestion des erreurs en JavaScript/TypeScript mène souvent à un code imbriqué et difficile à maintenir.

FreeTry applique le pattern « l'erreur comme donnée » (inspiré de Go & Rust) en retournant un simple tuple :

[data, error]

Résultat :

• Un flux linéaire\
• Un code prévisible\
• 100% type-safe

🔍 Comparison / Comparaison

❌ Before / Avant (Cognitive overload)

try {
  const res = await fetch('/api/user');
  const user = await res.json();
  // ... more nested try/catch
} catch (error) {
  console.error(error);
}

✅ With FreeTry / Avec FreeTry (Linear flow)

import { safe } from "freetry";

const [user, err] = await safe(api.getUser());

if (err) return handle(err);

Clean. Flat. Predictable.

📦 Installation

npm install freetry
# or
yarn add freetry
# or
pnpm add freetry

🛠 Features / Fonctionnalités

1️⃣ Async & Sync Safety

🇬🇧 EN: Handle both Promises and dangerous synchronous code (like JSON.parse).
🇫🇷 FR : Gérez les Promesses ainsi que le code synchrone risqué (comme JSON.parse).

// Async
const [data, err] = await safe(myPromise);

// Sync ✨
const [config, parseErr] = safe.sync(() => JSON.parse(rawData));

2️⃣ Safe.all (Parallelism)

🇬🇧 EN: Run multiple promises in parallel without one crash ruining everything.
🇫🇷 FR : Lancez plusieurs promesses en parallèle sans qu'un seul échec ne bloque tout.

const [results, err] = await safe.all([
  fetchUsers(),
  fetchPosts(),
]);

// results is a fully typed tuple:
// [User[], Post[]]

3️⃣ Resilience with Retry & Timeout

🇬🇧 EN: Automatically retry failed operations or set a strict time limit.
🇫🇷 FR : Relancez automatiquement les opérations échouées ou fixez une limite de temps.

// Retry 3 times before giving up
const [data, err] = await safeRetry(() => fetchData(), 3);

// Fail if not resolved after 2000ms
const [data2, err2] = await safeWithTimeout(api.getData(), 2000);

🧩 Advanced Usage / Usage Avancé

Fully Type-Safe / Inférence Automatique

🇬🇧 EN: Data types are automatically inferred. You can also specify custom Error types.
🇫🇷 FR : Les types de données sont déduits automatiquement. Spécifiez vos types d'erreurs métier.

type ApiError = {
  code: number;
  msg: string;
};

const [user, err] = await safe<User, ApiError>(fetchUser());

// user: User | null
// err: ApiError | null

📊 Benefits / Avantages

• ✅ Zero Dependencies --- Pure TypeScript\
• ⚡ Ultra-lightweight --- Under 1kb minified\
• 🧠 Linear Flow --- No more nested try/catch\
• 🎯 Auto-Typing --- Best-in-class Developer Experience\
• 🌳 Tree-shakable --- Only bundle what you use

🤝 Contributing

🇬🇧 EN: Contributions are welcome! Feel free to open an issue or a pull request.
🇫🇷 FR : Les contributions sont les bienvenues ! Ouvrez une issue ou une pull request.

📄 License

MIT © LOUZOLO Sim-Jr Steeven