Add recursiveMap(_:) methods

Guides/Effects.md

@@ -40,6 +40,8 @@
 | `AsyncMerge2Sequence.Iterator`                      | rethrows     | Sendable    |
 | `AsyncMerge3Sequence`                               | rethrows     | Sendable    |
 | `AsyncMerge3Sequence.Iterator`                      | rethrows     | Sendable    |
+| `AsyncRecursiveMapSequence`                         | rethrows     | Conditional |
+| `AsyncRecursiveMapSequence.Iterator`                | rethrows     | Conditional |
 | `AsyncRemoveDuplicatesSequence`                     | rethrows     | Conditional |
 | `AsyncRemoveDuplicatesSequence.Iterator`            | rethrows     | Conditional |
 | `AsyncThrottleSequence`                             | rethrows     | Conditional |
@@ -50,6 +52,8 @@
 | `AsyncThrowingExclusiveReductionsSequence.Iterator` | throws       | Conditional |
 | `AsyncThrowingInclusiveReductionsSequence`          | throws       | Conditional |
 | `AsyncThrowingInclusiveReductionsSequence.Iterator` | throws       | Conditional |
+| `AsyncThrowingRecursiveMapSequence`                 | throws       | Conditional |
+| `AsyncThrowingRecursiveMapSequence.Iterator`        | throws       | Conditional |
 | `AsyncTimerSequence`                                | non-throwing | Sendable    |
 | `AsyncTimerSequence.Iterator`                       | non-throwing | Sendable    |
 | `AsyncZip2Sequence`                                 | rethrows     | Sendable    |

Guides/RecursiveMap.md

