add throttler

Author: codingiran

README.md

@@ -1,28 +1,27 @@
 # AsyncTimer
 
-[![Swift](https://img.shields.io/badge/Swift-5.9%2B-orange.svg)](https://swift.org)
+[![Swift](https://img.shields.io/badge/Swift-5.10%2B-orange.svg)](https://swift.org)
 [![Platforms](https://img.shields.io/badge/Platforms-iOS%20|%20macOS%20|%20tvOS%20|%20watchOS%20|%20visionOS-blue.svg)](https://developer.apple.com)
 [![Swift Package Manager](https://img.shields.io/badge/Swift_Package_Manager-compatible-brightgreen.svg)](https://swift.org/package-manager)
 [![License](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-A lightweight, modern Swift async/await timer implementation for Apple platforms. AsyncTimer provides a clean, actor-based API for scheduling one-time and repeating tasks with precise control over timing, priorities, and cancellation.
+A lightweight, modern Swift async/await timer/debounce/throttle implementation for Apple platforms.
 
 ## Features
 
 - ✅ **Swift Concurrency** - Built with Swift's modern concurrency model using async/await and actors
-- ✅ **Flexible Timing** - Support for one-time and repeating timers with configurable intervals
-- ✅ **Task Priorities** - Set execution priorities for your timer tasks
-- ✅ **Immediate Firing Option** - Configure timers to fire immediately or after the first interval
-- ✅ **Cancellation Support** - Clean cancellation with optional cancellation handlers
-- ✅ **Dynamic Interval Adjustment** - Change timer intervals on-the-fly
 - ✅ **Thread Safety** - Actor-based design ensures thread-safe operation
 - ✅ **Lightweight** - Zero dependencies, minimal footprint
+- ✅ **Timer Utilities** - Built-in `AsyncTimer` with support for one-time and repeating timers with configurable intervals
+- ✅ **Debounce Utilities** - Built-in `AsyncDebouncer` with configurable debounce time
+- ✅ **Throttle Utilities** - Built-in `AsyncThrottler` with leading/trailing and drift/anti-drift cadence
 
 ## Requirements
 
-- Swift 5.9+ / Swift 6.0
+- Swift 5.10+ / Swift 6.0
 - iOS 13.0+
 - macOS 10.15+
+- macCatalyst 13.0+
 - tvOS 13.0+
 - watchOS 6.0+
 - visionOS 1.0+
@@ -35,7 +34,7 @@ Add AsyncTimer to your project using Swift Package Manager by adding it to your
 
 ```swift
 dependencies: [
-    .package(url: "https://github.com/codingiran/AsyncTimer.git", from: "0.0.3")
+    .package(url: "https://github.com/codingiran/AsyncTimer.git", from: "0.0.7")
 ]
 ```
 
@@ -45,228 +44,50 @@ Or add it directly in Xcode:
 2. Enter the repository URL: `https://github.com/codingiran/AsyncTimer.git`
 3. Select the version or branch you want to use
 
-## Usage
+## Usage (Quick Start)
 
-### Basic Examples
-
-#### One-time Timer
+### AsyncTimer
 
 ```swift
 import AsyncTimer
 
-func example() async {
-    let timer = AsyncTimer(
-        interval: 1.0,  // 1 second
-        repeating: false,
-        handler: {
-            print("Timer fired once!")
-        }
-    )
-    
-    await timer.start()
-    // Timer will fire after 1 second and then stop automatically
+// One-time
+let once = AsyncTimer(interval: .seconds(1), repeating: false) {
+    print("fire once")
 }
-```
+await once.start()
 
-#### Repeating Timer
-
-```swift
-import AsyncTimer
-
-func example() async {
-    let timer = AsyncTimer(
-        interval: 0.5,  // 0.5 seconds
-        repeating: true,
-        handler: {
-            print("Timer fired repeatedly!")
-        }
-    )
-    
-    await timer.start()
-    
-    // Let the timer run for 3 seconds
-    try? await Task.sleep(for: .seconds(3))
-    
-    // Stop the timer
-    await timer.stop()
+// Repeating (fire immediately on start)
+let repeating = AsyncTimer(interval: .seconds(0.5), repeating: true, firesImmediately: true) {
+    print("tick")
 }
+await repeating.start()
+// ... later
+await repeating.stop()
 ```
 
-#### Using Cancellation Handler
+### AsyncThrottler
 
 ```swift
 import AsyncTimer
 
-func example() async {
-    let timer = AsyncTimer(
-        interval: 1.0,
-        repeating: true,
-        handler: {
-            print("Timer fired!")
-        },
-        cancelHandler: {
-            print("Timer was cancelled!")
-        }
-    )
-    
-    await timer.start()
-    
-    // Later, when you want to stop the timer
-    await timer.stop()  // This will trigger the cancelHandler
-}
-```
-
-#### Changing Timer Interval
-
-```swift
-import AsyncTimer
-
-func example() async {
-    let timer = AsyncTimer(
-        interval: 1.0,
-        repeating: true,
-        handler: {
-            print("Timer fired!")
-        }
-    )
-    
-    await timer.start()
-    
-    // Run at 1-second intervals for a while
-    try? await Task.sleep(for: .seconds(3))
-    
-    // Change to 0.5-second intervals
-    await timer.setInterval(0.5)
-    
-    // Run at new interval for a while
-    try? await Task.sleep(for: .seconds(3))
-    
-    // Stop the timer
-    await timer.stop()
-}
-```
-
-#### Setting Task Priority
-
-```swift
-import AsyncTimer
-
-func example() async {
-    let highPriorityTimer = AsyncTimer(
-        interval: 1.0,
-        priority: .high,
-        repeating: true,
-        handler: {
-            print("High priority timer fired!")
-        }
-    )
-    
-    let lowPriorityTimer = AsyncTimer(
-        interval: 1.0,
-        priority: .low,
-        repeating: true,
-        handler: {
-            print("Low priority timer fired!")
-        }
-    )
-    
-    await highPriorityTimer.start()
-    await lowPriorityTimer.start()
-    
-    // High priority timer will generally execute before low priority timer
-}
-```
-
-## API Reference
-
-### AsyncTimer
-
-```swift
-public final actor AsyncTimer
-```
-
-A simple repeating timer that runs a task at a specified interval.
-
-#### Initialization
-
-```swift
-public init(
-    interval: TimeInterval,
-    priority: TaskPriority = .medium,
-    repeating: Bool = false,
-    firesImmediately: Bool = true,
-    handler: @escaping RepeatHandler,
-    cancelHandler: CancelHandler? = nil
+let throttler = AsyncThrottler(
+    throttleTime: .seconds(0.2),
+    behavior: .trailingOnly, // .leadingOnly / .leadingAndTrailing
+    cadence: .antiDrift      // .drift for rolling windows
 )
-```
-
-- **interval**: The interval at which the timer fires (in seconds)
-- **priority**: The priority of the task (default: `.medium`)
-- **repeating**: Whether the timer should repeat (default: `false`)
-- **firesImmediately**: Whether the timer should fire immediately upon starting (default: `true`, only effective when `repeating` is `true`)
-- **handler**: The handler that is called when the timer fires
-- **cancelHandler**: The handler that is called when the timer is cancelled (optional)
-
-#### Properties
 
-```swift
-public var isRunning: Bool
-```
-
-Whether the timer is currently running.
-
-#### Methods
-
-```swift
-public func start()
-```
-
-Starts the timer. If the timer is already running, it will be stopped and restarted.
-
-```swift
-public func stop()
-```
-
-Stops the timer.
-
-```swift
-public func restart()
+// High-frequency calls → at most one execution per window
+await throttler.call { print("work") }
 ```
 
-Restarts the timer (equivalent to calling `stop()` followed by `start()`).
+### AsyncDebouncer
 
 ```swift
-public func setInterval(_ newInterval: TimeInterval)
-```
-
-Modifies the interval of the timer. This will also restart the timer if it's currently running.
-
-```swift
-public static func sleep(_ interval: TimeInterval) async throws
-```
-
-Utility method to sleep for the specified interval.
-
-## Advanced Usage
-
-### Handling Concurrency
-
-Since `AsyncTimer` is implemented as an actor, all its methods are automatically thread-safe. You can safely call methods from different tasks without worrying about race conditions.
-
-```swift
-let timer = AsyncTimer(interval: 1.0, repeating: true) {
-    print("Timer fired!")
-}
-
-// These can be called from different tasks safely
-Task {
-    await timer.start()
-}
+import AsyncTimer
 
-Task {
-    try await Task.sleep(for: .seconds(5))
-    await timer.stop()
-}
+let debouncer = AsyncDebouncer(debounceTime: .seconds(0.2))
+await debouncer.call { print("fire after quiet period") }
 ```
 
 ## Contributing
@@ -275,4 +96,4 @@ Contributions are welcome! If you find a bug or have a feature request, please o
 
 ## License
 
-AsyncTimer is available under the MIT license. See the LICENSE file for more info.
+AsyncTimer is available under the MIT license. See the LICENSE file for more info.