Add ThrottledProgressAnimation to avoid too frequent animation updates

Too frequent updates to the progress animation can cause flickering and
can prevent kernel from reflecting the terminal size change on `ioctl`.

Author: kateinoigakukun

Sources/TSCUtility/ProgressAnimation.swift

@@ -300,3 +300,56 @@ public class DynamicProgressAnimation: ProgressAnimationProtocol {
         animation.clear()
     }
 }
+
+/// A progress animation wrapper that throttles updates to a given interval.
+@available(macOS 13.0, iOS 16.0, watchOS 9.0, tvOS 16.0, *)
+public class ThrottledProgressAnimation: ProgressAnimationProtocol {
+    private let animation: ProgressAnimationProtocol
+    private let shouldUpdate: () -> Bool
+    private var pendingUpdate: (Int, Int, String)?
+
+    public convenience init(_ animation: ProgressAnimationProtocol, interval: ContinuousClock.Duration) {
+        self.init(animation, clock: ContinuousClock(), interval: interval)
+    }
+
+    public convenience init<C: Clock>(_ animation: ProgressAnimationProtocol, clock: C, interval: C.Duration) {
+        self.init(animation, now: { clock.now }, interval: interval, clock: C.self)
+    }
+
+    init<C: Clock>(
+      _ animation: ProgressAnimationProtocol,
+      now: @escaping () -> C.Instant, interval: C.Duration, clock: C.Type = C.self
+    ) {
+        self.animation = animation
+        var lastUpdate: C.Instant?
+        self.shouldUpdate = {
+            let now = now()
+            if let lastUpdate = lastUpdate, now < lastUpdate.advanced(by: interval) {
+                return false
+            }
+            // If we're over the interval or it's the first update, should update.
+            lastUpdate = now
+            return true
+        }
+    }
+
+    public func update(step: Int, total: Int, text: String) {
+        guard shouldUpdate() else {
+            pendingUpdate = (step, total, text)
+            return
+        }
+        pendingUpdate = nil
+        animation.update(step: step, total: total, text: text)
+    }
+
+    public func complete(success: Bool) {
+        if let (step, total, text) = pendingUpdate {
+            animation.update(step: step, total: total, text: text)
+        }
+        animation.complete(success: success)
+    }
+
+    public func clear() {
+        animation.clear()
+    }
+}

Tests/TSCUtilityTests/ProgressAnimationTests.swift

@@ -9,7 +9,7 @@
 */
 
 import XCTest
-import TSCUtility
+@testable import TSCUtility
 import TSCLibc
 import TSCTestSupport
 import TSCBasic
@@ -62,6 +62,61 @@ final class ProgressAnimationTests: XCTestCase {
         XCTAssertEqual(outStream.bytes.validDescription, "")
     }
 
+    class TrackingProgressAnimation: ProgressAnimationProtocol {
+        var steps: [Int] = []
+
+        func update(step: Int, total: Int, text: String) {
+            steps.append(step)
+        }
+
+        func complete(success: Bool) {}
+        func clear() {}
+    }
+
+    func testThrottledPercentProgressAnimation() {
+        do {
+            let tracking = TrackingProgressAnimation()
+            var now = ContinuousClock().now
+            let animation = ThrottledProgressAnimation(
+              tracking, now: { now }, interval: .milliseconds(100),
+              clock: ContinuousClock.self
+            )
+
+            // Update the animation 10 times with a 50ms interval.
+            let total = 10
+            for i in 0...total {
+                animation.update(step: i, total: total, text: "")
+                now += .milliseconds(50)
+            }
+            animation.complete(success: true)
+            XCTAssertEqual(tracking.steps, [0, 2, 4, 6, 8, 10])
+        }
+
+        do {
+            // Check that the last animation update is sent even if
+            // the interval has not passed.
+            let tracking = TrackingProgressAnimation()
+            var now = ContinuousClock().now
+            let animation = ThrottledProgressAnimation(
+              tracking, now: { now }, interval: .milliseconds(100),
+              clock: ContinuousClock.self
+            )
+
+            // Update the animation 10 times with a 50ms interval.
+            let total = 10
+            for i in 0...total-1 {
+                animation.update(step: i, total: total, text: "")
+                now += .milliseconds(50)
+            }
+            // The next update is at 1000ms, but we are at 950ms,
+            // so "step 9" is not sent yet.
+            XCTAssertEqual(tracking.steps, [0, 2, 4, 6, 8])
+            // After explicit "completion", the last step is flushed out.
+            animation.complete(success: true)
+            XCTAssertEqual(tracking.steps, [0, 2, 4, 6, 8, 9])
+        }
+    }
+
   #if !os(Windows) // PseudoTerminal is not supported in Windows
     func testPercentProgressAnimationTTY() throws {
         let output = try readingTTY { tty in