From f27c113bb0fe40e804d65a65a1ea0bce1cf0e618 Mon Sep 17 00:00:00 2001
From: "Willow (GHOST)" <git@willow.sh>
Date: Tue, 13 Jan 2026 15:16:01 +0000
Subject: [PATCH] fix: add jsdoc comments to use-throttle

---
 .changeset/sad-cars-open.md                   |  5 ++
 .../use-throttle/use-throttle.svelte.ts       | 57 +++++++++++++++++++
 2 files changed, 62 insertions(+)
 create mode 100644 .changeset/sad-cars-open.md

diff --git a/.changeset/sad-cars-open.md b/.changeset/sad-cars-open.md
new file mode 100644
index 00000000..813a64f9
--- /dev/null
+++ b/.changeset/sad-cars-open.md
@@ -0,0 +1,5 @@
+---
+"runed": patch
+---
+
+fix: add jsdoc comments to use-throttle
diff --git a/packages/runed/src/lib/utilities/use-throttle/use-throttle.svelte.ts b/packages/runed/src/lib/utilities/use-throttle/use-throttle.svelte.ts
index b3e410ee..51566c3b 100644
--- a/packages/runed/src/lib/utilities/use-throttle/use-throttle.svelte.ts
+++ b/packages/runed/src/lib/utilities/use-throttle/use-throttle.svelte.ts
@@ -1,14 +1,71 @@
 import { untrack } from "svelte";
 import type { MaybeGetter } from "$lib/internal/types.js";
 
+/**
+ * Represents the throttled wrapper returned by {@link useThrottle}.
+ *
+ * The wrapper is an async function that returns a {@link Promise} resolving to
+ * the original callback's return value. In addition to being callable, it
+ * provides two helper properties `cancel()` and `pending`.
+ */
 type UseThrottleReturn<Args extends unknown[], Return> = ((
 	this: unknown,
 	...args: Args
 ) => Promise<Return>) & {
+	/**
+	 * Aborts any pending throttled execution and rejects the awaiting promise
+	 * with the string `"Cancelled"`.
+	 */
 	cancel: () => void;
+
+	/**
+	 * Whether a throttled call is currently waiting to be executed.
+	 */
 	pending: boolean;
 };
 
+/**
+ * Creates a throttled wrapper around a callback function.
+ *
+ * The returned function ensures that the original callback is invoked at most
+ * once per specified interval. Calls made during the wait period are queued
+ * and resolved with the result of the most recent invocation.
+ *
+ * @see https://runed.dev/docs/utilities/use-throttle
+ *
+ * @param callback - The function to be throttled.
+ * @param interval - The time interval in milliseconds, or a {@link MaybeGetter}
+ *   returning the interval. If omitted, the default is `250`.
+ *
+ * @returns A throttled version of the callback: {@link UseThrottleReturn}.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { useThrottle } from 'runed';
+ *
+ *   let search = $state('');
+ *   let throttledSearch = $state('');
+ *
+ *   // Create a throttled fn – it runs at most once per 250ms
+ *   const throttledUpdate = useThrottle(() => {
+ *     throttledSearch = search;
+ *   });
+ * </script>
+ *
+ * <input
+ *   bind:value={{
+ *     () => search,
+ *     (v) => {
+ *       search = v;
+ *       throttledUpdate();
+ *     }
+ *   }}
+ * />
+ *
+ * <p>You searched for: <b>{throttledSearch}</b></p>
+ * ```
+ */
 export function useThrottle<Args extends unknown[], Return>(
 	callback: (...args: Args) => Return,
 	interval: MaybeGetter<number> = 250