project: implement Debounce and Throttle + SwiftUI helpers

Author: twittemb

CHANGELOG.md

@@ -0,0 +1,5 @@
+**v0.1.0:**
+
+- Debouncer
+- Throttler
+- SwiftUI helpers for buttons and bindings

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 AsyncCommunity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,12 +1,49 @@
 # Regulate
 
-**Regulate** is a lightweight library that brings the following time-based regulation operations for things that can emit values over times (and are not from reactive programming or `AsyncSequence`).
+**Regulate** is a lightweight library that brings the following time-based regulation operations for things that can emit values over times (and are not using reactive programming or `AsyncSequence`).
 
-- debounce:
-- throttle:
+- [Debounce](./Sources/Debouncer.swift) (Outputs elements only after a specified time interval elapses between events)
+- [Throttle](./Sources/Throttler.swift) (Outputs either the most-recent or first element pushed by a producer in the specified time interval)
 
 **Regulate** is entirely backed by Swift concurrency and limits the number of created `Tasks` to the minimum.
 
+**Regulate** also provides SwiftUI helpers to regulate buttons and bindings out of the box.
+You can give a look at the [Sample app](./Sample).
+
+For a Button, it is as simple as:
+
+```swift
+Button {
+  print("I've been hit (throttled)!")
+} label: {
+  Text("Hit me")
+}
+.throttle(dueTime: .seconds(1))
+```
+
+For a Binding, there is a tiny bit of extra work:
+
+```swift
+@State private var text = ""
+@StateObject private var debouncer = Debouncer<String>(dueTime: .seconds(1))
+...
+TextField(
+  text: self
+    .$text
+    .perform(regulator: debouncer) { text in
+      print("regulated text \(text)") // you can perform any side effect here!
+    }
+) {
+  Text("prompt")
+}
+```
+
+## Demo
+
+<kbd>
+<img style="border:2px solid black" alt="Demo Application" src="https://raw.githubusercontent.com/sideeffect-io/Regulate/main/Regulate.gif"/>
+</kbd>
+
 ## Adding Regulate as a Dependency
 
 To use the `Regulate` library in a SwiftPM project,