Ratelimiter (#181)

* feat(ratelimiter): add token bucket rate limiter

Introduce a thread-safe token bucket rate limiter with dynamic capacity
and refill rate adjustment. Includes comprehensive tests and usage
examples. Provides both blocking and non-blocking methods, context
support, and runtime configuration.

* feat(ratelimiter): add token bucket rate limiter

Introduce a thread-safe token bucket rate limiter with dynamic capacity
and refill rate adjustment. Includes comprehensive tests and usage
examples. Provides both blocking and non-blocking methods, context
support, and runtime configuration.

* Delete .DS_Store

Signed-off-by: Dimitrios Kyriakidis Kortsekidis <kwstasnere@gmail.com>

* fix(ratelimiter): improve token precision and WaitN accuracy

Refactored TokenBucket to use float64 for tokens, allowing fractional
token accumulation and more precise rate limiting. Updated refill and
token consumption logic to prevent rounding errors. Enhanced WaitN to
avoid busy-waiting and improve responsiveness to context cancellation.
Adjusted tests for timing accuracy with new token handling.

* fix(ratelimiter): avoid race on capacity check in WaitN

Previously, the capacity check in WaitN accessed t.capacity without
locking, which could lead to a race condition if the capacity was
changed concurrently. This change ensures the capacity is read under
lock before comparing with the requested token count, improving
thread safety.

* feat(ratelimiter): improve precision, fix races, enhance docs

- Move unexported methods to helper.go for better organization
- Add comprehensive documentation for all exported functions
- Improve code readability with better formatting
- Add expected output to all examples in EXAMPLES.md

* Update README.md

* fix(ratelimiter): add capacity validation to nextAvailableDuration

- Return -1 for impossible requests exceeding capacity
- Handle -1 return value in WaitN with proper error message
- Fix mutex ordering to prevent race conditions

* fix(ratelimiter): improve token bucket validation logic

Refactored token bucket methods to better handle invalid input and edge
cases. Removed unnecessary mutex usage in nextAvailableDuration and added
checks for negative refill rates. Cleaned up code formatting and comments
for clarity.

* Update README.md

Signed-off-by: Dimitrios Kyriakidis Kortsekidis <kwstasnere@gmail.com>

* Update ratelimiter/ratelimiter.go

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Signed-off-by: Dimitrios Kyriakidis Kortsekidis <kwstasnere@gmail.com>

* Fix typo

* Delete dbutils directory / Uploaded by mistake

Signed-off-by: Dimitrios Kyriakidis Kortsekidis <kwstasnere@gmail.com>

* Refactor suggestions by coderabbitai

* Add more tests

* Update ratelimiter/ratelimiter.go

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Signed-off-by: Kashif Khan <70996046+kashifkhan0771@users.noreply.github.com>

* Update README.md

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Signed-off-by: Kashif Khan <70996046+kashifkhan0771@users.noreply.github.com>

* formatted

* updated gitignore

* updated gitignore

* Fix lint issues

---------

Signed-off-by: Dimitrios Kyriakidis Kortsekidis <kwstasnere@gmail.com>
Signed-off-by: Kashif Khan <70996046+kashifkhan0771@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>
Co-authored-by: Kashif Khan <70996046+kashifkhan0771@users.noreply.github.com>
Co-authored-by: kashif khan <kashif.khan@trufflesec.com>

Author: 3 people

.gitignore

@@ -1,2 +1,3 @@
 .idea
 .vscode
+.DS_Store

README.md

@@ -68,6 +68,7 @@ cd utils
 | **timeutils** | Time and date manipulation utilities               | [README](time/README.md)      | [EXAMPLES](time/EXAMPLES.md)      |
 | **url**       | URL parsing and manipulation utilities             | [README](url/README.md)       | [EXAMPLES](url/EXAMPLES.md)       |
 | **conversion** | Conversion of data types, time, and temperatues   | [README](conversion/README.md) | [EXAMPLES](conversion/EXAMPLES.md)
+| **ratelimiter** | Token-bucket rate limiter (allow/wait, adjustable capacity & refill rate) | [README](ratelimiter/README.md) | [EXAMPLES](ratelimiter/EXAMPLES.md) |
 
 ## Comparison
 
@@ -96,6 +97,7 @@ cd utils
 | URL Utilities             | ✅ Yes                      | ❌ No                            | ✅ Yes                           |
 | Dependency-Free           | ✅ Yes                      | ❌ No                            | ❌ No                            |
 | Small API Surface         | ✅ Yes                      | ❌ No                            | ✅ Yes                           |
+| Rate Limiter Utilities         | ✅ Yes                      | ❌ No                            | ❌ No                           |
 
 
 ## Contributions