Added a paged sequence.

Sources/ASConnectService/Catalogs/ASConnectService.docc/Library.md

@@ -48,19 +48,22 @@ The `ok` property throws for any other response. To handle those, switch over th
 
 ### Fetching More Pages
 
-Lists are paged. Pass a page's ``Components/Schemas/PagedDocumentLinks/nextCursor`` as the `cursor` of the next request:
+Lists are paged. Iterate a ``PagedSequence`` to fetch each page in turn:
 
 ```swift
-var apps: [Components.Schemas.App] = []
-var cursor: String?
+let pages = PagedSequence(links: \.links) { cursor in
+    try await client.appsGetCollection(query: .init(limit: 200, cursor: cursor)).ok.body.json
+}
 
-repeat {
-    let page = try await client.appsGetCollection(query: .init(limit: 200, cursor: cursor)).ok.body.json
+var apps: [Components.Schemas.App] = []
+
+for try await page in pages {
     apps += page.data
-    cursor = page.links.nextCursor
-} while cursor != nil
+}
 ```
 
+To fetch pages yourself, pass a page's ``Components/Schemas/PagedDocumentLinks/nextCursor`` as the `cursor` of the next request.
+
 ### Handling Rate Limits
 
 Add ``RateLimitMiddleware`` before the authentication middleware to retry `429 Too Many Requests` responses:
@@ -84,6 +87,10 @@ middlewares: [
 - ``BearerAuthMiddleware``
 - ``APIKeyTokenProvider``
 
+### Pagination
+
+- ``PagedSequence``
+
 ### Rate Limiting
 
 - ``RateLimitMiddleware``

Sources/ASConnectService/Sources/Public/Sequences/PagedSequence.swift

@@ -0,0 +1,117 @@
+// ===----------------------------------------------------------------------===
+//
+// This source file is part of the ASConnectService open source project
+//
+// Copyright (c) 2026 Röck+Cöde VoF. and the ASConnectService project authors
+// Licensed under Apache license v2.0
+//
+// See LICENSE for license information
+// See CONTRIBUTORS for the list of ASConnectService project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+// ===----------------------------------------------------------------------===
+
+/// An asynchronous sequence of the pages of a paged operation.
+///
+/// Each iteration fetches the next page, until a page has no next link:
+///
+/// ```swift
+/// let pages = PagedSequence(links: \.links) { cursor in
+///     try await client.appsGetCollection(query: .init(limit: 200, cursor: cursor)).ok.body.json
+/// }
+///
+/// var apps: [Components.Schemas.App] = []
+///
+/// for try await page in pages {
+///     apps += page.data
+/// }
+/// ```
+public struct PagedSequence<Page: Sendable>: AsyncSequence, Sendable {
+    // MARK: Type aliases
+
+    public typealias Element = Page
+
+    // MARK: Properties
+
+    /// The closure that returns the links of a page.
+    private let links: @Sendable (Page) -> Components.Schemas.PagedDocumentLinks
+
+    /// The closure that fetches the page at a cursor.
+    private let fetch: @Sendable (String?) async throws -> Page
+
+    // MARK: Initializers
+
+    /// Creates a sequence of the pages of a paged operation.
+    /// - Parameters:
+    ///   - links: A closure that returns the links of a page.
+    ///   - fetch: A closure that fetches the page at a cursor, or the first page if the cursor is `nil`.
+    public init(
+        links: @escaping @Sendable (Page) -> Components.Schemas.PagedDocumentLinks,
+        fetch: @escaping @Sendable (_ cursor: String?) async throws -> Page
+    ) {
+        self.links = links
+        self.fetch = fetch
+    }
+
+    // MARK: Functions
+
+    public func makeAsyncIterator() -> Iterator {
+        Iterator(
+            links: links,
+            fetch: fetch
+        )
+    }
+}
+
+// MARK: - Iterator
+
+extension PagedSequence {
+    /// An iterator that fetches one page at a time.
+    public struct Iterator: AsyncIteratorProtocol {
+        // MARK: Properties
+
+        /// The closure that returns the links of a page.
+        private let links: @Sendable (Page) -> Components.Schemas.PagedDocumentLinks
+
+        /// The closure that fetches the page at a cursor.
+        private let fetch: @Sendable (String?) async throws -> Page
+
+        /// The cursor of the next page, or `nil` for the first page.
+        private var cursor: String?
+
+        /// A Boolean value that indicates whether there are no more pages to fetch.
+        private var isFinished = false
+
+        // MARK: Initializers
+
+        init(
+            links: @escaping @Sendable (Page) -> Components.Schemas.PagedDocumentLinks,
+            fetch: @escaping @Sendable (String?) async throws -> Page
+        ) {
+            self.links = links
+            self.fetch = fetch
+        }
+
+        // MARK: Functions
+
+        /// Fetches the next page.
+        /// - Returns: The next page, or `nil` after the last page.
+        /// - Throws: The error thrown by the fetch closure, after which the iterator returns `nil`.
+        public mutating func next() async throws -> Page? {
+            guard !isFinished else {
+                return nil
+            }
+
+            // Finishes the iteration if fetching the page throws.
+            isFinished = true
+
+            let page = try await fetch(cursor)
+
+            cursor = links(page).nextCursor
+            isFinished = cursor == nil
+
+            return page
+        }
+    }
+}