You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+68-11Lines changed: 68 additions & 11 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -61,7 +61,7 @@ The correct approach is to conform to `LocalizedError`, which defines the follow
61
61
-`recoverySuggestion: String?`
62
62
-`helpAnchor: String?`
63
63
64
-
However, since all of these properties are optional, you won’t get any compiler errors if you forget to implement them. Worse, only `errorDescription` affects `localizedDescription`. Fields like `failureReason` and `recoverySuggestion` are ignored, while `helpAnchor` is rarely used today.
64
+
However, since all of these properties are optional, you won’t get any compiler errors if you forget to implement them. Worse, only `errorDescription` affects `localizedDescription`. Fields like `failureReason` and `recoverySuggestion` are ignored, while `helpAnchor` is rarely used nowadays.
65
65
66
66
This makes `LocalizedError` both confusing and error-prone.
67
67
@@ -71,11 +71,11 @@ To address these issues, **ErrorKit** introduces the `Throwable` protocol:
71
71
72
72
```swift
73
73
publicprotocolThrowable: LocalizedError {
74
-
varlocalizedDescription: String { get }
74
+
varuserFriendlyMessage: String { get }
75
75
}
76
76
```
77
77
78
-
This protocol is simple and clear. It’s named `Throwable` to align with Swift’s `throw` keyword and follows Swift’s convention of using the `able` suffix (like `Codable` and `Identifiable`). Most importantly, it requires the `localizedDescription` property, ensuring your errors behave exactly as expected.
78
+
This protocol is simple and clear. It’s named `Throwable` to align with Swift’s `throw` keyword and follows Swift’s convention of using the `able` suffix (like `Codable` and `Identifiable`). Most importantly, it requires the `userFriendlyMessage` property, ensuring your errors behave exactly as expected.
79
79
80
80
Here’s how you use it:
81
81
@@ -84,7 +84,7 @@ enum NetworkError: Throwable {
84
84
casenoConnectionToServer
85
85
caseparsingFailed
86
86
87
-
varlocalizedDescription: String {
87
+
varuserFriendlyMessage: String {
88
88
switchself {
89
89
case .noConnectionToServer:"Unable to connect to the server."
90
90
case .parsingFailed:"Data parsing failed."
@@ -110,24 +110,24 @@ This approach eliminates boilerplate code while keeping the error definitions co
110
110
111
111
### Summary
112
112
113
-
> Conform your custom error types to `Throwable` instead of `Error` or `LocalizedError`. The `Throwable` protocol requires only `localizedDescription: String`, ensuring your error messages are exactly what you expect – no surprises.
113
+
> Conform your custom error types to `Throwable` instead of `Error` or `LocalizedError`. The `Throwable` protocol requires only `userFriendlyMessage: String`, ensuring your error messages are exactly what you expect – no surprises.
114
114
115
115
116
-
## Enhanced Error Descriptions with `enhancedDescription(for:)`
116
+
## Enhanced Error Descriptions with `userFriendlyMessage(for:)`
117
117
118
-
ErrorKit goes beyond simplifying error handling — it enhances the clarity of error messages by providing improved, localized descriptions. With the `ErrorKit.enhancedDescription(for:)` function, developers can deliver clear, user-friendly error messages tailored to their audience.
118
+
ErrorKit goes beyond simplifying error handling — it enhances the clarity of error messages by providing improved, localized descriptions. With the `ErrorKit.userFriendlyMessage(for:)` function, developers can deliver clear, user-friendly error messages tailored to their audience.
119
119
120
120
### How It Works
121
121
122
-
The `enhancedDescription(for:)` function analyzes the provided `Error` and returns an enhanced, localized message. It draws on a community-maintained collection of descriptions to ensure the messages are accurate, helpful, and continuously evolving.
122
+
The `userFriendlyMessage(for:)` function analyzes the provided `Error` and returns an enhanced, localized message. It draws on a community-maintained collection of descriptions to ensure the messages are accurate, helpful, and continuously evolving.
123
123
124
124
### Supported Error Domains
125
125
126
126
ErrorKit supports errors from various domains such as `Foundation`, `CoreData`, `MapKit`, and more. These domains are continuously updated, providing coverage for the most common error types in Swift development.
127
127
128
128
### Usage Example
129
129
130
-
Here’s how to use `enhancedDescription(for:)` to handle errors gracefully:
130
+
Here’s how to use `userFriendlyMessage(for:)` to handle errors gracefully:
131
131
132
132
```swift
133
133
do {
@@ -136,12 +136,12 @@ do {
136
136
let_=tryData(contentsOf: url)
137
137
} catch {
138
138
// Print or show the enhanced error message to a user
139
-
print(ErrorKit.enhancedDescription(for: error))
139
+
print(ErrorKit.userFriendlyMessage(for: error))
140
140
// Example output: "You are not connected to the Internet. Please check your connection."
141
141
}
142
142
```
143
143
144
-
### Why Use `enhancedDescription(for:)`?
144
+
### Why Use `userFriendlyMessage(for:)`?
145
145
146
146
-**Localization**: Error messages are localized to ~40 languages to provide a better user experience.
Found a bug or missing description? We welcome your contributions! Submit a pull request (PR), and we’ll gladly review and merge it to enhance the library further.
153
153
154
154
> **Note:** The enhanced error descriptions are constantly evolving, and we’re committed to making them as accurate and helpful as possible.
155
+
156
+
## Overloads of Common System Functions with Typed Throws
157
+
158
+
ErrorKit introduces typed-throws overloads for common system APIs like `FileManager` and `URLSession`, providing more granular error handling and improved code clarity. These overloads allow you to handle specific error scenarios with tailored responses, making your code more robust and easier to maintain.
159
+
160
+
To streamline discovery, ErrorKit uses the same API names prefixed with `throwable`. These functions throw specific errors that conform to `Throwable`, allowing for clear and informative error messages.
161
+
162
+
**Enhanced User-Friendly Error Messages:**
163
+
164
+
One of the key advantages of ErrorKit's typed throws is the improved `localizedDescription` property. This property provides user-friendly error messages that are tailored to the specific error type. This eliminates the need for manual error message construction and ensures a consistent and informative user experience.
// Request write permission from the user intead of showing error message
175
+
default:
176
+
// Common error cases have a more descriptive message
177
+
showErrorDialog(error.localizedDescription)
178
+
}
179
+
}
180
+
```
181
+
182
+
The code demonstrates how to handle errors for specific error cases with an improved UX rather than just showing an error message to the user, which can still be the fallback. And the error cases are easy to discover thanks to the typed enum error.
183
+
184
+
**Example: Handling network request errors**
185
+
186
+
```swift
187
+
do {
188
+
let (data, response) =tryawait URLSession.shared.throwableData(from: URL(string: "https://api.example.com/data")!)
189
+
// Process the data and response
190
+
} catch {
191
+
// Error is of type `URLSessionError`
192
+
print(error.localizedDescription)
193
+
194
+
switch error {
195
+
case .timeout, .requestTimeout, .tooManyRequests:
196
+
// Automatically retry the request with a backoff strategy
197
+
case .noNetwork:
198
+
// Show an SF Symbol indicating the user is offline plus a retry button
199
+
case .unauthorized:
200
+
// Redirect the user to your login-flow (e.g. because token expired)
201
+
default:
202
+
// Fall back to showing error message
203
+
}
204
+
}
205
+
```
206
+
207
+
Here, the code leverages the specific error types to implement various kinds of custom logic. This demonstrates the power of typed throws in providing fine-grained control over error handling.
208
+
209
+
### Summary
210
+
211
+
By utilizing these typed-throws overloads, you can write more robust and maintainable code. ErrorKit's enhanced user-friendly messages and ability to handle specific errors with code lead to a better developer and user experience. As the library continues to evolve, we encourage the community to contribute additional overloads and error types for common system APIs to further enhance its capabilities.
0 commit comments