leptos_use/
sync_signal.rs

1use crate::core::UseRwSignal;
2use default_struct_builder::DefaultBuilder;
3use leptos::prelude::*;
4use std::rc::Rc;
5
6/// Two-way Signals synchronization.
7///
8/// > Note: Please consider first if you can achieve your goals with the
9/// > ["Good Options" described in the Leptos book](https://book.leptos.dev/reactivity/working_with_signals.html#making-signals-depend-on-each-other)
10/// > Only if you really have to, use this function. This is, in effect, the
11/// > ["If you really must..." option](https://book.leptos.dev/reactivity/working_with_signals.html#if-you-really-must).
12///
13/// ## Demo
14///
15/// [Link to Demo](https://github.com/Synphonyte/leptos-use/tree/main/examples/sync_signal)
16///
17/// ## Usage
18///
19/// ```
20/// # use leptos::prelude::*;
21/// # use leptos::logging::log;
22/// # use leptos_use::sync_signal;
23/// #
24/// # #[component]
25/// # fn Demo() -> impl IntoView {
26/// let (a, set_a) = signal(1);
27/// let (b, set_b) = signal(2);
28///
29/// let stop = sync_signal((a, set_a), (b, set_b));
30///
31/// log!("a: {}, b: {}", a.get(), b.get()); // a: 1, b: 1
32///
33/// set_b.set(3);
34///
35/// log!("a: {}, b: {}", a.get(), b.get()); // a: 3, b: 3
36///
37/// set_a.set(4);
38///
39/// log!("a: {}, b: {}", a.get(), b.get()); // a: 4, b: 4
40/// #
41/// # view! { }
42/// # }
43/// ```
44///
45/// ### `RwSignal`
46///
47/// You can mix and match `RwSignal`s and `Signal`-`WriteSignal` pairs.
48///
49/// ```
50/// # use leptos::prelude::*;
51/// # use leptos_use::sync_signal;
52/// #
53/// # #[component]
54/// # fn Demo() -> impl IntoView {
55/// let (a, set_a) = signal(1);
56/// let (b, set_b) = signal(2);
57/// let c_rw = RwSignal::new(3);
58/// let d_rw = RwSignal::new(4);
59///
60/// sync_signal((a, set_a), c_rw);
61/// sync_signal(d_rw, (b, set_b));
62/// sync_signal(c_rw, d_rw);
63///
64/// #
65/// # view! { }
66/// # }
67/// ```
68///
69/// ### One directional
70///
71/// You can synchronize a signal only from left to right or right to left.
72///
73/// ```
74/// # use leptos::prelude::*;
75/// # use leptos::logging::log;
76/// # use leptos_use::{sync_signal_with_options, SyncSignalOptions, SyncDirection};
77/// #
78/// # #[component]
79/// # fn Demo() -> impl IntoView {
80/// let (a, set_a) = signal(1);
81/// let (b, set_b) = signal(2);
82///
83/// let stop = sync_signal_with_options(
84///     (a, set_a),
85///     (b, set_b),
86///     SyncSignalOptions::default().direction(SyncDirection::LeftToRight)
87/// );
88///
89/// set_b.set(3); // doesn't sync
90///
91/// log!("a: {}, b: {}", a.get(), b.get()); // a: 1, b: 3
92///
93/// set_a.set(4);
94///
95/// log!("a: {}, b: {}", a.get(), b.get()); // a: 4, b: 4
96/// #
97/// # view! { }
98/// # }
99/// ```
100///
101/// ### Custom Transform
102///
103/// You can optionally provide custom transforms between the two signals.
104///
105/// ```
106/// # use leptos::prelude::*;
107/// # use leptos::logging::log;
108/// # use leptos_use::{sync_signal_with_options, SyncSignalOptions};
109/// #
110/// # #[component]
111/// # fn Demo() -> impl IntoView {
112/// let (a, set_a) = signal(10);
113/// let (b, set_b) = signal(2);
114///
115/// let stop = sync_signal_with_options(
116///     (a, set_a),
117///     (b, set_b),
118///     SyncSignalOptions::with_transforms(
119///         |left| *left * 2,
120///         |right| *right / 2,
121///     ),
122/// );
123///
124/// log!("a: {}, b: {}", a.get(), b.get()); // a: 10, b: 20
125///
126/// set_b.set(30);
127///
128/// log!("a: {}, b: {}", a.get(), b.get()); // a: 15, b: 30
129/// #
130/// # view! { }
131/// # }
132/// ```
133///
134/// #### Different Types
135///
136/// `SyncSignalOptions::default()` is only defined if the two signal types are identical.
137/// Otherwise, you have to initialize the options with `with_transforms` or `with_assigns` instead
138/// of `default`.
139///
140/// ```
141/// # use leptos::prelude::*;
142/// # use leptos_use::{sync_signal_with_options, SyncSignalOptions};
143/// # use std::str::FromStr;
144/// #
145/// # #[component]
146/// # fn Demo() -> impl IntoView {
147/// let (a, set_a) = signal("10".to_string());
148/// let (b, set_b) = signal(2);
149///
150/// let stop = sync_signal_with_options(
151///     (a, set_a),
152///     (b, set_b),
153///     SyncSignalOptions::with_transforms(
154///         |left: &String| i32::from_str(left).unwrap_or_default(),
155///         |right: &i32| right.to_string(),
156///     ),
157/// );
158/// #
159/// # view! { }
160/// # }
161/// ```
162///
163/// ```
164/// # use leptos::prelude::*;
165/// # use leptos_use::{sync_signal_with_options, SyncSignalOptions};
166/// # use std::str::FromStr;
167/// #
168/// #[derive(Clone)]
169/// pub struct Foo {
170///     bar: i32,
171/// }
172///
173/// # #[component]
174/// # fn Demo() -> impl IntoView {
175/// let (a, set_a) = signal(Foo { bar: 10 });
176/// let (b, set_b) = signal(2);
177///
178/// let stop = sync_signal_with_options(
179///     (a, set_a),
180///     (b, set_b),
181///     SyncSignalOptions::with_assigns(
182///         |b: &mut i32, a: &Foo| *b = a.bar,
183///         |a: &mut Foo, b: &i32| a.bar = *b,
184///     ),
185/// );
186/// #
187/// # view! { }
188/// # }
189/// ```
190///
191/// ## Server-Side Rendering
192///
193/// On the server the signals are not continuously synced. If the option `immediate` is `true`, the
194/// signals are synced once initially. If the option `immediate` is `false`, then this function
195/// does nothing.
196pub fn sync_signal<T>(
197    left: impl Into<UseRwSignal<T>>,
198    right: impl Into<UseRwSignal<T>>,
199) -> impl Fn() + Clone
200where
201    T: Clone + Send + Sync + 'static,
202{
203    sync_signal_with_options(left, right, SyncSignalOptions::<T, T>::default())
204}
205
206/// Version of [`sync_signal`] that takes a `SyncSignalOptions`. See [`sync_signal`] for how to use.
207pub fn sync_signal_with_options<L, R>(
208    left: impl Into<UseRwSignal<L>>,
209    right: impl Into<UseRwSignal<R>>,
210    options: SyncSignalOptions<L, R>,
211) -> impl Fn() + Clone
212where
213    L: Clone + Send + Sync + 'static,
214    R: Clone + Send + Sync + 'static,
215{
216    let SyncSignalOptions {
217        immediate,
218        direction,
219        transforms,
220    } = options;
221
222    let (assign_ltr, assign_rtl) = transforms.assigns();
223
224    let left = left.into();
225    let right = right.into();
226
227    let mut stop_watch_left = None;
228    let mut stop_watch_right = None;
229
230    let is_sync_update = StoredValue::new(false);
231
232    if matches!(direction, SyncDirection::Both | SyncDirection::LeftToRight) {
233        #[cfg(feature = "ssr")]
234        {
235            if immediate {
236                let assign_ltr = Rc::clone(&assign_ltr);
237                right.try_update(move |right| assign_ltr(right, &left.get_untracked()));
238            }
239        }
240
241        stop_watch_left = Some(Effect::watch(
242            move || left.get(),
243            move |new_value, _, _| {
244                if !is_sync_update.get_value() || !matches!(direction, SyncDirection::Both) {
245                    is_sync_update.set_value(true);
246                    right.try_update(|right| {
247                        assign_ltr(right, new_value);
248                    });
249                } else {
250                    is_sync_update.set_value(false);
251                }
252            },
253            immediate,
254        ));
255    }
256
257    if matches!(direction, SyncDirection::Both | SyncDirection::RightToLeft) {
258        #[cfg(feature = "ssr")]
259        {
260            if immediate && matches!(direction, SyncDirection::RightToLeft) {
261                let assign_rtl = Rc::clone(&assign_rtl);
262                left.try_update(move |left| assign_rtl(left, &right.get_untracked()));
263            }
264        }
265
266        stop_watch_right = Some(Effect::watch(
267            move || right.get(),
268            move |new_value, _, _| {
269                if !is_sync_update.get_value() || !matches!(direction, SyncDirection::Both) {
270                    is_sync_update.set_value(true);
271                    left.try_update(|left| assign_rtl(left, new_value));
272                } else {
273                    is_sync_update.set_value(false);
274                }
275            },
276            immediate,
277        ));
278    }
279
280    move || {
281        if let Some(stop_watch_left) = &stop_watch_left {
282            stop_watch_left.stop();
283        }
284        if let Some(stop_watch_right) = &stop_watch_right {
285            stop_watch_right.stop();
286        }
287    }
288}
289
290/// Direction of syncing.
291#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
292pub enum SyncDirection {
293    LeftToRight,
294    RightToLeft,
295    #[default]
296    Both,
297}
298
299pub type AssignFn<T, S> = Rc<dyn Fn(&mut T, &S)>;
300
301/// Transforms or assigns for syncing.
302pub enum SyncTransforms<L, R> {
303    /// Transform the signal into each other by calling the transform functions.
304    /// The values are then simply assigned.
305    Transforms {
306        /// Transforms the left signal into the right signal.
307        ltr: Rc<dyn Fn(&L) -> R>,
308        /// Transforms the right signal into the left signal.
309        rtl: Rc<dyn Fn(&R) -> L>,
310    },
311
312    /// Assign the signals to each other. Instead of using `=` to assign the signals,
313    /// these functions are called.
314    Assigns {
315        /// Assigns the left signal to the right signal.
316        ltr: AssignFn<R, L>,
317        /// Assigns the right signal to the left signal.
318        rtl: AssignFn<L, R>,
319    },
320}
321
322impl<T> Default for SyncTransforms<T, T>
323where
324    T: Clone,
325{
326    fn default() -> Self {
327        Self::Assigns {
328            ltr: Rc::new(|right, left| *right = left.clone()),
329            rtl: Rc::new(|left, right| *left = right.clone()),
330        }
331    }
332}
333
334impl<L, R> SyncTransforms<L, R>
335where
336    L: 'static,
337    R: 'static,
338{
339    /// Returns assign functions for both directions that respect the value of this enum.
340    pub fn assigns(&self) -> (AssignFn<R, L>, AssignFn<L, R>) {
341        match self {
342            SyncTransforms::Transforms { ltr, rtl } => {
343                let ltr = Rc::clone(ltr);
344                let rtl = Rc::clone(rtl);
345                (
346                    Rc::new(move |right, left| *right = ltr(left)),
347                    Rc::new(move |left, right| *left = rtl(right)),
348                )
349            }
350            SyncTransforms::Assigns { ltr, rtl } => (Rc::clone(ltr), Rc::clone(rtl)),
351        }
352    }
353}
354
355/// Options for [`sync_signal_with_options`].
356#[derive(DefaultBuilder)]
357pub struct SyncSignalOptions<L, R> {
358    /// If `true`, the signals will be immediately synced when this function is called.
359    /// If `false`, a signal is only updated when the other signal's value changes.
360    /// Defaults to `true`.
361    immediate: bool,
362
363    /// Direction of syncing. Defaults to `SyncDirection::Both`.
364    direction: SyncDirection,
365
366    /// How to transform or assign the values to each other
367    /// If `L` and `R` are identical this defaults to the simple `=` operator. If the types are
368    /// not the same, then you have to choose to either use [`SyncSignalOptions::with_transforms`]
369    /// or [`SyncSignalOptions::with_assigns`].
370    #[builder(skip)]
371    transforms: SyncTransforms<L, R>,
372}
373
374impl<L, R> SyncSignalOptions<L, R> {
375    /// Initializes options with transforms functions that convert the signals into each other.
376    pub fn with_transforms(
377        transform_ltr: impl Fn(&L) -> R + 'static,
378        transform_rtl: impl Fn(&R) -> L + 'static,
379    ) -> Self {
380        Self {
381            immediate: true,
382            direction: SyncDirection::Both,
383            transforms: SyncTransforms::Transforms {
384                ltr: Rc::new(transform_ltr),
385                rtl: Rc::new(transform_rtl),
386            },
387        }
388    }
389
390    /// Initializes options with assign functions that replace the default `=` operator.
391    pub fn with_assigns(
392        assign_ltr: impl Fn(&mut R, &L) + 'static,
393        assign_rtl: impl Fn(&mut L, &R) + 'static,
394    ) -> Self {
395        Self {
396            immediate: true,
397            direction: SyncDirection::Both,
398            transforms: SyncTransforms::Assigns {
399                ltr: Rc::new(assign_ltr),
400                rtl: Rc::new(assign_rtl),
401            },
402        }
403    }
404}
405
406impl<T> Default for SyncSignalOptions<T, T>
407where
408    T: Clone,
409{
410    fn default() -> Self {
411        Self {
412            immediate: true,
413            direction: Default::default(),
414            transforms: Default::default(),
415        }
416    }
417}
leptos_use/sync_signal.rs

leptos_use/
sync_signal.rs
