docs: add throttle utility to documentation across all platforms

Author: Ivanmw97

README.md

@@ -61,6 +61,7 @@ KompKit provides essential utility functions that work seamlessly across Web (Ty
 - **📧 isEmail** - Validate email addresses with robust regex patterns
 - **💰 formatCurrency** - Format numbers as currency with full locale support
 - **📐 clamp** - Constrain a number within an inclusive [min, max] range
+- **⏱️ throttle** - Limit a function to execute at most once per wait period
 
 ### Key Features
 

docs/ARCHITECTURE.md

@@ -46,14 +46,15 @@ All modules implement identical functionality:
 - **isEmail**: Email validation using regex patterns
 - **formatCurrency**: Localized currency formatting
 - **clamp**: Constrain a number within an inclusive [min, max] range
+- **throttle**: Limit function execution to at most once per wait period
 
 ## API Parity Contract
 
 This section defines the formal contract for cross-platform API consistency in KompKit.
 
 ### What is Guaranteed
 
-- **Function names** are identical across all platforms (`debounce`, `isEmail`, `formatCurrency`, `clamp`).
+- **Function names** are identical across all platforms (`debounce`, `isEmail`, `formatCurrency`, `clamp`, `throttle`).
 - **Behavioral semantics** are identical: given the same inputs, all platforms produce the same observable output.
 - **Default values** are identical: `wait = 250ms`, `currency = "USD"`, `locale = "en-US"`.
 - **Error handling philosophy** is consistent: invalid inputs that cannot produce a meaningful result throw/throw-equivalent errors. Silent fallbacks are not permitted.
@@ -75,6 +76,7 @@ debounce(action, options)         → Debounced<T>  (with .cancel())
 isEmail(value)                    → Boolean
 formatCurrency(amount, options)   → String
 clamp(value, min, max)            → Number
+throttle(fn, wait)                → Throttled<T>  (with .cancel())
 ```
 
 A developer familiar with the TypeScript API should be able to use the Kotlin or Dart API with only idiomatic adjustments — not conceptual re-learning.
@@ -127,6 +129,16 @@ export function formatCurrency(
 ): string;
 
 export function clamp(value: number, min: number, max: number): number;
+
+export interface Throttled<T extends (...args: any[]) => void> {
+  (...args: Parameters<T>): void;
+  cancel(): void;
+}
+
+export function throttle<T extends (...args: any[]) => void>(
+  fn: T,
+  wait: number, // must be > 0
+): Throttled<T>;
 ```
 
 **Kotlin:**
@@ -152,6 +164,17 @@ fun formatCurrency(
 ): String
 
 fun clamp(value: Double, min: Double, max: Double): Double
+
+class Throttled<T>(private val invoke: (T) -> Unit) {
+  operator fun invoke(value: T): Unit
+  fun cancel(): Unit
+}
+
+fun <T> throttle(
+  waitMs: Long,           // must be > 0
+  scope: CoroutineScope,  // platform constraint: structured concurrency
+  action: (T) -> Unit,
+): Throttled<T>
 ```
 
 **Dart:**
@@ -176,6 +199,16 @@ String formatCurrency(
 });
 
 double clamp(double value, double min, double max);
+
+class Throttled<T> {
+  void call(T arg);
+  void cancel();
+}
+
+Throttled<T> throttle<T>(
+  void Function(T) fn,
+  Duration wait, // must be > Duration.zero
+);
 ```
 
 ### Platform-Specific Adaptations
@@ -189,6 +222,7 @@ While maintaining API consistency, we leverage platform strengths:
 - **Intl.NumberFormat** for currency formatting
 - **RegExp** for email validation
 - **Math.min/Math.max** for clamp
+- **setTimeout/clearTimeout** for throttle timer
 
 #### Kotlin Implementation
 
@@ -197,6 +231,7 @@ While maintaining API consistency, we leverage platform strengths:
 - **NumberFormat/Currency** for localized formatting
 - **Regex** for email validation
 - **Double.coerceIn** for clamp
+- **Coroutine delay + Job** for throttle wait period
 
 #### Dart/Flutter Implementation
 
@@ -205,6 +240,7 @@ While maintaining API consistency, we leverage platform strengths:
 - **RegExp** for email validation
 - **Null safety** with full type-safe APIs
 - **num.clamp** for clamp
+- **Timer** for throttle scheduling (same as debounce)
 
 ## Build System Architecture
 
@@ -284,17 +320,19 @@ android.yml:
 ```
 packages/core/web/tests/
 ├── core.test.ts              # debounce, isEmail, formatCurrency tests
-└── clamp.test.ts             # clamp unit tests
+├── clamp.test.ts             # clamp unit tests
+└── throttle.test.ts          # throttle unit tests
 
 packages/core/android/src/test/kotlin/com/kompkit/core/
-└── CoreTests.kt              # All utility tests (incl. ClampTests)
+└── CoreTests.kt              # All utility tests (incl. ThrottleTests, ClampTests)
 
 packages/core/flutter/test/
 ├── kompkit_core_test.dart     # Integration tests
 ├── debounce_test.dart         # Debounce unit tests
 ├── validate_test.dart         # Validation unit tests
 ├── format_test.dart           # Formatting unit tests
-└── clamp_test.dart            # Clamp unit tests
+├── clamp_test.dart            # Clamp unit tests
+└── throttle_test.dart         # Throttle unit tests
 ```
 
 ### Test Coverage

docs/android.md

@@ -31,6 +31,7 @@ import com.kompkit.core.debounce
 import com.kompkit.core.isEmail
 import com.kompkit.core.formatCurrency
 import com.kompkit.core.clamp
+import com.kompkit.core.throttle
 ```
 
 ## Usage examples
@@ -80,6 +81,23 @@ clamp(-3.0, 0.0, 10.0)  // 0.0
 clamp(15.0, 0.0, 10.0)  // 10.0
 ```
 
+### throttle
+
+```kotlin
+import com.kompkit.core.throttle
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+
+val scope = CoroutineScope(Dispatchers.Main)
+val onScroll = throttle<Unit>(200L, scope) {
+    println("scroll event")
+}
+
+onScroll(Unit)    // executes immediately
+onScroll(Unit)    // ignored within 200ms
+onScroll.cancel() // reset state
+```
+
 ## Jetpack Compose integration
 
 ```kotlin
@@ -111,7 +129,7 @@ fun SearchBox() {
 
 ## Notes
 
-- Requires `kotlinx-coroutines-core` for the `debounce` utility.
+- Requires `kotlinx-coroutines-core` for the `debounce` and `throttle` utilities.
 - All utilities are top-level functions in the `com.kompkit.core` package.
 - `formatCurrency` accepts a BCP 47 locale string (e.g., `"en-US"`) — no `java.util.Locale` needed.
 - Compatible with Android API 21+.

docs/flutter.md

@@ -177,6 +177,28 @@ double opacity = clamp(userInput, 0.0, 1.0);
 double scrollOffset = clamp(rawOffset, 0.0, maxScrollExtent);
 ```
 
+### Throttle
+
+Limit a function to execute at most once per wait duration. The first call executes immediately; subsequent calls within the wait period are ignored.
+
+```dart
+final onScroll = throttle<void>((_) {
+  print('scroll event');
+}, const Duration(milliseconds: 200));
+
+onScroll(null);    // executes immediately
+onScroll(null);    // ignored within 200ms
+onScroll.cancel(); // reset state (e.g. in dispose())
+```
+
+Useful for scroll listeners, resize handlers, or any high-frequency event:
+
+```dart
+final onResize = throttle<Size>((size) {
+  setState(() => _size = size);
+}, const Duration(milliseconds: 100));
+```
+
 #### Flutter Widget Example
 
 ```dart
@@ -330,6 +352,7 @@ KompKit Core for Flutter/Dart works on:
 - **Email Validation**: Compiled regex for fast validation
 - **Currency Formatting**: Leverages Dart's `intl` package for optimal localization
 - **Clamp**: Pure arithmetic — zero overhead
+- **Throttle**: Uses Dart's `Timer` class — same mechanism as debounce
 
 ## Next Steps
 

docs/getting-started.md

@@ -56,11 +56,12 @@ npm run test
 
 ## Utilities
 
-| Utility          | Description                                              |
-| ---------------- | -------------------------------------------------------- |
-| `debounce`       | Debounce a function call by a delay.                     |
-| `isEmail`        | Validate a string with a basic email regex.              |
-| `formatCurrency` | Format numbers into a localized currency string.         |
-| `clamp`          | Constrain a number within an inclusive [min, max] range. |
+| Utility          | Description                                               |
+| ---------------- | --------------------------------------------------------- |
+| `debounce`       | Debounce a function call by a delay.                      |
+| `isEmail`        | Validate a string with a basic email regex.               |
+| `formatCurrency` | Format numbers into a localized currency string.          |
+| `clamp`          | Constrain a number within an inclusive [min, max] range.  |
+| `throttle`       | Limit a function to execute at most once per wait period. |
 
 Next: read the detailed guides for [Web](./web.md), [Android](./android.md), [Flutter](./flutter.md), and the [Recipes](./recipes.md).

docs/recipes.md

@@ -290,6 +290,84 @@ class _PriceDisplayState extends State<PriceDisplay> {
 }
 ```
 
+## Throttled scroll handler (TypeScript)
+
+```ts
+import { throttle } from "kompkit-core";
+
+const onScroll = throttle(() => {
+  console.log("scroll position:", window.scrollY);
+}, 200);
+
+window.addEventListener("scroll", onScroll);
+
+// On cleanup:
+onScroll.cancel();
+window.removeEventListener("scroll", onScroll);
+```
+
+## Throttled event handler (Kotlin)
+
+```kotlin
+import com.kompkit.core.throttle
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+
+val scope = CoroutineScope(Dispatchers.Main)
+val onSensorUpdate = throttle<Float>(100L, scope) { value ->
+    updateUI(value)
+}
+
+// In sensor callback:
+onSensorUpdate(sensorValue)
+
+// On cleanup:
+onSensorUpdate.cancel()
+```
+
+## Throttled scroll listener (Flutter)
+
+```dart
+import 'package:flutter/material.dart';
+import 'package:kompkit_core/kompkit_core.dart';
+
+class ScrollTracker extends StatefulWidget {
+  @override
+  _ScrollTrackerState createState() => _ScrollTrackerState();
+}
+
+class _ScrollTrackerState extends State<ScrollTracker> {
+  final _controller = ScrollController();
+  late final Throttled<double> _throttledScroll;
+
+  @override
+  void initState() {
+    super.initState();
+    _throttledScroll = throttle<double>(
+      (offset) => print('scroll: $offset'),
+      const Duration(milliseconds: 200),
+    );
+    _controller.addListener(() => _throttledScroll(_controller.offset));
+  }
+
+  @override
+  void dispose() {
+    _throttledScroll.cancel();
+    _controller.dispose();
+    super.dispose();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    return ListView.builder(
+      controller: _controller,
+      itemCount: 100,
+      itemBuilder: (_, i) => ListTile(title: Text('Item $i')),
+    );
+  }
+}
+```
+
 ## Clamping a slider value (TypeScript / React)
 
 ```tsx

docs/web.md

@@ -15,13 +15,25 @@ npm i kompkit-core
 ESM:
 
 ```ts
-import { debounce, isEmail, formatCurrency, clamp } from "kompkit-core";
+import {
+  debounce,
+  isEmail,
+  formatCurrency,
+  clamp,
+  throttle,
+} from "kompkit-core";
 ```
 
 CommonJS:
 
 ```js
-const { debounce, isEmail, formatCurrency, clamp } = require("kompkit-core");
+const {
+  debounce,
+  isEmail,
+  formatCurrency,
+  clamp,
+  throttle,
+} = require("kompkit-core");
 ```
 
 ## Usage examples
@@ -68,6 +80,19 @@ clamp(-3, 0, 10); // 0
 clamp(15, 0, 10); // 10
 ```
 
+### throttle
+
+```ts
+import { throttle } from "kompkit-core";
+
+const onScroll = throttle(() => {
+  console.log("scroll");
+}, 200);
+
+window.addEventListener("scroll", onScroll);
+onScroll.cancel(); // reset state (e.g. on unmount)
+```
+
 ## React snippet
 
 ```tsx

packages/core/flutter/README.md

@@ -30,6 +30,11 @@ print(formatCurrency(1234.56)); // "$1,234.56" (en-US / USD default)
 
 // Clamp a value
 print(clamp(15.0, 0.0, 10.0)); // 10.0
+
+// Throttle a function
+final onScroll = throttle<double>((offset) => print(offset),
+                                  const Duration(milliseconds: 200));
+onScroll.cancel(); // reset state
 ```
 
 ## Documentation