https://github.com/flinedev/errorkit
Simplified error handling with built-in user-friendly messages for common errors. Fully localized. Community-driven.
https://github.com/flinedev/errorkit
debugging error-handling swift swift6 swiftui typed-throws
Last synced: 7 months ago
JSON representation
Simplified error handling with built-in user-friendly messages for common errors. Fully localized. Community-driven.
- Host: GitHub
- URL: https://github.com/flinedev/errorkit
- Owner: FlineDev
- License: mit
- Created: 2023-09-11T17:24:29.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2025-06-04T10:59:06.000Z (7 months ago)
- Last Synced: 2025-06-04T14:10:45.445Z (7 months ago)
- Topics: debugging, error-handling, swift, swift6, swiftui, typed-throws
- Language: Swift
- Homepage: https://swiftpackageindex.com/FlineDev/ErrorKit/documentation/errorkit
- Size: 2.84 MB
- Stars: 347
- Watchers: 3
- Forks: 6
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://swiftpackageindex.com/FlineDev/ErrorKit)
[](https://swiftpackageindex.com/FlineDev/ErrorKit)
# ErrorKit
Making error handling in Swift more intuitive and powerful with clearer messages, type safety, and user-friendly diagnostics.
## Overview
Swift's error handling has several limitations that make it challenging to create robust, user-friendly applications:
- The `Error` protocol's confusing behavior with `localizedDescription`
- Hard-to-understand system error messages
- Limited type safety in error propagation
- Difficulties with error chain debugging (relevant for typed throws!)
- Challenges in collecting meaningful feedback from users
ErrorKit addresses these challenges with a suite of lightweight, interconnected features you can adopt progressively.
## Core Features
### The Throwable Protocol
`Throwable` fixes the confusion of Swift's `Error` protocol by providing a clear, Swift-native approach to error handling:
```swift
enum NetworkError: Throwable {
case noConnectionToServer
case parsingFailed
var userFriendlyMessage: String {
switch self {
case .noConnectionToServer:
String(localized: "Unable to connect to the server.")
case .parsingFailed:
String(localized: "Data parsing failed.")
}
}
}
```
Now when catching this error, you'll see exactly what you expect:
```
"Unable to connect to the server."
```
For rapid development, you can use string raw values:
```swift
enum NetworkError: String, Throwable {
case noConnectionToServer = "Unable to connect to the server."
case parsingFailed = "Data parsing failed."
}
```
[Read more about Throwable →](https://swiftpackageindex.com/FlineDev/ErrorKit/documentation/errorkit/throwable-protocol)
### Enhanced Error Descriptions
Get improved, user-friendly messages for ANY error, including system errors:
```swift
do {
let _ = try Data(contentsOf: url)
} catch {
// Better than localizedDescription, works with any error type
print(ErrorKit.userFriendlyMessage(for: error))
// "You are not connected to the Internet. Please check your connection."
// String interpolation automatically uses userFriendlyMessage(for:)
print("Request failed: \(error)")
}
```
These enhanced descriptions are community-provided and fully localized mappings of common system errors to clearer, more actionable messages. ErrorKit comes with built-in mappers for Foundation, CoreData, MapKit, and more. You can also create custom mappers for third-party libraries or your own error types.
[Read more about Enhanced Error Descriptions →](https://swiftpackageindex.com/FlineDev/ErrorKit/documentation/errorkit/enhanced-error-descriptions)
## Swift 6 Typed Throws Support
Swift 6 introduces typed throws (`throws(ErrorType)`), bringing compile-time type checking to error handling. ErrorKit makes this powerful feature practical with solutions for its biggest challenges:
### Error Nesting with Catching
The `Catching` protocol solves the biggest problem with error handling: nested errors.
```swift
enum ProfileError: Throwable, Catching {
case validationFailed(field: String)
case caught(Error) // Single case handles all nested errors!
var userFriendlyMessage: String { /* ... */ }
}
struct ProfileRepository {
func loadProfile(id: String) throws(ProfileError) -> UserProfile {
// Regular error throwing for validation
guard id.isValidFormat else {
throw ProfileError.validationFailed(field: "id")
}
// Automatically wrap any database or file errors
let userData = try ProfileError.catch {
let user = try database.loadUser(id)
let settings = try fileSystem.readUserSettings(user.settingsPath)
return UserProfile(user: user, settings: settings)
}
return userData
}
}
```
[Read more about Typed Throws and Error Nesting →](https://swiftpackageindex.com/FlineDev/ErrorKit/documentation/errorkit/typed-throws-and-error-nesting)
### Error Chain Debugging
When using `Throwable` with the `Catching` protocol, you get powerful error chain debugging:
```swift
do {
try await updateUserProfile()
} catch {
print(ErrorKit.errorChainDescription(for: error))
// Output shows the complete error path:
// ProfileError
// └─ DatabaseError
// └─ FileError.notFound(path: "/Users/data.db")
// └─ userFriendlyMessage: "Could not find database file."
}
```
[Read more about Error Chain Debugging →](https://swiftpackageindex.com/FlineDev/ErrorKit/documentation/errorkit/error-chain-debugging)
## Ready-to-Use Tools
### Built-in Error Types
Stop reinventing common error types in every project. ErrorKit provides standardized error types for common scenarios:
```swift
func fetchUserData() throws(DatabaseError) {
guard isConnected else {
throw .connectionFailed
}
// Fetching logic
}
```
Includes ready-to-use types like `DatabaseError`, `NetworkError`, `FileError`, `ValidationError`, `PermissionError`, and more – all conforming to both `Throwable` and `Catching` with localized messages.
For quick one-off errors, use `GenericError`:
```swift
func quickOperation() throws {
guard condition else {
throw GenericError(userFriendlyMessage: "The operation couldn't be completed due to invalid state.")
}
// Operation logic
}
```
[Read more about Built-in Error Types →](https://swiftpackageindex.com/FlineDev/ErrorKit/documentation/errorkit/built-in-error-types)
### User Feedback with Error Logs
Gathering diagnostic information from users has never been simpler:
```swift
Button("Report a Problem") {
showMailComposer = true
}
.mailComposer(
isPresented: $showMailComposer,
recipient: "support@yourapp.com",
subject: "Bug Report",
messageBody: "Please describe what happened:",
attachments: [
try? ErrorKit.logAttachment(ofLast: .minutes(30))
]
)
```
With just a simple built-in SwiftUI modifier and the `logAttachment` helper function, you can easily include all log messages from Apple's unified logging system and let your users send them to you via email. Other integrations are also supported.
[Read more about User Feedback and Logging →](https://swiftpackageindex.com/FlineDev/ErrorKit/documentation/errorkit/user-feedback-with-logs)
## How These Features Work Together
ErrorKit's features are designed to complement each other while remaining independently useful:
1. **Start with improved error definitions** using `Throwable` for custom errors and `userFriendlyMessage(for:)` for system errors.
2. **Add type safety with Swift 6 typed throws**, using the `Catching` protocol to solve nested error challenges. This pairs with error chain debugging to understand error flows through your app.
3. **Save time with ready-made tools**: built-in error types for common scenarios and simple log collection for user feedback.
4. **Extend with custom mappers**: Create error mappers for any library to improve error messages across your entire application.
## Adoption Path
Here's a practical adoption strategy:
1. Replace `Error` with `Throwable` in your custom error types
2. Use `ErrorKit.userFriendlyMessage(for:)` when showing system errors
3. Adopt built-in error types where they fit your needs
4. Implement typed throws with `Catching` for more robust error flows
5. Add error chain debugging to improve error visibility
6. Integrate log collection with your feedback system
## Documentation
For complete documentation visit:
[ErrorKit Documentation](https://swiftpackageindex.com/FlineDev/ErrorKit/documentation/errorkit)
## Showcase
I created this library for my own Indie apps (download & rate them to show your appreciation):
App Icon
App Name & Description
Supported Platforms
TranslateKit: App Localization
AI-powered app localization with unmatched accuracy. Fast & easy: AI & proofreading, 125+ languages, market insights. Budget-friendly, free to try.
Mac
FreemiumKit: In-App Purchases for Indies
Simple In-App Purchases and Subscriptions: Automation, Paywalls, A/B Testing, Live Notifications, PPP, and more.
iPhone, iPad, Mac, Vision
Pleydia Organizer: Movie & Series Renamer
Simple, fast, and smart media management for your Movie, TV Show and Anime collection.
Mac
FreelanceKit: Project Time Tracking
Simple & affordable time tracking with a native experience for all devices. iCloud sync & CSV export included.
iPhone, iPad, Mac, Vision
CrossCraft: Custom Crosswords
Create themed & personalized crosswords. Solve them yourself or share them to challenge others.
iPhone, iPad, Mac, Vision
FocusBeats: Pomodoro + Music
Deep Focus with proven Pomodoro method & select Apple Music playlists & themes. Automatically pauses music during breaks.
iPhone, iPad, Mac, Vision
Posters: Discover Movies at Home
Auto-updating & interactive posters for your home with trailers, showtimes, and links to streaming services.
Vision