#113 Define the first element of throttled sequences by not exceeding the rate (and fix a expectation misalignment of events) (#133)

* #113 Define the first element of throttled sequences by not exceeding the rate (and fix a expectation misalignment of events)

* Update guide for throttle referencing the first element and duration measurement

Author: phausler

Guides/Throttle.md

@@ -77,6 +77,8 @@ extension AsyncThrottleSequence.Iterator: Sendable
 
 The `AsyncThrottleSequence` and its `Iterator` are conditionally `Sendable` if the base types comprising it are `Sendable`.
 
+The time in which events are measured are from the previous emission if present. If a duration has elapsed between the last emission and the point in time the throttle is measured then that duration is counted as elapsed. The first element is considered not throttled because no interval can be constructed from the start to the first element.
+
 ## Alternatives Considered
 
 It was considered to only provide the "latest" style APIs, however the reduction version grants more flexibility and can act as a funnel to the implementations of `latest`.

Sources/AsyncAlgorithms/AsyncThrottleSequence.swift

@@ -64,6 +64,7 @@ extension AsyncThrottleSequence: AsyncSequence {
   /// The iterator for an `AsyncThrottleSequence` instance.
   public struct Iterator: AsyncIteratorProtocol {
     var base: Base.AsyncIterator
+    var last: C.Instant?
     let interval: C.Instant.Duration
     let clock: C
     let reducing: @Sendable (Reduced?, Base.Element) async -> Reduced
@@ -77,13 +78,15 @@ extension AsyncThrottleSequence: AsyncSequence {
 
     public mutating func next() async rethrows -> Reduced? {
       var reduced: Reduced?
-      let start = clock.now
+      let start = last ?? clock.now
       repeat {
         guard let element = try await base.next() else {
           return nil
         }
         let reduction = await reducing(reduced, element)
-        if start.duration(to: clock.now) >= interval {
+        let now = clock.now
+        if start.duration(to: now) >= interval || last == nil {
+          last = now
           return reduction
         } else {
           reduced = reduction

Sources/AsyncSequenceValidation/Expectation.swift

@@ -42,7 +42,7 @@ extension AsyncSequenceValidationDiagram {
     }
 
     func reconstitute<Theme: AsyncSequenceValidationTheme>(_ events: [Clock.Instant : [Result<String?, Error>]], theme: Theme, end: Clock.Instant) -> String {
-      var now = Clock.Instant(when: .zero)
+      var now = Clock.Instant(when: .steps(1)) // adjust for the offset index
       var reconstituted = ""
       while now <= end {
         if let results = events[now] {

Tests/AsyncAlgorithmsTests/TestThrottle.swift

@@ -49,47 +49,47 @@ final class TestThrottle: XCTestCase {
     validate {
       "abcdefghijk|"
       $0.inputs[0].throttle(for: .steps(2), clock: $0.clock)
-      "-b-d-f-h-j-|"
+      "a-c-e-g-i-k|"
     }
   }
 
   func test_rate_2_leading_edge() {
     validate {
       "abcdefghijk|"
       $0.inputs[0].throttle(for: .steps(2), clock: $0.clock, latest: false)
-      "-a-c-e-g-i-|"
+      "a-b-d-f-h-j|"
     }
   }
 
   func test_rate_3() {
     validate {
       "abcdefghijk|"
       $0.inputs[0].throttle(for: .steps(3), clock: $0.clock)
-      "--c--f--i--|"
+      "a--d--g--j-|"
     }
   }
 
   func test_rate_3_leading_edge() {
     validate {
       "abcdefghijk|"
       $0.inputs[0].throttle(for: .steps(3), clock: $0.clock, latest: false)
-      "--a--d--g--|"
+      "a--b--e--h-|"
     }
   }
 
   func test_throwing() {
     validate {
       "abcdef^hijk|"
       $0.inputs[0].throttle(for: .steps(2), clock: $0.clock)
-      "-b-d-f^"
+      "a-c-e-^"
     }
   }
 
   func test_throwing_leading_edge() {
     validate {
       "abcdef^hijk|"
       $0.inputs[0].throttle(for: .steps(2), clock: $0.clock, latest: false)
-      "-a-c-e^"
+      "a-b-d-^"
     }
   }
 
@@ -121,7 +121,7 @@ final class TestThrottle: XCTestCase {
     validate {
       "-a-b-c-d-e-f-g-h-i-j-k-|"
       $0.inputs[0].throttle(for: .steps(3), clock: $0.clock)
-      "---b---d---f---h---j---|"
+      "-a---c---e---g---i---k-|"
     }
   }
 }