asyncSequences: Add Timer AsyncSequence

Author: Thibault Wittemberg

CHANGELOG.md

@@ -1,6 +1,7 @@
 **v0.3.0 - Beryllium:**
 
 - new Share operator
+- new Timer AsyncSequence
 
 **v0.2.1 - Lithium:**
 

README.md

@@ -29,6 +29,7 @@ AsyncSequences
 * [Zip2](#Zip2)
 * [Zip3](#Zip3)
 * [Zip](#Zip)
+* [Timer](#Timer)
 
 ### Async Streams
 * [Passthrough](#Passthrough)
@@ -202,6 +203,28 @@ for try await element in zippedAsyncSequence {
 }
 ```
 
+### Timer
+
+`Timer` is an async sequence that repeatedly emits the current date on the given interval, with the given priority.
+
+```swift
+let timer = AsyncSequences.Timer(priority: .high, every: .seconds(1))
+
+Task {
+    for try await element in timer {
+        print(element)
+    }
+}
+
+// will print:
+// 2022-03-06 19:31:22 +0000
+// 2022-03-06 19:31:23 +0000
+// 2022-03-06 19:31:24 +0000
+// 2022-03-06 19:31:25 +0000
+// 2022-03-06 19:31:26 +0000
+// and will stop once timer.cancel() is called or the parent task is cancelled.
+```
+
 ## Async Streams
 
 ### Passthrough

Sources/AsyncSequences/AsyncSequences+Timer.swift

@@ -0,0 +1,78 @@
+//
+//  AsyncSequences+Timer.swift
+//  
+//
+//  Created by Thibault Wittemberg on 04/03/2022.
+//
+
+import Foundation
+
+public extension AsyncSequences {
+    typealias Timer = AsyncTimerSequence
+}
+
+/// `AsyncTimerSequence`is an async sequence that repeatedly emits the current date on the given interval, with the given priority.
+public class AsyncTimerSequence: AsyncSequence {
+    public typealias Element = Date
+    public typealias AsyncIterator = AsyncThrowingStream<Date, Error>.AsyncIterator
+
+    let priority: TaskPriority?
+    let interval: AsyncSequences.Interval
+    var task: Task<Void, Error>?
+
+    /// Created an async sequence that repeatedly emits the current date on the given interval, with the given priority.
+    ///
+    /// ```
+    /// let timer = AsyncSequences.Timer(priority: .high, every: .seconds(1))
+    ///
+    /// Task {
+    ///     for try await element in timer {
+    ///         print(element)
+    ///     }
+    /// }
+    ///
+    /// // will print:
+    /// // 2022-03-06 19:31:22 +0000
+    /// // 2022-03-06 19:31:23 +0000
+    /// // 2022-03-06 19:31:24 +0000
+    /// // 2022-03-06 19:31:25 +0000
+    /// // 2022-03-06 19:31:26 +0000
+    /// // and will stop once timer.cancel() is called or the parent task is cancelled.
+    /// ```
+    ///
+    /// - Parameters:
+    ///   - priority: The priority of the inderlying Task. Nil by default.
+    ///   - interval: The time interval on which to publish events. For example, a value of `0.5` publishes an event approximately every half-second.
+    /// - Returns: An async sequence that repeatedly emits the current date on the given interval, with the given priority.
+    public init(priority: TaskPriority? = nil, every interval: AsyncSequences.Interval) {
+        self.priority = priority
+        self.interval = interval
+    }
+
+    func makeStream() -> AsyncThrowingStream<Date, Error> {
+        AsyncThrowingStream<Date, Error>(Date.self, bufferingPolicy: .unbounded) { [weak self] continuation in
+            let interval = self?.interval ?? .immediate
+            self?.task = Task(priority: self?.priority) {
+                do {
+                    while !Task.isCancelled {
+                        try await Task.sleep(nanoseconds: interval.value)
+                        continuation.yield(Date())
+                    }
+                } catch is CancellationError {
+                    continuation.finish()
+                } catch {
+                    throw error
+                }
+            }
+        }
+    }
+
+    /// Cancels the timer.
+    public func cancel() {
+        self.task?.cancel()
+    }
+
+    public func makeAsyncIterator() -> AsyncIterator {
+        self.makeStream().makeAsyncIterator()
+    }
+}

Tests/AsyncSequences/AsyncSequences+TimerTests.swift

@@ -0,0 +1,49 @@
+//
+//  AsyncSequences+TimerTests.swift
+//  
+//
+//  Created by Thibault Wittemberg on 06/03/2022.
+//
+
+import AsyncExtensions
+import XCTest
+
+final class AsyncSequences_TimerTests: XCTestCase {
+    func testTimer_finishes_when_task_is_cancelled() {
+        let canCancelExpectation = expectation(description: "the timer can be cancelled")
+        let asyncSequenceHasFinishedExpectation = expectation(description: "The async sequence has finished")
+
+        let sut = AsyncSequences.Timer(priority: .userInitiated, every: .milliSeconds(100))
+
+        let task = Task {
+            var index = 1
+            for try await _ in sut {
+                if index == 10 {
+                    canCancelExpectation.fulfill()
+                }
+                index += 1
+            }
+            asyncSequenceHasFinishedExpectation.fulfill()
+        }
+
+        wait(for: [canCancelExpectation], timeout: 5)
+
+        task.cancel()
+
+        wait(for: [asyncSequenceHasFinishedExpectation], timeout: 5)
+    }
+
+    func testTimer_finishes_when_cancel_is_called() async throws {
+        let sut = AsyncSequences.Timer(priority: .userInitiated, every: .milliSeconds(100))
+
+        var index = 1
+        for try await _ in sut {
+            if index == 10 {
+                sut.cancel()
+            }
+            index += 1
+        }
+
+        XCTAssertEqual(index, 11)
+    }
+}