Add AsyncMaterializedSequence

Creates an asynchronous sequence that iterates over the events of the original sequence.

Author: erikbasargin

Package.swift

@@ -18,6 +18,9 @@ let package = Package(
         .target(
             name: "AsyncSwiftly"
         ),
+        .target(
+            name: "AsyncMaterializedSequence"
+        ),
         .target(
             name: "TestingSupport",
             dependencies: [
@@ -26,11 +29,22 @@ let package = Package(
         ),
         .testTarget(
             name: "AsyncSwiftlyTests",
-            dependencies: ["AsyncSwiftly"]
+            dependencies: [
+                "AsyncSwiftly",
+            ]
+        ),
+        .testTarget(
+            name: "AsyncMaterializedSequenceTests",
+            dependencies: [
+                "AsyncMaterializedSequence", 
+                "TestingSupport",
+            ]
         ),
         .testTarget(
             name: "TestingSupportTests",
-            dependencies: ["TestingSupport"]
+            dependencies: [
+                "TestingSupport",
+            ]
         ),
     ]
 )

Sources/AsyncMaterializedSequence/AsyncMaterializedSequence.swift

@@ -0,0 +1,135 @@
+import Foundation
+
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension AsyncSequence {
+    
+    /// Creates an asynchronous sequence that iterates over the events of the original sequence.
+    ///
+    /// ```
+    /// for await event in (1...3).async.materialize() {
+    ///     print("\(event)")
+    /// }
+    ///
+    /// // .value(1)
+    /// // .value(2)
+    /// // .value(3)
+    /// // .completed(.finished)
+    /// ```
+    ///
+    /// - Returns: An `AsyncSequence` where the element is an event of the original `AsyncSequence`.
+    @inlinable
+    public func materialize() -> AsyncMaterializedSequence<Self> {
+        return AsyncMaterializedSequence(self)
+    }
+}
+
+/// An `AsyncSequence` that iterates over the events of the original `AsyncSequence`.
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+public struct AsyncMaterializedSequence<Base: AsyncSequence> {
+    
+    @usableFromInline
+    let base: Base
+    
+    @inlinable
+    init(_ base: Base) {
+        self.base = base
+    }
+}
+
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension AsyncMaterializedSequence: AsyncSequence {
+
+    public enum Completion {
+        case failure(Base.Failure)
+        case finished
+    }
+    
+    public enum Event {
+        case value(Base.Element)
+        case completed(Completion)
+    }
+    
+    public struct Iterator: AsyncIteratorProtocol {
+
+        @usableFromInline
+        var base: Base.AsyncIterator
+        
+        @usableFromInline
+        private(set) var baseIsCompleted: Bool = false
+        
+        @inlinable
+        init(_ base: Base.AsyncIterator) {
+            self.base = base
+        }
+        
+        @inlinable
+        public mutating func next() async -> Event? {
+            guard !baseIsCompleted else {
+                return nil
+            }
+            
+            do {
+                if let element = try await base.next() {
+                    return .value(element)
+                } else {
+                    baseIsCompleted = true
+                    return .completed(.finished)
+                }
+            } catch let error as Base.Failure {
+                baseIsCompleted = true
+                return .completed(.failure(error))
+            } catch {
+                preconditionFailure("Unexpected error: \(error)")
+            }
+        }
+    }
+    
+    @inlinable
+    public func makeAsyncIterator() -> Iterator {
+        Iterator(base.makeAsyncIterator())
+    }
+}
+
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension AsyncMaterializedSequence: Sendable where Base: Sendable, Base.Element: Sendable {}
+
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension AsyncMaterializedSequence.Completion: Sendable {}
+
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension AsyncMaterializedSequence.Event: Sendable where Base.Element: Sendable {}
+
+@available(*, unavailable)
+extension AsyncMaterializedSequence.Iterator: Sendable {}
+
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension AsyncMaterializedSequence.Completion: Equatable where Base.Failure: Equatable {}
+
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension AsyncMaterializedSequence.Event: Equatable where Base.Element: Equatable, Base.Failure: Equatable {}
+
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension AsyncMaterializedSequence.Completion: CustomDebugStringConvertible {
+    
+    public var debugDescription: String {
+        switch self {
+        case .failure(let error):
+            ".failure(\(error.localizedDescription))"
+        case .finished:
+            ".finished"
+        }
+    }
+}
+
+@available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+extension AsyncMaterializedSequence.Event: CustomDebugStringConvertible {
+
+    public var debugDescription: String {
+        switch self {
+        case .value(let element):
+            ".value(\(element))"
+        case .completed(let completion):
+            ".completed(\(completion))"
+        }
+    }
+}

Tests/AsyncMaterializedSequenceTests/AsyncMaterializedSequenceTests.swift

@@ -0,0 +1,103 @@
+import Testing
+import TestingSupport
+import AsyncMaterializedSequence
+
+struct AsyncMaterializedSequenceTests {
+
+    @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+    @Test func materialize_produces_next_events_of_values_of_original_element() async throws {
+        let source = 1...3
+        let sequence = source.async.materialize().prefix(source.count)
+        
+        await #expect(sequence.collect() == [
+            .value(1),
+            .value(2),
+            .value(3),
+        ])
+    }
+
+    @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+    @Test func materialize_produces_completed_event_when_source_sequence_completes() async throws {
+        let source = 0..<1
+        let sequence = source.async.materialize()
+        
+        await #expect(sequence.collect() == [
+            .value(0),
+            .completed(.finished),
+        ])
+    }
+
+    @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+    @Test func materialize_produces_completed_event_when_source_sequence_is_empty() async throws {
+        let source: [Int] = []
+        let sequence = source.async.materialize()
+        
+        await #expect(sequence.collect() == [
+            .completed(.finished),
+        ])
+    }
+    
+    @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+    @Test func materialize_forwards_termination_from_source_when_iteration_is_finished() async throws {
+        let source = 1...3
+        
+        var iterator = source.async.materialize().makeAsyncIterator()
+        while let _ = await iterator.next() {}
+
+        let pastEnd = await iterator.next()
+        #expect(pastEnd == nil)
+    }
+
+    @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+    @Test func materialize_produces_completed_event_when_source_sequence_throws() async throws {
+        let source = AsyncThrowingStream<Int, Error> { continuation in
+            continuation.finish(throwing: TestError())
+        }
+        
+        let sequence = source.materialize()
+        let events = await sequence.collect()
+        
+        #expect(events.count == 1)
+        
+        let event = try #require(events.last)
+        
+        switch event {
+        case .completed(.failure(let error)) where error is TestError:
+            break
+        default:
+            Issue.record("Unexpected event: \(event)")
+        }
+    }
+
+    @available(macOS 15.0, iOS 18.0, watchOS 11.0, tvOS 18.0, visionOS 2.0, *)
+    @Test func materialize_produces_completed_event_when_source_sequence_is_cancelled() async throws {
+        let trigger = AsyncStream.makeStream(of: Void.self, bufferingPolicy: .bufferingNewest(1))
+        let source = AsyncStream<Int> { continuation in
+            continuation.yield(0)
+        }
+        let sequence = source.materialize()
+        
+        let task = Task {
+            var firstIteration = false
+            return await sequence.reduce(into: [AsyncMaterializedSequence<AsyncStream<Int>>.Event]()) {
+                if !firstIteration {
+                    firstIteration = true
+                    trigger.continuation.finish()
+                }
+                $0.append($1)
+            }
+        }
+        
+        // ensure the other task actually starts
+        await trigger.stream.first { _ in true }
+        
+        // cancellation should ensure the loop finishes
+        // without regards to the remaining underlying sequence
+        task.cancel()
+            
+        await #expect(task.value == [
+            .value(0),
+            .completed(.finished),
+        ])
+    }
+}