1# Async/Await Basics
2 
3Use this when:
4 
5- You are starting fresh with async/await and need foundational patterns.
6- You are converting callback-based code to async/await.
7- You need to understand execution order and the sync-to-async bridge.
8 
9Skip this file if:
10 
11- You need parallel execution with task groups or `async let`. Use `tasks.md`.
12- You need stream-based async iteration. Use `async-sequences.md`.
13 
14Jump to:
15 
16- Function Declaration
17- Execution Order
18- Parallel Execution with async let
19- URLSession with Async/Await
20- Migration Strategy
21 
22## Function Declaration
23 
24Mark functions with `async` to indicate asynchronous work:
25 
26```swift
27func fetchData() async -> Data {
28    // async work
29}
30 
31func fetchData() async throws -> Data {
32    // async work that can fail
33}
34```
35 
36**Key benefit over closures**: The compiler enforces return values. No forgotten completion handlers.
37 
38> **Course Deep Dive**: This topic is covered in detail in [Lesson 2.1: Introduction to async/await syntax](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
39 
40## Calling Async Functions
41 
42### From synchronous context
43 
44Use `Task` to bridge from sync to async:
45 
46```swift
47Task {
48    let data = try await fetchData()
49}
50```
51 
52### From async context
53 
54Use `await` directly:
55 
56```swift
57func processData() async throws {
58    let data = try await fetchData()
59    // process data
60}
61```
62 
63## Execution Order
64 
65Structured concurrency executes top-to-bottom in the order you expect:
66 
67```swift
68let first = try await fetchData(1)   // Waits for completion
69let second = try await fetchData(2)  // Starts after first completes
70let third = try await fetchData(3)   // Starts after second completes
71```
72 
73Code after `await` only executes once the awaited function returns.
74 
75> **Course Deep Dive**: This topic is covered in detail in [Lesson 2.2: Understanding the order of execution](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
76 
77## Parallel Execution with async let
78 
79Use `async let` to run multiple operations concurrently:
80 
81```swift
82async let data1 = fetchData(1)
83async let data2 = fetchData(2)
84async let data3 = fetchData(3)
85 
86let results = try await [data1, data2, data3]
87```
88 
89### How async let works
90 
91- **Starts immediately**: The function executes right away, even before `await`
92- **Structured concurrency**: Automatically canceled when leaving scope
93- **Error handling**: If one fails, others are implicitly canceled when awaiting grouped results
94- **No redundant keywords**: Don't use `try await` in the `async let` line itself
95 
96```swift
97// Redundant - avoid this
98async let data = try await fetchData()
99 
100// Correct - errors handled at await point
101async let data = fetchData()
102let result = try await data
103```
104 
105### When to use async let
106 
107**Use when:**
108- Tasks don't depend on each other
109- Number of tasks known at compile-time
110- Want automatic cancellation on scope exit
111 
112**Avoid when:**
113- Tasks must run sequentially
114- Need dynamic task spawning (use `TaskGroup`)
115- Need manual cancellation control
116 
117### Limitations
118 
119- Cannot use at top-level declarations (only within function bodies)
120- Tasks not explicitly awaited may be canceled implicitly
121 
122> **Course Deep Dive**: This topic is covered in detail in [Lesson 2.3: Calling async functions in parallel using async let](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
123 
124## URLSession with Async/Await
125 
126URLSession provides async alternatives to closure-based APIs:
127 
128```swift
129// Closure-based (old)
130URLSession.shared.dataTask(with: request) { data, response, error in
131    guard let data = data, error == nil else { return }
132    // handle response
133}.resume()
134 
135// Async/await (modern)
136let (data, response) = try await URLSession.shared.data(for: request)
137```
138 
139### Benefits over closures
140 
141- No optional `data` or `response` to unwrap
142- Automatic error throwing
143- Compiler enforces return values
144- Simpler error handling with do-catch
145 
146### Complete network request pattern
147 
148```swift
149func fetchUser(id: Int) async throws -> User {
150    let url = URL(string: "https://api.example.com/users/\(id)")!
151    var request = URLRequest(url: url)
152    request.httpMethod = "GET"
153    
154    let (data, response) = try await URLSession.shared.data(for: request)
155    
156    guard let httpResponse = response as? HTTPURLResponse,
157          (200...299).contains(httpResponse.statusCode) else {
158        throw NetworkError.invalidResponse
159    }
160    
161    return try JSONDecoder().decode(User.self, from: data)
162}
163```
164 
165### POST requests with JSON
166 
167```swift
168func createUser(_ user: User) async throws -> User {
169    let url = URL(string: "https://api.example.com/users")!
170    var request = URLRequest(url: url)
171    request.httpMethod = "POST"
172    request.setValue("application/json", forHTTPHeaderField: "Content-Type")
173    request.httpBody = try JSONEncoder().encode(user)
174    
175    let (data, response) = try await URLSession.shared.data(for: request)
176    
177    guard let httpResponse = response as? HTTPURLResponse,
178          (200...299).contains(httpResponse.statusCode) else {
179        throw NetworkError.invalidResponse
180    }
181    
182    return try JSONDecoder().decode(User.self, from: data)
183}
184```
185 
186> **Course Deep Dive**: This topic is covered in detail in [Lesson 2.4: Performing network requests using URLSession and async/await](https://www.swiftconcurrencycourse.com?utm_source=github&utm_medium=agent-skill&utm_campaign=lesson-reference)
187 
188## Typed Errors (Swift 6)
189 
190Specify exact error types for better API contracts:
191 
192```swift
193enum NetworkError: Error {
194    case invalidResponse
195    case decodingFailed(DecodingError)
196    case requestFailed(URLError)
197}
198 
199func fetchData() async throws(NetworkError) -> Data {
200    do {
201        let (data, _) = try await URLSession.shared.data(from: url)
202        return data
203    } catch let error as URLError {
204        throw .requestFailed(error)
205    } catch {
206        throw .invalidResponse
207    }
208}
209```
210 
211Callers know exactly which errors to handle.
212 
213## Migration Strategy
214 
215When converting closure-based code:
216 
2171. **Add new async method alongside old one** - keeps code compiling
2182. **Update method signature** - add `async`, remove completion parameter
2193. **Replace closure calls with await** - use URLSession async APIs
2204. **Remove optional unwrapping** - async APIs return non-optional values
2215. **Simplify error handling** - use do-catch instead of nested closures
2226. **Return directly** - compiler enforces return values
223 
224## Common Patterns
225 
226### Sequential execution (when order matters)
227 
228```swift
229let user = try await fetchUser(id: 1)
230let posts = try await fetchPosts(userId: user.id)
231let comments = try await fetchComments(postIds: posts.map(\.id))
232```
233 
234### Parallel execution (when independent)
235 
236```swift
237async let user = fetchUser(id: 1)
238async let settings = fetchSettings()
239async let notifications = fetchNotifications()
240 
241let (userData, settingsData, notificationsData) = try await (user, settings, notifications)
242```
243 
244### Mixed execution
245 
246```swift
247// Fetch user first (required for next step)
248let user = try await fetchUser(id: 1)
249 
250// Then fetch related data in parallel
251async let posts = fetchPosts(userId: user.id)
252async let followers = fetchFollowers(userId: user.id)
253async let following = fetchFollowing(userId: user.id)
254 
255let profile = Profile(
256    user: user,
257    posts: try await posts,
258    followers: try await followers,
259    following: try await following
260)
261```
262 
263## Further Learning
264 
265For in-depth coverage of async/await patterns, error handling strategies, and real-world migration scenarios, see [Swift Concurrency Course](https://www.swiftconcurrencycourse.com).
266 
267