leptos_use/
watch_throttled.rs

1use crate::{utils::ThrottleOptions, watch_with_options, WatchOptions};
2use default_struct_builder::DefaultBuilder;
3
4/// A throttled version of `leptos::watch`.
5///
6/// ## Demo
7///
8/// [Link to Demo](https://github.com/Synphonyte/leptos-use/tree/main/examples/watch_throttled)
9///
10/// ## Usage
11///
12/// ```
13/// # use leptos::prelude::*;
14/// # use leptos::logging::log;
15/// # use leptos_use::watch_throttled;
16/// #
17/// # pub fn Demo() -> impl IntoView {
18/// #     let (source, set_source) = signal(0);
19/// #
20/// watch_throttled(
21///     move || source.get(),
22///     move |_, _, _| {
23///         log!("changed!");
24///     },
25///     500.0,
26/// );
27///
28/// #    view! { }
29/// # }
30/// ```
31///
32/// This really is only shorthand shorthand for `watch_with_options(deps, callback, WatchOptions::default().throttle(ms))`.
33///
34/// Please note that if the current component is cleaned up before the throttled callback is called, the throttled callback will not be called.
35///
36/// There's also `watch_throttled_with_options` where you can specify the other watch options (except `filter`).
37///
38/// ```
39/// # use leptos::prelude::*;
40/// # use leptos::logging::log;
41/// # use leptos_use::{watch_throttled_with_options, WatchThrottledOptions};
42/// #
43/// # pub fn Demo() -> impl IntoView {
44/// #     let (source, set_source) = signal(0);
45/// #
46/// watch_throttled_with_options(
47///     move || source.get(),
48///     move |_, _, _| {
49///         log!("changed!");
50///     },
51///     500.0,
52///     WatchThrottledOptions::default().leading(true).trailing(false),
53/// );
54///
55/// #    view! { }
56/// # }
57/// ```
58///
59/// ## Recommended Reading
60///
61/// - [**Debounce vs Throttle**: Definitive Visual Guide](https://redd.one/blog/debounce-vs-throttle)
62/// - [Debouncing and Throttling Explained Through Examples](https://css-tricks.com/debouncing-throttling-explained-examples/)
63///
64/// ## Server-Side Rendering
65///
66/// On the server the callback
67/// will never be called except if you set `immediate` to `true` in which case the callback will be
68/// called exactly once.
69///
70/// ## See also
71///
72/// * `leptos::watch`
73/// * [`fn@crate::watch_debounced`]
74pub fn watch_throttled<W, T, DFn, CFn>(
75    deps: DFn,
76    callback: CFn,
77    ms: f64,
78) -> impl Fn() + Clone + Send + Sync
79where
80    DFn: Fn() -> W + 'static,
81    CFn: Fn(&W, Option<&W>, Option<T>) -> T + Clone + 'static,
82    W: Clone + 'static,
83    T: Clone + 'static,
84{
85    watch_with_options(deps, callback, WatchOptions::default().throttle(ms))
86}
87
88/// Version of [`fn@watch_throttled`] that accepts `WatchThrottledOptions`. See [`watch_throttled`] for how to use.
89pub fn watch_throttled_with_options<W, T, DFn, CFn>(
90    deps: DFn,
91    callback: CFn,
92    ms: f64,
93    options: WatchThrottledOptions,
94) -> impl Fn() + Clone + Send + Sync
95where
96    DFn: Fn() -> W + 'static,
97    CFn: Fn(&W, Option<&W>, Option<T>) -> T + Clone + 'static,
98    W: Clone + 'static,
99    T: Clone + 'static,
100{
101    watch_with_options(
102        deps,
103        callback,
104        WatchOptions::default()
105            .throttle_with_options(
106                ms,
107                ThrottleOptions::default()
108                    .leading(options.leading)
109                    .trailing(options.trailing),
110            )
111            .immediate(options.immediate),
112    )
113}
114
115/// Options for [`watch_throttled_with_options`].
116#[derive(DefaultBuilder)]
117pub struct WatchThrottledOptions {
118    /// If `immediate` is false, the `callback` will not run immediately but only after
119    /// the first change is detected of any signal that is accessed in `deps`.
120    /// Defaults to `true`.
121    immediate: bool,
122
123    /// Invoke on the trailing edge of the timeout. Defaults to `true`.
124    pub trailing: bool,
125    /// Invoke on the leading edge of the timeout. Defaults to `true`.
126    pub leading: bool,
127}
128
129impl Default for WatchThrottledOptions {
130    fn default() -> Self {
131        Self {
132            immediate: false,
133            trailing: true,
134            leading: true,
135        }
136    }
137}
leptos_use/watch_throttled.rs

leptos_use/
watch_throttled.rs