@@ -0,0 +1,56 @@
+# RecursiveMap
+
+* Author(s): [Susan Cheng](https://github.com/SusanDoggie)
+
+[
+[Source](https://github.com/apple/swift-async-algorithms/blob/main/Sources/AsyncAlgorithms/AsyncRecursiveMapSequence.swift) |
+[Tests](https://github.com/apple/swift-async-algorithms/blob/main/Tests/AsyncAlgorithmsTests/TestRecursiveMap.swift)
+]
+
+Produces a sequence containing the original sequence followed by recursive mapped sequence.
+
+```swift
+struct Node {
+    var id: Int
+    var children: [Node] = []
+}
+let tree = [
+    Node(id: 1, children: [
+        Node(id: 3),
+        Node(id: 4, children: [
+            Node(id: 6),
+        ]),
+        Node(id: 5),
+    ]),
+    Node(id: 2),
+]
+for await node in tree.async.recursiveMap({ $0.children.async }) {
+    print(node.id)
+}
+// 1
+// 2
+// 3
+// 4
+// 5
+// 6
+```
+
+## Detailed Design
+
+The `recursiveMap(_:)` method is declared as `AsyncSequence` extensions, and return `AsyncRecursiveMapSequence` or `AsyncThrowingRecursiveMapSequence` instance:
+
+```swift
+extension AsyncSequence {
+    public func recursiveMap<S>(
+        _ transform: @Sendable @escaping (Element) async -> S
+    ) -> AsyncRecursiveMapSequence<Self, S>
+
+    public func recursiveMap<S>(
+        _ transform: @Sendable @escaping (Element) async throws -> S
+    ) -> AsyncThrowingRecursiveMapSequence<Self, S>
+}
+```
+
+### Complexity
+
+Calling this method is O(_1_).

README.md

@@ -39,6 +39,7 @@ This package is the home for these APIs. Development and API design take place o
 #### Other useful asynchronous sequences
 - [`chunks(...)` and `chunked(...)`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Chunked.md): Collect values into chunks.
 - [`compacted()`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Compacted.md): Remove nil values from an asynchronous sequence.
+- [`recursiveMap(_:)`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/RecursiveMap.md): Produces a sequence containing the original sequence followed by recursive mapped sequence.
 - [`removeDuplicates()`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/RemoveDuplicates.md): Remove sequentially adjacent duplicate values.
 - [`interspersed(with:)`](https://github.com/apple/swift-async-algorithms/blob/main/Guides/Intersperse.md): Place a value between every two elements of an asynchronous sequence.
 

Sources/AsyncAlgorithms/AsyncRecursiveMapSequence.swift

@@ -0,0 +1,127 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+extension AsyncSequence {
+    /// Returns a sequence containing the original sequence followed by recursive mapped sequence.
+    ///
+    /// ```
+    /// struct Node {
+    ///     var id: Int
+    ///     var children: [Node] = []
+    /// }
+    /// let tree = [
+    ///     Node(id: 1, children: [
+    ///         Node(id: 3),
+    ///         Node(id: 4, children: [
+    ///             Node(id: 6),
+    ///         ]),
+    ///         Node(id: 5),
+    ///     ]),
+    ///     Node(id: 2),
+    /// ]
+    /// for await node in tree.async.recursiveMap({ $0.children.async }) {
+    ///     print(node.id)
+    /// }
+    /// // 1
+    /// // 2
+    /// // 3
+    /// // 4
+    /// // 5
+    /// // 6
+    /// ```
+    ///
+    /// - Parameters:
+    ///   - transform: A closure that map the element to new sequence.
+    /// - Returns: A sequence of the original sequence followed by recursive mapped sequence.
+    @inlinable
+    public func recursiveMap<C>(_ transform: @Sendable @escaping (Element) async -> C) -> AsyncRecursiveMapSequence<Self, C> {
+        return AsyncRecursiveMapSequence(self, transform)
+    }
+}
+
+public struct AsyncRecursiveMapSequence<Base: AsyncSequence, Transformed: AsyncSequence>: AsyncSequence where Base.Element == Transformed.Element {
+
+    public typealias Element = Base.Element
+
+    @usableFromInline
+    let base: Base
+
+    @usableFromInline
+    let transform: @Sendable (Base.Element) async -> Transformed
+
+    @inlinable
+    init(_ base: Base, _ transform: @Sendable @escaping (Base.Element) async -> Transformed) {
+        self.base = base
+        self.transform = transform
+    }
+
+    @inlinable
+    public func makeAsyncIterator() -> AsyncIterator {
+        return AsyncIterator(base, transform)
+    }
+}
+
+extension AsyncRecursiveMapSequence {
+
+    public struct AsyncIterator: AsyncIteratorProtocol {
+
+        @usableFromInline
+        var base: Base.AsyncIterator?
+
+        @usableFromInline
+        var mapped: ArraySlice<Transformed> = []
+
+        @usableFromInline
+        var mapped_iterator: Transformed.AsyncIterator?
+
+        @usableFromInline
+        var transform: @Sendable (Base.Element) async -> Transformed
+
+        @inlinable
+        init(_ base: Base, _ transform: @Sendable @escaping (Base.Element) async -> Transformed) {
+            self.base = base.makeAsyncIterator()
+            self.transform = transform
+        }
+
+        @inlinable
+        public mutating func next() async rethrows -> Base.Element? {
+
+            if self.base != nil {
+
+                if let element = try await self.base?.next() {
+                    await mapped.append(transform(element))
+                    return element
+                }
+
+                self.base = nil
+                self.mapped_iterator = mapped.popFirst()?.makeAsyncIterator()
+            }
+
+            while self.mapped_iterator != nil {
+
+                if let element = try await self.mapped_iterator?.next() {
+                    await mapped.append(transform(element))
+                    return element
+                }
+
+                self.mapped_iterator = mapped.popFirst()?.makeAsyncIterator()
+            }
+
+            return nil
+        }
+    }
+}
+
+extension AsyncRecursiveMapSequence: Sendable
+where Base: Sendable, Base.Element: Sendable, Transformed: Sendable { }
+
+extension AsyncRecursiveMapSequence.AsyncIterator: Sendable
+where Base.AsyncIterator: Sendable, Base.Element: Sendable, Transformed: Sendable, Transformed.AsyncIterator: Sendable { }

Sources/AsyncAlgorithms/AsyncThrowingRecursiveMapSequence.swift

@@ -0,0 +1,127 @@
+//===----------------------------------------------------------------------===//
+//
+// 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
+//
+//===----------------------------------------------------------------------===//
+
+extension AsyncSequence {
+    /// Returns a sequence containing the original sequence followed by recursive mapped sequence.
+    ///
+    /// ```
+    /// struct Node {
+    ///     var id: Int
+    ///     var children: [Node] = []
+    /// }
+    /// let tree = [
+    ///     Node(id: 1, children: [
+    ///         Node(id: 3),
+    ///         Node(id: 4, children: [
+    ///             Node(id: 6),
+    ///         ]),
+    ///         Node(id: 5),
+    ///     ]),
+    ///     Node(id: 2),
+    /// ]
+    /// for await node in tree.async.recursiveMap({ $0.children.async }) {
+    ///     print(node.id)
+    /// }
+    /// // 1
+    /// // 2
+    /// // 3
+    /// // 4
+    /// // 5
+    /// // 6
+    /// ```
+    ///
+    /// - Parameters:
+    ///   - transform: A closure that map the element to new sequence.
+    /// - Returns: A sequence of the original sequence followed by recursive mapped sequence.
+    @inlinable
+    public func recursiveMap<C>(_ transform: @Sendable @escaping (Element) async throws -> C) -> AsyncThrowingRecursiveMapSequence<Self, C> {
+        return AsyncThrowingRecursiveMapSequence(self, transform)
+    }
+}
+
+public struct AsyncThrowingRecursiveMapSequence<Base: AsyncSequence, Transformed: AsyncSequence>: AsyncSequence where Base.Element == Transformed.Element {
+
+    public typealias Element = Base.Element
+
+    @usableFromInline
+    let base: Base
+
+    @usableFromInline
+    let transform: @Sendable (Base.Element) async throws -> Transformed
+
+    @inlinable
+    init(_ base: Base, _ transform: @Sendable @escaping (Base.Element) async throws -> Transformed) {
+        self.base = base
+        self.transform = transform
+    }
+
+    @inlinable
+    public func makeAsyncIterator() -> AsyncIterator {
+        return AsyncIterator(base, transform)
+    }
+}
+
+extension AsyncThrowingRecursiveMapSequence {
+
+    public struct AsyncIterator: AsyncIteratorProtocol {
+
+        @usableFromInline
+        var base: Base.AsyncIterator?
+
+        @usableFromInline
+        var mapped: ArraySlice<Transformed> = []
+
+        @usableFromInline
+        var mapped_iterator: Transformed.AsyncIterator?
+
+        @usableFromInline
+        var transform: @Sendable (Base.Element) async throws -> Transformed
+
+        @inlinable
+        init(_ base: Base, _ transform: @Sendable @escaping (Base.Element) async throws -> Transformed) {
+            self.base = base.makeAsyncIterator()
+            self.transform = transform
+        }
+
+        @inlinable
+        public mutating func next() async throws -> Base.Element? {
+
+            if self.base != nil {
+
+                if let element = try await self.base?.next() {
+                    try await mapped.append(transform(element))
+                    return element
+                }
+
+                self.base = nil
+                self.mapped_iterator = mapped.popFirst()?.makeAsyncIterator()
+            }
+
+            while self.mapped_iterator != nil {
+
+                if let element = try await self.mapped_iterator?.next() {
+                    try await mapped.append(transform(element))
+                    return element
+                }
+
+                self.mapped_iterator = mapped.popFirst()?.makeAsyncIterator()
+            }
+
+            return nil
+        }
+    }
+}
+
+extension AsyncThrowingRecursiveMapSequence: Sendable
+where Base: Sendable, Base.Element: Sendable, Transformed: Sendable { }
+
+extension AsyncThrowingRecursiveMapSequence.AsyncIterator: Sendable
+where Base.AsyncIterator: Sendable, Base.Element: Sendable, Transformed: Sendable, Transformed.AsyncIterator: Sendable { }