Simplify try catch handling in JS/TS with explicit error management using discriminated union types.
Install with npm:
npm install @spongesoftware/trycatchOr with yarn:
yarn add @spongesoftware/trycatchOr with pnpm:
pnpm add @spongesoftware/trycatch- Node.js: >=20.0.0
- npm: >=9.0.0
- pnpm: >=8.0.0
- ✅ TypeScript support with full type safety
- ✅ Dual module support (CommonJS and ESM)
- ✅ Zero dependencies (runtime)
- ✅ Explicit error handling without throwing exceptions
- ✅ Discriminated union types for type-safe error management
- ✅ Support for both sync and async operations
Both tryCatch (for Promises) and tryCatchSync (for synchronous functions) return a Promise<Result> or Result object respectively. The Result type is a discriminated union with three properties: data, error, and success.
- If the operation succeeds:
successwill betrue,datawill contain the result, anderrorwill benull. - If the operation fails:
successwill befalse,errorwill contain the caught exception, anddatawill benull.
This pattern allows for explicit error handling without throwing exceptions.
Wraps an async operation in a try-catch block and returns a Promise<Result>.
import { tryCatch } from "@spongesoftware/trycatch"
// Example: TypeScript with explicit generics
interface User {
id: number
name: string
}
async function fetchUserById(userId: number) {
const { data, error, success } = await tryCatch<User, Error>(
fetch(`https://api.example.com/users/${userId}`).then((res) => {
if (!res.ok) {
throw new Error(`HTTP error! status: ${res.status}`)
}
return res.json()
})
)
if (success) {
console.log("User fetched:", data.name) // data is of type User
return data
} else {
console.error("Failed to fetch user:", error.message) // error is of type Error
return null
}
}
fetchUserById(123)
// Example: Inferred types for a simple API call
async function runAsyncExample() {
const { data, error, success } = await tryCatch(async () => {
await new Promise((resolve) => setTimeout(resolve, 100))
if (Math.random() > 0.5) {
throw new Error("Asynchronous operation failed")
}
return "Asynchronous success!"
})
if (success) {
console.log("Async operation data:", data)
} else {
console.error("Async operation error:", error.message)
}
}
runAsyncExample()Wraps a synchronous operation in a try-catch block and returns a Result object directly.
import { tryCatchSync } from "@spongesoftware/trycatch"
// Example: TypeScript with explicit generics
interface AppConfig {
apiUrl: string
timeoutMs: number
}
const configString = '{"apiUrl": "/api", "timeoutMs": 5000}'
const { data, error, success } = tryCatchSync<AppConfig, SyntaxError>(() => {
const parsed = JSON.parse(configString)
if (typeof parsed.timeoutMs !== "number") {
throw new SyntaxError("timeoutMs must be a number")
}
return parsed as AppConfig
})
if (success) {
console.log("Config loaded:", data.apiUrl, data.timeoutMs) // data is of type AppConfig
} else {
console.error("Failed to parse config:", error.message) // error is of type SyntaxError
}
// Example: Inferred types
const jsonString = '{"value": 123}'
const { data: parsedData, error: parseError, success: parseSuccess } =
tryCatchSync(() => JSON.parse(jsonString))
if (parseSuccess) {
console.log("Parsed synchronous data:", parsedData)
} else {
console.error("Synchronous parse error:", parseError.message)
}Wraps a Promise in a try-catch block and returns a Promise that resolves to a Result.
Type Parameters:
T- The type of the successful result (defaults tounknown)E- The type of the error (defaults toError)
Parameters:
promise- The Promise to execute and handle
Returns: A Promise that resolves to either a Success or Failure result
Wraps a synchronous function in a try-catch block and returns a Result.
Type Parameters:
T- The type of the successful result (defaults tounknown)E- The type of the error (defaults toError)
Parameters:
callback- The synchronous function to execute and handle
Returns: Either a Success or Failure result
A discriminated union type representing either a successful or failed operation.
Success Type:
interface Success<T> {
data: T
error: null
success: true
}Failure Type:
interface Failure<E> {
data: null
error: E
success: false
}Contributions are welcome! Please feel free to open an issue or submit a pull request.
This project is licensed under the Apache-2.0 License - see the LICENSE.md file for details.