* feat: Add initial naive implementation of flatMapLatest This introduces a simplified version of the flatMapLatest operator for AsyncSequence, along with a basic unit test. Note that this implementation uses unstructured concurrency and may have race conditions regarding task cancellation. * refactor: Implement robust flatMapLatest with generation tracking - Replaces naive implementation with a thread-safe approach using ManagedCriticalState. - Introduces generation tracking to prevent race conditions where cancelled inner sequences could yield stale values. - Adds test_interleaving_race_condition to verify correctness under concurrent load. - Ensures Swift 6 Sendable compliance. * refactor: Implement high-performance State Machine for flatMapLatest - Replaces AsyncThrowingStream implementation with a custom AsyncSequence, Storage, and StateMachine. - Implements explicit state management using Lock for thread safety. - Handles concurrency between outer and inner sequences robustly. - Ensures correct cancellation propagation and error handling. - Verified with test_interleaving_race_condition. * refactor: Split flatMapLatest into separate files - Moves AsyncFlatMapLatestSequence.swift to Sources/AsyncAlgorithms/FlatMapLatest/ - Extracts FlatMapLatestStateMachine and FlatMapLatestStorage into their own files. - Aligns project structure with other complex operators like CombineLatest and Debounce. * test: Add comprehensive tests for flatMapLatest - Added test_outer_throwing to verify outer sequence error propagation - Added test_inner_throwing to verify inner sequence error propagation - Added test_cancellation to verify proper cancellation handling - Added test_empty_outer to verify empty outer sequence handling - Added test_empty_inner to verify empty inner sequence handling - Fixed test_simple_sequence to be more robust against timing issues * fix: Make test_outer_throwing stable - Changed from synchronous map with throwIf to AsyncThrowingStream - Added delay to ensure proper error propagation timing - Fixes intermittent test failures * refactor: Clean up verbose comments in FlatMapLatestStateMachine - Removed LLM-style thinking comments - Kept only essential, professional explanations - No functional changes, all tests pass * docs: Add comprehensive guide for flatMapLatest - Added FlatMapLatest.md documentation guide - Authored by Peter Friese - Includes introduction, code samples, and use cases - Covers search-as-you-type, location-based data, and dynamic config examples - Compares with similar operators in ReactiveX and Combine * docs: Add evolution proposal for flatMapLatest - Created SAA-00nn proposal for flatMapLatest operator - Includes motivation, detailed design, and examples - Covers implementation strategy with state machine - Compares with ReactiveX switchMap and Combine switchToLatest * mapError - transforming failures (#366) * Implement AsyncMapErrorSequence * Update the proposal, implementation and tests with formatting, additional details and modifications for being able to push it to a review * Foratting and preambles * Update Copyright date for error sequence Co-authored-by: Clive <clive819@users.noreply.github.com> * Update copyright year for mapError tests Co-authored-by: Clive <clive819@users.noreply.github.com> * Update availablity and modify the mapError algorithm to be opaque * Correct pre 6.0 build avail parameters * Make the formatting of the algorithm accesor a bit more consistent * Update the 5.8 package builder to define 1.2 * re-run formatter --------- Co-authored-by: Clive <clive819@gmail.com> Co-authored-by: Clive <clive819@users.noreply.github.com> * Update the flatMapLatest proposal and implementation to a pitchable state * Fix race condition in flatMapLatest and add regression test * chore: Remove test_output.log and add it to .gitignore --------- Co-authored-by: Philippe Hausler <phausler@apple.com> Co-authored-by: Clive <clive819@gmail.com> Co-authored-by: Clive <clive819@users.noreply.github.com>
5.1 KiB
FlatMapLatest
- Author(s): Peter Friese
Transforms elements into asynchronous sequences, emitting elements from only the most recent inner sequence.
let searchQuery = AsyncStream<String> { continuation in
// User types into search field
continuation.yield("swi")
try? await Task.sleep(for: .milliseconds(100))
continuation.yield("swift")
try? await Task.sleep(for: .milliseconds(100))
continuation.yield("swift async")
continuation.finish()
}
let searchResults = searchQuery.flatMapLatest { query in
performSearch(query) // Returns AsyncSequence<SearchResult>
}
for try await result in searchResults {
print(result) // Only shows results from "swift async"
}
Introduction
When transforming elements of an asynchronous sequence into new asynchronous sequences, you often want to abandon previous sequences when new data arrives. This is particularly useful for scenarios like search-as-you-type, where each keystroke triggers a new search request and you only care about results from the most recent query.
The flatMapLatest operator solves this by cancelling iteration on the previous inner sequence whenever a new element arrives from the outer sequence.
Proposed Solution
The flatMapLatest algorithm transforms each element from the base AsyncSequence into a new inner AsyncSequence using the provided transform closure. When a new element is produced by the base sequence, iteration on the current inner sequence is cancelled, and iteration begins on the newly created sequence.
extension AsyncSequence where Self: Sendable {
public func flatMapLatest<T: AsyncSequence & Sendable>(
_ transform: @escaping @Sendable (Element) -> T
) -> AsyncFlatMapLatestSequence<Self, T>
}
This creates a concise way to express switching behavior:
userInput.flatMapLatest { input in
fetchDataFromNetwork(input)
}
In this case, each new user input cancels any ongoing network request and starts a fresh one, ensuring only the latest data is delivered.
Detailed Design
The type that implements the algorithm emits elements from the inner sequences. It throws when either the base type or any inner sequence throws.
public struct AsyncFlatMapLatestSequence<Base: AsyncSequence & Sendable, Inner: AsyncSequence & Sendable>: AsyncSequence, Sendable
where Base.Element: Sendable, Inner.Element: Sendable {
public typealias Element = Inner.Element
public struct Iterator: AsyncIteratorProtocol, Sendable {
public func next() async throws -> Element?
}
public func makeAsyncIterator() -> Iterator
}
The implementation uses a state machine to ensure thread-safe operation and generation tracking to prevent stale values from cancelled sequences.
Behavior
- Switching: When a new element arrives from the base sequence, the current inner sequence is cancelled immediately
- Completion: The sequence completes when the base sequence finishes and the final inner sequence completes
- Error Handling: Errors from either the base or inner sequences are propagated immediately
- Cancellation: Cancelling iteration cancels both the base and current inner sequence
Use Cases
Search as You Type
let searchField = AsyncStream<String> { continuation in
// Emit search queries as user types
continuation.yield("s")
continuation.yield("sw")
continuation.yield("swift")
}
let results = searchField.flatMapLatest { query in
searchAPI(for: query)
}
Only the results for "swift" will be emitted, as earlier queries are cancelled.
Location-Based Data
let locationUpdates = CLLocationManager.shared.locationUpdates
let nearbyPlaces = locationUpdates.flatMapLatest { location in
fetchNearbyPlaces(at: location)
}
Each location update triggers a new search, cancelling any ongoing requests for previous locations.
Dynamic Configuration
let settings = userSettingsStream
let data = settings.flatMapLatest { config in
loadData(with: config)
}
When settings change, data loading is restarted with the new configuration.
Comparison with Other Operators
map: Transforms elements synchronously without producing sequences.
flatMap (if it existed): Would emit elements from all inner sequences concurrently, not cancelling previous ones.
switchToLatest (Combine): Equivalent operator in Combine framework - flatMapLatest is the AsyncSequence equivalent.
Comparison with Other Libraries
ReactiveX ReactiveX has an API definition of switchMap which performs the same operation for Observables.
Combine Combine has an API definition of switchToLatest() which flattens a publisher of publishers by subscribing to the most recent one.