feat: read time via package:clock, fix flush() leaving a timer armed

[xsahil03x]

What

Debounce read the wall clock directly via DateTime.now(), so its timing behaviour couldn't be controlled from a test. It now reads through package:clock — three call sites in lib/src/debounce.dart. Throttle delegates to Debounce and benefits for free; BackOff uses Future.delayed and needs no change.

clock alone only makes the time source mockable — Timer is still real. The payoff is fakeAsync, which installs both a fake Timer queue and a clock that advances with elapse(). The whole debounce/throttle suite now runs on it.

Public API is unchanged — the diff under lib/ is three time reads and one Timer.cancel().

Bug fix: flush() left its timer armed

_trailingEdge detached the timer without cancelling it. Reached through flush() — where the timer is still armed — the orphan fired later, found nothing to invoke, and rescheduled itself. Measured before the fix:

after flush: callCount=1 isPending=false
t+23ms     : callCount=1 isPending=true     ← spuriously pending again
t+223ms    : callCount=1 isPending=false

No double invocation, but isPending returned the wrong answer — and it's the getter the docs point users at (debounced.isPending ? "Pending..." : "Ready"). One line in _trailingEdge, with regression tests in both suites that fail without it.

This has been shipping since 0.1.0. It was only findable once the suite moved to a fake clock; under real time the test always finished before the orphan fired.

Versioning: 1.1.0

clock 1.1.2 declares sdk: ^3.4.0, so rate_limiter matches. That is not breaking in pub's terms — consumers on an older SDK resolve to 1.0.0 and keep building. package:clock itself made the same >=2.12.0 <3.0.0 → ^3.4.0 move in a patch release (1.1.1 → 1.1.2).

Pinning clock below 1.1.2 to hold the old floor was considered and rejected: it needs an upper bound like >=1.1.0 <1.1.2, which causes resolution conflicts for any consumer that also depends on something wanting clock ^1.1.2.

Test suite now runs on a fake clock

Every delay() became elapse; the two busy-wait loops became elapseBlocking, which advances the clock without running timers — what a synchronous tight loop does to a real program. ~0.7s instead of ~3s, with no dependence on machine speed.

Reviewing them against a now-knowable clock turned up assertions verifying less than they appeared to:

• Both cancel tests asserted callCount == 0 at 30ms — before the 32ms trailing call was ever due. They passed whether or not cancel() did anything. They now elapse past the deadline.
• isNot('b') / isNotNull checks only ruled out one wrong answer; they now assert the right one.
• Throttle counts were compared against a snapshot variable rather than stated outright.

Counts that encode loop iterations rather than documented behaviour are deliberately left as greaterThan(1).

Coverage

Check Code Coverage has failed on master since 4e1e2b0 (BackOff) added BackOffExtension.backOff() with no test:

commit	coverage
4e1e2b0~1 (before BackOff)	78/78 = 100%
master	96/99 = 96.97% (CI reported 94.95%)
this branch	100/100 = 100%

Verified line-by-line, not just by total, across the fakeAsync port — no line silently traded for another.

CI

The old workflow pinned flutter-action@v1.4.0 → Flutter 2.2.1 → Dart 2.13, which cannot resolve sdk: ^3.4.0. Rebuilt on the very_good_workflows build layout, adapted:

• dart-lang/setup-dart instead of flutter-action — pure Dart package; Flutter was only ever a vehicle for its bundled Dart SDK.
• An SDK matrix (3.4.0, stable). It earned its keep immediately: it caught the maxWait tight-loop branch uncovered on 3.4.0 but not stable, reachable only via a wall-clock test. That finding is what motivated the suite port.
• Coverage measured once in its own job (needs: build), matching dart-lang/coverage's layout.
• Kept format_coverage over the test_with_coverage one-liner pub.dev recommends: it has no --base-directory, and Codecov can only map files when lcov paths are repo-relative.
• very_good_coverage gate at 97, permissions: contents: read preserved from CI: add least-privilege permissions to GitHub Actions workflows #7.

New: pub_publish.yaml

Ported from super_paging, adapted: no flutter-action, dart pub get, and least-privilege permissions with id-token: write scoped to the publish job. The tag filter is v[0-9]+.[0-9]+.[0-9]+* to match what pub.dev is configured with — note releases through 1.0.0 were tagged without the v prefix, so the next tag needs to be v1.1.0.

⚠️ This goes live on merge. The next matching tag push publishes to pub.dev with --force (no confirmation). It requires automated publishing to be enabled for the package on pub.dev first; until then the job fails at the publish step.

Verification

All checks green. Locally: dart format --set-exit-if-changed ., dart analyze --fatal-infos ., 39 tests under randomized ordering, coverage 100%, dart pub publish --dry-run clean, and example/ resolves and analyzes against the new SDK floor.

Mutation checks — reverting clock.now() → DateTime.now() fails 19 tests (3 before the port); removing the _trailingEdge cancel fails both new flush tests.

Known and accepted

• clock.now() does a Zone lookup per call, now on Debounce.call()'s hot path.
• Coverage is line-only; branch coverage is not measured.
• CI format/analyze scope is lib, so test/ is not lint-gated. Passing . instead would gate it — an improvement rather than a restoration, since the old whole-repo check ran under a Dart 2.13 analyzer.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 100.00%. Comparing base (f6c1b6b) to head (9b48e6b).
⚠️ Report is 6 commits behind head on master.

Additional details and impacted files

@@             Coverage Diff             @@
##           master        #8      +/-   ##
===========================================
+ Coverage   97.43%   100.00%   +2.56%     
===========================================
  Files           3         4       +1     
  Lines          78       100      +22     
===========================================
+ Hits           76       100      +24     
+ Misses          2         0       -2     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.