feat: Add AsyncSequence.flatMapLatest operator (#382)

* 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>
This commit is contained in:
authored and GitHub committed 2026-03-04 13:58:48 -08:00
1 parent 2971dd5d9f
commit 5043186441
7 files changed
+1389 -1

No files matched your search

+2 -1
View File
@@ -9,4 +9,5 @@ DerivedData/
.netrc
.swiftpm
Package.resolved
.swift-version
.swift-version
test_output.log
+200
View File
@@ -0,0 +1,200 @@
# FlatMapLatest
* Proposal: [SAA-00nn](https://github.com/apple/swift-async-algorithms/blob/main/Evolution/00nn-flatMapLatest.md)
* Author(s): [Peter Friese](https://github.com/peterfriese)
* Status: **Proposed**
* Implementation:
[
[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/FlatMapLatest/AsyncFlatMapLatestSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestFlatMapLatest.swift)
]
* Decision Notes:
* Bugs:
## Introduction
When transforming elements of an asynchronous sequence into new asynchronous sequences, there are cases where only the results from the most recent transformation are relevant, and previous transformations should be abandoned. This is particularly common in reactive user interfaces where rapid user input triggers asynchronous operations, but only the result of the latest operation matters.
## Motivation
Consider a search-as-you-type interface where each keystroke triggers a network request:
```swift
let searchQueries = userInputField.textChanges
// Without flatMapLatest - all requests complete, wasting resources
for await query in searchQueries {
let results = try await searchAPI(query)
displayResults(results) // May display stale results
}
```
Without automatic cancellation, earlier requests continue to completion even though their results are no longer relevant. This wastes network bandwidth, server resources, and may display stale results to the user if a slower request completes after a faster one.
The `flatMapLatest` operator solves this by automatically cancelling iteration on the previous inner sequence whenever a new element arrives from the outer sequence:
```swift
let searchResults = searchQueries.flatMapLatest { query in
searchAPI(query)
}
for await result in searchResults {
displayResults(result) // Only latest results displayed
}
```
This pattern is broadly applicable:
- **Location-based queries**: Cancel previous location lookups when user moves
- **Dynamic configuration**: Restart data loading when settings change
- **Auto-save**: Only save the most recent changes when user types rapidly
- **Real-time data**: Switch to new data streams based on user selections
## Proposed Solution
The `flatMapLatest` algorithm transforms each element from the base `AsyncSequence` into a new inner `AsyncSequence` using a 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.
The interface is available on all `AsyncSequence` types where both the base and inner sequences are `Sendable` along with two disfavored refinements to account for variations of typed throws signatures:
```swift
extension AsyncSequence where Self: Sendable {
public func flatMapLatest<T: AsyncSequence & Sendable>(
_ transform: @escaping @Sendable (Element) -> T
) -> some AsyncSequence<T.Element, T.Failure> & Sendable where T.Failure == Failure, T.Element: Sendable, Element: Sendable
@_disfavoredOverload
public func flatMapLatest<T: AsyncSequence & Sendable>(
_ transform: @escaping @Sendable (Element) -> T
) -> some AsyncSequence<T.Element, Failure> & Sendable where T.Failure == Never, T.Element: Sendable, Element: Sendable
@_disfavoredOverload
public func flatMapLatest<T: AsyncSequence & Sendable>(
_ transform: @escaping @Sendable (Element) -> T
) -> some AsyncSequence<T.Element, T.Failure> & Sendable where Failure == Never, T.Element: Sendable, Element: Sendable
}
```
This provides a clean API for expressing switching behavior:
```swift
userActions.flatMapLatest { action in
performAction(action)
}
```
## 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.
Since both the base sequence and inner sequences must be `Sendable` (to support concurrent iteration and cancellation), `AsyncFlatMapLatestSequence` is unconditionally `Sendable`.
### Implementation Strategy
The implementation uses a state machine pattern to ensure thread-safe operation:
1. **Generation Tracking**: Each new inner sequence is assigned a generation number. Elements from stale generations are discarded.
2. **Explicit Cancellation**: When a new outer element arrives, the previous inner sequence's task is explicitly cancelled and its continuation is resumed with a cancellation error.
3. **Lock-Based Coordination**: A `Lock` protects the state machine from concurrent access.
4. **Continuation Management**: The storage manages continuations for both upstream (outer/inner sequences) and downstream (consumer) demand.
This approach eliminates race conditions where cancelled sequences could emit stale values.
### Behavioral Characteristics
**Switching**: When the base sequence produces a new element, the current inner sequence iteration is immediately cancelled. Any elements it would have produced are lost.
**Completion**: The sequence completes when:
1. The base sequence finishes producing elements, AND
2. The final inner sequence finishes producing elements
**Error Handling**: If either the base sequence or any inner sequence throws, the error is immediately propagated and all tasks are cancelled.
**Cancellation**: Cancelling the downstream iteration cancels both the base sequence iteration and the current inner sequence iteration.
## Example
```swift
let requests = AsyncStream<String> { continuation in
continuation.yield("query1")
try? await Task.sleep(for: .milliseconds(100))
continuation.yield("query2")
try? await Task.sleep(for: .milliseconds(100))
continuation.yield("query3")
continuation.finish()
}
let responses = requests.flatMapLatest { query in
AsyncStream<String> { continuation in
continuation.yield("\(query): loading")
try? await Task.sleep(for: .milliseconds(50))
continuation.yield("\(query): complete")
continuation.finish()
}
}
for await response in responses {
print(response)
}
// Output (may vary due to timing):
// query1: loading
// query2: loading
// query3: loading
// query3: complete
```
In this example, the earlier queries (query1 and query2) are cancelled before they complete, so only query3 produces its complete response.
## Effect on API Resilience
This is an additive API. No existing systems are changed. The new types introduced are:
- `AsyncFlatMapLatestSequence<Base, Inner>`: The sequence type
- Associated private types for the state machine implementation
These types will be part of the ABI surface area.
## Alternatives Considered
### Alternative Names
**`switchMap`**: Used in ReactiveX, but "switch" in Swift has strong association with control flow statements.
**`switchToLatest`**: Combine's terminology, but `flatMapLatest` is more discoverable alongside other `map` variants.
**`flatMap(...).latest()`**: Requires a hypothetical `flatMap` first, adding complexity.
### Delivering All Elements
An alternative behavior would buffer elements from cancelled sequences and deliver them later. However, this contradicts the core purpose of "latest" semantics and would be better served by a different operator.
### No Automatic Cancellation
Requiring manual cancellation would place significant burden on developers and be error-prone. The automatic cancellation is the key value proposition.
### Shorthand version for async sequences of async sequences
Mimicing combine a shorthand extension of `switchToLatest` could be added as an extension when the base AsyncSequence's element conforms to AsyncSequence. The implementation of which is trivial:
```swift
extension AsyncSequence where Self: Sendable {
func switchToLatest() -> some AsyncSequence<Element.Element, Failure> where Element: AsyncSequence, Element.Failure == Failure, Element.Element: Sendable, Element: Sendable {
flatMapLatest { $0 }
}
@_disfavoredOverload
func switchToLatest() -> some AsyncSequence<Element.Element, Failure> where Element: AsyncSequence, Element.Failure == Never, Element.Element: Sendable, Element: Sendable {
flatMapLatest { $0 }
}
@_disfavoredOverload
func switchToLatest() -> some AsyncSequence<Element.Element, Failure> where Element: AsyncSequence, Failure == Never, Element.Element: Sendable, Element: Sendable {
flatMapLatest { $0 }
}
}
```
## Comparison with Other Libraries
**ReactiveX**: ReactiveX has an [API definition of switchMap](https://reactivex.io/documentation/operators/flatmap.html) that performs the same operation for Observables, switching to the latest inner Observable.
**Combine**: Combine has an [API definition of switchToLatest()](https://developer.apple.com/documentation/combine/publisher/switchtolatest()) which subscribes to the most recent Publisher produced by an upstream Publisher of Publishers. `flatMapLatest` combines the map and switch operations into a single convenient operator.
**RxSwift**: RxSwift calls this operator `flatMapLatest`, which is the naming this proposal adopts.
@@ -0,0 +1,139 @@
# FlatMapLatest
* Author(s): [Peter Friese](https://github.com/peterfriese)
Transforms elements into asynchronous sequences, emitting elements from only the most recent inner sequence.
[[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/FlatMapLatest/AsyncFlatMapLatestSequence.swift) |
[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestFlatMapLatest.swift)]
```swift
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.
```swift
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:
```swift
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.
```swift
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
```swift
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
```swift
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
```swift
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](https://reactivex.io/documentation/operators/flatmap.html) which performs the same operation for Observables.
**Combine** Combine has an [API definition of switchToLatest()](https://developer.apple.com/documentation/combine/publisher/switchtolatest()) which flattens a publisher of publishers by subscribing to the most recent one.
@@ -0,0 +1,77 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2025 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
@available(AsyncAlgorithms 1.1, *)
extension AsyncSequence where Self: Sendable {
/// Transforms elements into new asynchronous sequences, emitting elements
/// from the most recent inner sequence.
///
/// When a new element is emitted by this sequence, the `transform`
/// is called to produce a new inner sequence. Iteration on the
/// previous inner sequence is cancelled, and iteration begins
/// on the new one.
public func flatMapLatest<T: AsyncSequence & Sendable>(
_ transform: @escaping @Sendable (Element) -> T
) -> some AsyncSequence<T.Element, T.Failure> & Sendable where T.Failure == Failure, T.Element: Sendable, Element: Sendable {
return AsyncFlatMapLatestSequence(self, transform: transform)
}
@_disfavoredOverload
public func flatMapLatest<T: AsyncSequence & Sendable>(
_ transform: @escaping @Sendable (Element) -> T
) -> some AsyncSequence<T.Element, Failure> & Sendable where T.Failure == Never, T.Element: Sendable, Element: Sendable {
return AsyncFlatMapLatestSequence(self) {
transform($0).mapError { _ -> Failure in
fatalError()
}
}
}
@_disfavoredOverload
public func flatMapLatest<T: AsyncSequence & Sendable>(
_ transform: @escaping @Sendable (Element) -> T
) -> some AsyncSequence<T.Element, T.Failure> & Sendable where Failure == Never, T.Element: Sendable, Element: Sendable {
return AsyncFlatMapLatestSequence(self.mapError { _ -> T.Failure in
fatalError()
}, transform: transform)
}
}
@available(AsyncAlgorithms 1.1, *)
struct AsyncFlatMapLatestSequence<Base: AsyncSequence & Sendable, Inner: AsyncSequence & Sendable>: AsyncSequence, Sendable where Base.Element: Sendable, Inner.Element: Sendable, Base.Failure == Inner.Failure{
typealias Element = Inner.Element
typealias Failure = Inner.Failure
let base: Base
let transform: @Sendable (Base.Element) -> Inner
init(_ base: Base, transform: @escaping @Sendable (Base.Element) -> Inner) {
self.base = base
self.transform = transform
}
func makeAsyncIterator() -> Iterator {
return Iterator(base: base, transform: transform)
}
struct Iterator: AsyncIteratorProtocol, Sendable {
let storage: FlatMapLatestStorage<Base, Inner>
init(base: Base, transform: @escaping @Sendable (Base.Element) -> Inner) {
self.storage = FlatMapLatestStorage(base: base, transform: transform)
}
func next(isolation: isolated (any Actor)? = #isolation) async throws(Failure) -> Element? {
return try await storage.next(isolation: isolation)
}
}
}
@@ -0,0 +1,531 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2025 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
import DequeModule
@available(AsyncAlgorithms 1.1, *)
struct FlatMapLatestStateMachine<Base: AsyncSequence & Sendable, Inner: AsyncSequence & Sendable>
where Base.Element: Sendable, Inner.Element: Sendable {
typealias Element = Inner.Element
private enum State {
case initial(Base)
case running(
outerTask: Task<Void, Never>?,
outerContinuation: UnsafeContinuation<Void, Error>?,
innerTask: Task<Void, Never>?,
innerContinuation: UnsafeContinuation<Void, Error>?,
downstreamContinuation: UnsafeContinuation<Element?, Error>?,
buffer: Deque<Result<Element, Error>>,
generation: Int,
outerFinished: Bool
)
case finished
}
private var state: State
private let transform: @Sendable (Base.Element) -> Inner
init(base: Base, transform: @escaping @Sendable (Base.Element) -> Inner) {
self.state = .initial(base)
self.transform = transform
}
enum NextAction {
case returnElement(Element)
case returnNil
case throwError(Error)
case startOuterTask(Base)
case suspend
}
enum Action {
case startInnerTask(
Inner,
generation: Int,
previousTask: Task<Void, Never>?,
previousContinuation: UnsafeContinuation<Void, Error>?
)
case cancelInnerTask(Task<Void, Never>, UnsafeContinuation<Void, Error>?)
case resumeDownstream(UnsafeContinuation<Element?, Error>, Result<Element?, Error>)
case resumeOuterContinuation(UnsafeContinuation<Void, Error>)
case cancelTasks(
Task<Void, Never>?,
Task<Void, Never>?,
UnsafeContinuation<Void, Error>?,
UnsafeContinuation<Void, Error>?
)
case none
}
enum SuspendAction {
case resumeOuterContinuation(UnsafeContinuation<Void, Error>)
case resumeInnerContinuation(UnsafeContinuation<Void, Error>)
case none
}
mutating func next() -> NextAction {
switch state {
case .initial(let base):
return .startOuterTask(base)
case .running(
let outerTask,
let outerCont,
let innerTask,
let innerCont,
let downstreamCont,
var buffer,
let generation,
let outerFinished
):
if let result = buffer.popFirst() {
state = .running(
outerTask: outerTask,
outerContinuation: outerCont,
innerTask: innerTask,
innerContinuation: innerCont,
downstreamContinuation: downstreamCont,
buffer: buffer,
generation: generation,
outerFinished: outerFinished
)
switch result {
case .success(let element): return .returnElement(element)
case .failure(let error): return .throwError(error)
}
} else if outerFinished && innerTask == nil {
state = .finished
return .returnNil
} else {
return .suspend
}
case .finished:
return .returnNil
}
}
mutating func next(for continuation: UnsafeContinuation<Element?, Error>) -> SuspendAction {
switch state {
case .initial:
fatalError("Should be started")
case .running(
let outerTask,
let outerCont,
let innerTask,
let innerCont,
let downstreamCont,
let buffer,
let generation,
let outerFinished
):
precondition(downstreamCont == nil, "Already have downstream continuation")
precondition(buffer.isEmpty, "Buffer should be empty if suspending")
state = .running(
outerTask: outerTask,
outerContinuation: outerCont,
innerTask: innerTask,
innerContinuation: innerCont,
downstreamContinuation: continuation,
buffer: buffer,
generation: generation,
outerFinished: outerFinished
)
// Resume waiting tasks to produce elements for downstream demand
if let innerCont = innerCont {
state = .running(
outerTask: outerTask,
outerContinuation: outerCont,
innerTask: innerTask,
innerContinuation: nil,
downstreamContinuation: continuation,
buffer: buffer,
generation: generation,
outerFinished: outerFinished
)
return .resumeInnerContinuation(innerCont)
}
if let outerCont = outerCont {
state = .running(
outerTask: outerTask,
outerContinuation: nil,
innerTask: innerTask,
innerContinuation: innerCont,
downstreamContinuation: continuation,
buffer: buffer,
generation: generation,
outerFinished: outerFinished
)
return .resumeOuterContinuation(outerCont)
}
return .none
case .finished:
continuation.resume(returning: nil)
return .none
}
}
mutating func outerTaskStarted(_ task: Task<Void, Never>) {
switch state {
case .initial:
// Transition to running
state = .running(
outerTask: task,
outerContinuation: nil,
innerTask: nil,
innerContinuation: nil,
downstreamContinuation: nil,
buffer: Deque(),
generation: 0,
outerFinished: false
)
default:
fatalError("Invalid state transition")
}
}
mutating func outerTaskSuspended(_ continuation: UnsafeContinuation<Void, Error>) -> SuspendAction {
switch state {
case .running(
let outerTask,
_,
let innerTask,
let innerCont,
let downstreamCont,
let buffer,
let generation,
let outerFinished
):
// If we have downstream demand, resume immediately
if downstreamCont != nil {
return .resumeOuterContinuation(continuation)
}
state = .running(
outerTask: outerTask,
outerContinuation: continuation,
innerTask: innerTask,
innerContinuation: innerCont,
downstreamContinuation: downstreamCont,
buffer: buffer,
generation: generation,
outerFinished: outerFinished
)
return .none
case .finished:
continuation.resume(throwing: CancellationError())
return .none
default:
fatalError("Invalid state")
}
}
mutating func outerElementProduced(_ element: Base.Element) -> Action {
switch state {
case .running(
let outerTask,
_,
let innerTask,
let innerCont,
let downstreamCont,
let buffer,
var generation,
let outerFinished
):
// New element from outer -> Cancel previous inner, start new inner
let newInner = transform(element)
generation += 1
state = .running(
outerTask: outerTask,
outerContinuation: nil, // We just consumed the continuation by producing
innerTask: nil, // Will be set by innerTaskStarted
innerContinuation: nil,
downstreamContinuation: downstreamCont,
buffer: buffer,
generation: generation,
outerFinished: outerFinished
)
return .startInnerTask(newInner, generation: generation, previousTask: innerTask, previousContinuation: innerCont)
case .finished:
return .none
default:
fatalError("Invalid state")
}
}
mutating func innerTaskStarted(_ task: Task<Void, Never>, generation: Int) {
switch state {
case .running(
let outerTask,
let outerCont,
_,
let innerCont,
let downstreamCont,
let buffer,
let currentGen,
let outerFinished
):
if generation != currentGen {
// Stale task from previous generation, ignore it
return
}
state = .running(
outerTask: outerTask,
outerContinuation: outerCont,
innerTask: task,
innerContinuation: innerCont,
downstreamContinuation: downstreamCont,
buffer: buffer,
generation: currentGen,
outerFinished: outerFinished
)
default:
// If finished, we don't care
break
}
}
mutating func innerTaskSuspended(_ continuation: UnsafeContinuation<Void, Error>, generation: Int) -> SuspendAction {
switch state {
case .running(
let outerTask,
let outerCont,
let innerTask,
_,
let downstreamCont,
let buffer,
let currentGen,
let outerFinished
):
if generation != currentGen {
// Stale generation
continuation.resume(throwing: CancellationError())
return .none
}
if downstreamCont != nil {
return .resumeInnerContinuation(continuation)
}
state = .running(
outerTask: outerTask,
outerContinuation: outerCont,
innerTask: innerTask,
innerContinuation: continuation,
downstreamContinuation: downstreamCont,
buffer: buffer,
generation: currentGen,
outerFinished: outerFinished
)
return .none
case .finished:
continuation.resume(throwing: CancellationError())
return .none
default:
fatalError("Invalid state")
}
}
mutating func innerElementProduced(_ element: Element, generation: Int) -> Action {
switch state {
case .running(
let outerTask,
let outerCont,
let innerTask,
_,
let downstreamCont,
var buffer,
let currentGen,
let outerFinished
):
if generation != currentGen {
return .none
}
guard let downstreamCont = downstreamCont else {
buffer.append(.success(element))
state = .running(
outerTask: outerTask,
outerContinuation: outerCont,
innerTask: innerTask,
innerContinuation: nil,
downstreamContinuation: nil,
buffer: buffer,
generation: currentGen,
outerFinished: outerFinished
)
return .none
}
state = .running(
outerTask: outerTask,
outerContinuation: outerCont,
innerTask: innerTask,
innerContinuation: nil, // Consumed
downstreamContinuation: nil,
buffer: buffer,
generation: currentGen,
outerFinished: outerFinished
)
return .resumeDownstream(downstreamCont, .success(element))
case .finished:
return .none
default:
fatalError("Invalid state")
}
}
mutating func innerFinished(generation: Int) -> Action {
switch state {
case .running(let outerTask, let outerCont, _, _, let downstreamCont, let buffer, let currentGen, let outerFinished):
if generation != currentGen {
return .none
}
// Inner finished.
if outerFinished {
// Both finished
state = .finished
if let downstreamCont = downstreamCont {
return .resumeDownstream(downstreamCont, .success(nil))
}
} else {
// Just this inner finished. Wait for next outer.
state = .running(
outerTask: outerTask,
outerContinuation: outerCont,
innerTask: nil,
innerContinuation: nil,
downstreamContinuation: downstreamCont,
buffer: buffer,
generation: currentGen,
outerFinished: outerFinished
)
// Resume outer sequence if downstream is waiting for more elements
if downstreamCont != nil, let outerCont = outerCont {
state = .running(
outerTask: outerTask,
outerContinuation: nil, // Consumed
innerTask: nil,
innerContinuation: nil,
downstreamContinuation: downstreamCont,
buffer: buffer,
generation: currentGen,
outerFinished: outerFinished
)
return .resumeOuterContinuation(outerCont)
}
}
return .none
default:
return .none
}
}
mutating func innerThrew(_ error: Error, generation: Int) -> Action {
switch state {
case .running(let outerTask, let outerCont, let innerTask, let innerCont, let downstreamCont, _, let currentGen, _):
if generation != currentGen {
return .none
}
state = .finished
let action: Action = .cancelTasks(outerTask, innerTask, outerCont, innerCont)
guard let downstreamCont = downstreamCont else {
return action
}
return .resumeDownstream(downstreamCont, .failure(error))
default:
return .none
}
}
mutating func outerFinished() -> Action {
switch state {
case .running(let outerTask, _, let innerTask, let innerCont, let downstreamCont, let buffer, let generation, _):
if innerTask == nil && buffer.isEmpty {
state = .finished
if let downstreamCont = downstreamCont {
return .resumeDownstream(downstreamCont, .success(nil))
}
} else {
state = .running(
outerTask: outerTask,
outerContinuation: nil,
innerTask: innerTask,
innerContinuation: innerCont,
downstreamContinuation: downstreamCont,
buffer: buffer,
generation: generation,
outerFinished: true
)
}
return .none
default:
return .none
}
}
mutating func outerThrew(_ error: Error) -> Action {
switch state {
case .running(let outerTask, let outerCont, let innerTask, let innerCont, let downstreamCont, _, _, _):
state = .finished
let action: Action = .cancelTasks(outerTask, innerTask, outerCont, innerCont)
guard let downstreamCont = downstreamCont else {
return action
}
return .resumeDownstream(downstreamCont, .failure(error))
default:
return .none
}
}
mutating func cancelled() -> Action {
switch state {
case .running(let outerTask, let outerCont, let innerTask, let innerCont, let downstreamCont, _, _, _):
state = .finished
let action: Action = .cancelTasks(outerTask, innerTask, outerCont, innerCont)
if let downstreamCont = downstreamCont {
return .resumeDownstream(downstreamCont, .success(nil))
}
return action
default:
state = .finished
return .none
}
}
}
@@ -0,0 +1,200 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2025 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
@available(AsyncAlgorithms 1.1, *)
final class FlatMapLatestStorage<Base: AsyncSequence & Sendable, Inner: AsyncSequence & Sendable>: @unchecked Sendable where Base.Element: Sendable, Inner.Element: Sendable {
typealias Element = Inner.Element
private let lock = Lock.allocate()
private var stateMachine: FlatMapLatestStateMachine<Base, Inner>
init(base: Base, transform: @escaping @Sendable (Base.Element) -> Inner) {
self.stateMachine = FlatMapLatestStateMachine(base: base, transform: transform)
}
deinit {
lock.deinitialize()
}
func next(isolation: isolated (any Actor)? = #isolation) async throws(Inner.Failure) -> Inner.Element? {
do {
return try await withTaskCancellationHandler {
lock.lock()
let action = stateMachine.next()
switch action {
case .returnElement(let element):
lock.unlock()
return element
case .returnNil:
lock.unlock()
return nil
case .throwError(let error):
lock.unlock()
throw error
case .startOuterTask(let base):
// We need to start the outer task and then suspend
startOuterTask(base)
return try await suspend()
case .suspend:
lock.unlock()
return try await suspend()
}
} onCancel: {
let action = lock.withLock { stateMachine.cancelled() }
handleAction(action)
}
} catch {
throw error as! Inner.Failure
}
}
private func suspend() async throws -> Element? {
return try await withUnsafeThrowingContinuation { continuation in
let action = lock.withLock { stateMachine.next(for: continuation) }
switch action {
case .resumeOuterContinuation(let continuation):
continuation.resume()
case .resumeInnerContinuation(let continuation):
continuation.resume()
case .none:
break
}
}
}
private func startOuterTask(_ base: Base) {
let task = Task {
var iterator = base.makeAsyncIterator()
loop: while true {
// Create a continuation to wait for demand
do {
try await withUnsafeThrowingContinuation { continuation in
let action = lock.withLock { stateMachine.outerTaskSuspended(continuation) }
switch action {
case .resumeOuterContinuation(let continuation):
continuation.resume()
case .resumeInnerContinuation(let continuation):
continuation.resume()
case .none:
break
}
}
} catch {
// Cancellation or other error during suspension
let action = lock.withLock { stateMachine.outerThrew(error) }
handleAction(action)
break loop
}
do {
if let element = try await iterator.next() {
let action = lock.withLock { stateMachine.outerElementProduced(element) }
handleAction(action)
} else {
let action = lock.withLock { stateMachine.outerFinished() }
handleAction(action)
break loop
}
} catch {
let action = lock.withLock { stateMachine.outerThrew(error) }
handleAction(action)
break loop
}
}
}
stateMachine.outerTaskStarted(task)
lock.unlock()
}
private func startInnerTask(_ inner: Inner, generation: Int) {
let task = Task {
var iterator = inner.makeAsyncIterator()
loop: while true {
// Wait for demand
do {
try await withUnsafeThrowingContinuation { continuation in
let action = lock.withLock { stateMachine.innerTaskSuspended(continuation, generation: generation) }
switch action {
case .resumeInnerContinuation(let continuation):
continuation.resume()
case .resumeOuterContinuation(let continuation):
continuation.resume()
case .none:
break
}
}
} catch {
// Cancellation
let action = lock.withLock { stateMachine.innerThrew(error, generation: generation) }
handleAction(action)
break loop
}
do {
if let element = try await iterator.next() {
let action = lock.withLock { stateMachine.innerElementProduced(element, generation: generation) }
handleAction(action)
} else {
let action = lock.withLock { stateMachine.innerFinished(generation: generation) }
handleAction(action)
break loop
}
} catch {
let action = lock.withLock { stateMachine.innerThrew(error, generation: generation) }
handleAction(action)
break loop
}
}
}
stateMachine.innerTaskStarted(task, generation: generation)
}
private func handleAction(_ action: FlatMapLatestStateMachine<Base, Inner>.Action) {
switch action {
case .startInnerTask(let inner, let generation, let previousTask, let previousCont):
if let previousTask = previousTask {
previousTask.cancel()
previousCont?.resume(throwing: CancellationError())
}
startInnerTask(inner, generation: generation)
case .cancelInnerTask(let task, let continuation):
task.cancel()
continuation?.resume(throwing: CancellationError())
case .resumeDownstream(let continuation, let result):
continuation.resume(with: result)
case .resumeOuterContinuation(let continuation):
continuation.resume()
case .cancelTasks(let outer, let inner, let outerCont, let innerCont):
outer?.cancel()
inner?.cancel()
outerCont?.resume(throwing: CancellationError())
innerCont?.resume(throwing: CancellationError())
case .none:
break
}
}
}
@@ -0,0 +1,240 @@
//===----------------------------------------------------------------------===//
//
// This source file is part of the Swift Async Algorithms open source project
//
// Copyright (c) 2022 Apple Inc. and the Swift project authors
// Licensed under Apache License v2.0 with Runtime Library Exception
//
// See https://swift.org/LICENSE.txt for license information
//
//===----------------------------------------------------------------------===//
import XCTest
import AsyncAlgorithms
@available(macOS 15.0, *)
final class TestFlatMapLatest: XCTestCase {
func test_simple_sequence() async throws {
let source = [1, 2, 3].async
let transformed = source.flatMapLatest { intValue in
return [intValue, intValue * 10].async
}
var results: [Int] = []
for try await element in transformed {
results.append(element)
}
// With synchronous emission, we expect only the last inner sequence [3, 30]
// However, depending on timing, we might see more intermediate values
XCTAssertTrue(results.contains(3), "Should contain 3")
XCTAssertTrue(results.contains(30), "Should contain 30")
// We should also verify it ends with the last sequence
XCTAssertEqual(results.suffix(2), [3, 30], "Should end with [3, 30]")
}
func test_interleaving_race_condition() async throws {
// This test simulates a scenario where the inner sequence is slow.
// In a naive implementation (without generation tracking), the inner task for '1'
// might wake up and yield AFTER '2' has already started, causing interleaving.
let source = [1, 2, 3].async
let transformed = source.flatMapLatest { intValue -> AsyncStream<Int> in
AsyncStream { continuation in
Task {
// Yield the value immediately
continuation.yield(intValue)
// Sleep for a bit to allow the outer sequence to move on
try? await Task.sleep(nanoseconds: 10_000_000) // 10ms
// Yield a second value - this should be ignored if a new outer value has arrived
continuation.yield(intValue * 10)
continuation.finish()
}
}
}
// We expect:
// 1 arrives -> starts inner(1) -> yields 1 -> sleeps
// 2 arrives -> cancels inner(1) -> starts inner(2) -> yields 2 -> sleeps
// 3 arrives -> cancels inner(2) -> starts inner(3) -> yields 3 -> sleeps
// inner(3) finishes sleep -> yields 30
//
// Ideally, we should NOT see 10 or 20.
// However, without strict synchronization, we might see them.
// The strict expectation for flatMapLatest is that once a new value arrives,
// the old one produces NO MORE values.
// Note: This test is probabilistic in the naive implementation.
// It might pass or fail depending on scheduling.
// But with a correct implementation, it should ALWAYS pass.
// We'll collect all results to see what happened
var results: [Int] = []
for try await element in transformed {
results.append(element)
}
// In the naive implementation, we might get [1, 2, 3, 10, 20, 30] or similar.
// We want strictly [3, 30] (or [1, 2, 3, 30] depending on how fast the outer sequence is consumed vs produced)
// Actually, if the outer sequence is consumed fast, we might see intermediate "first" values (1, 2).
// But we should NEVER see "second" values (10, 20) from cancelled sequences.
// Let's relax the check to: "Must not contain 10 or 20"
XCTAssertFalse(results.contains(10), "Should not contain 10 (from cancelled sequence 1)")
XCTAssertFalse(results.contains(20), "Should not contain 20 (from cancelled sequence 2)")
XCTAssertTrue(results.contains(30), "Should contain 30 (from final sequence)")
}
func test_outer_throwing() async throws {
let source = AsyncThrowingStream<Int, Error> { continuation in
Task {
for value in [1, 2, 3] {
if value == 2 {
continuation.finish(throwing: FlatMapLatestFailure())
return
}
continuation.yield(value)
try? await Task.sleep(nanoseconds: 5_000_000) // 5ms delay
}
continuation.finish()
}
}
let transformed = source.flatMapLatest { intValue in
return [intValue, intValue * 10].async
}
do {
for try await _ in transformed {}
XCTFail("Should have thrown")
} catch {
XCTAssertEqual(error as? FlatMapLatestFailure, FlatMapLatestFailure())
}
}
func test_inner_throwing() async throws {
let source = AsyncStream<Int> { continuation in
Task {
for value in [1, 2, 3] {
continuation.yield(value)
try? await Task.sleep(nanoseconds: 5_000_000) // 5ms delay between outer values
}
continuation.finish()
}
}
let transformed = source.flatMapLatest { intValue in
return [intValue].async.map { try $0.throwIf(2) }
}
do {
for try await _ in transformed {}
XCTFail("Should have thrown")
} catch {
XCTAssertEqual(error as? FlatMapLatestFailure, FlatMapLatestFailure())
}
}
func test_cancellation() async throws {
let source = [1, 2, 3].async
let transformed = source.flatMapLatest { intValue in
return [intValue].async
}
let task = Task {
for try await _ in transformed {}
}
task.cancel()
do {
try await task.value
} catch is CancellationError {
// Expected
} catch {
XCTFail("Unexpected error: \(error)")
}
}
func test_empty_outer() async throws {
let source = [].async.map { $0 as Int }
let transformed = source.flatMapLatest { intValue in
return [intValue].async
}
var count = 0
for try await _ in transformed {
count += 1
}
XCTAssertEqual(count, 0)
}
func test_empty_inner() async throws {
let source = [1, 2, 3].async
let transformed = source.flatMapLatest { _ in
return [].async.map { $0 as Int }
}
var count = 0
for try await _ in transformed {
count += 1
}
XCTAssertEqual(count, 0)
}
func test_concurrency_crash_repro() async throws {
// This test simulates the exact race condition where an inner stream producer
// mimics the behavior of Firestore/Combine publisher wrappers that might
// yield values or finish asynchronously relative to cancellation.
@Sendable func innerStream(for user: String) -> AsyncThrowingStream<Int, Error> {
return AsyncThrowingStream { continuation in
let task = Task {
for i in 0...100 {
// Artificial delay to allow overlap/interleaving
// This is critical to hit the race condition window
try await Task.sleep(nanoseconds: 1_000_000) // 1ms
continuation.yield(i)
}
continuation.finish()
}
continuation.onTermination = { @Sendable termination in
task.cancel()
}
}
}
let authStream = AsyncStream<String> { continuation in
continuation.yield("A")
Task {
// Yielding again triggers the switch (and cancellation of the previous inner stream)
try? await Task.sleep(nanoseconds: 10_000_000) // 10ms
continuation.yield("B")
try? await Task.sleep(nanoseconds: 10_000_000)
continuation.finish()
}
}
let combined = authStream.flatMapLatest { user in
innerStream(for: user)
}
// Determine success by running without crashing
for try await _ in combined {}
}
}
private struct FlatMapLatestFailure: Error, Equatable {}
extension Int {
fileprivate func throwIf(_ value: Int) throws -> Int {
if self == value {
throw FlatMapLatestFailure()
}
return self
}
}