leptos_use/
sync_signal.rs

1use crate::core::UseRwSignal;
2use default_struct_builder::DefaultBuilder;
3use leptos::prelude::*;
4use std::{ops::Deref, 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/// > Make sure you follow the [instructions in Server-Side Rendering](https://leptos-use.rs/server_side_rendering.html).
194///
195/// On the server the signals are not continuously synced. If the option `immediate` is `true`, the
196/// signals are synced once initially. If the option `immediate` is `false`, then this function
197/// does nothing.
198pub fn sync_signal<LeftRead, RightRead, LeftWrite, RightWrite, T>(
199    left: impl Into<UseRwSignal<LeftRead, LeftWrite, T>>,
200    right: impl Into<UseRwSignal<RightRead, RightWrite, T>>,
201) -> impl Fn() + Clone
202where
203    T: Clone + Send + Sync + 'static,
204    LeftRead: Read + ReadUntracked + Track + Copy + Send + Sync + 'static,
205    <LeftRead as Read>::Value: Deref<Target = T>,
206    <LeftRead as ReadUntracked>::Value: Deref<Target = T>,
207    LeftWrite: Write<Value = T> + Copy + 'static,
208    RightRead: Read + ReadUntracked + Track + Copy + Send + Sync + 'static,
209    <RightRead as Read>::Value: Deref<Target = T>,
210    <RightRead as ReadUntracked>::Value: Deref<Target = T>,
211    RightWrite: Write<Value = T> + Copy + 'static,
212{
213    sync_signal_with_options(left, right, SyncSignalOptions::<T, T>::default())
214}
215
216/// Version of [`sync_signal`] that takes a `SyncSignalOptions`. See [`sync_signal`] for how to use.
217pub fn sync_signal_with_options<LeftRead, RightRead, LeftWrite, RightWrite, Left, Right>(
218    left: impl Into<UseRwSignal<LeftRead, LeftWrite, Left>>,
219    right: impl Into<UseRwSignal<RightRead, RightWrite, Right>>,
220    options: SyncSignalOptions<Left, Right>,
221) -> impl Fn() + Clone
222where
223    Left: Clone + Send + Sync + 'static,
224    LeftRead: Read + ReadUntracked + Track + Copy + Send + Sync + 'static,
225    <LeftRead as Read>::Value: Deref<Target = Left>,
226    <LeftRead as ReadUntracked>::Value: Deref<Target = Left>,
227    LeftWrite: Write<Value = Left> + Copy + 'static,
228    Right: Clone + Send + Sync + 'static,
229    RightRead: Read + ReadUntracked + Track + Copy + Send + Sync + 'static,
230    <RightRead as Read>::Value: Deref<Target = Right>,
231    <RightRead as ReadUntracked>::Value: Deref<Target = Right>,
232    RightWrite: Write<Value = Right> + Copy + 'static,
233{
234    let SyncSignalOptions {
235        immediate,
236        direction,
237        transforms,
238    } = options;
239
240    let (assign_ltr, assign_rtl) = transforms.assigns();
241
242    let left = left.into();
243    let right = right.into();
244
245    let mut stop_watch_left = None;
246    let mut stop_watch_right = None;
247
248    let is_sync_update = StoredValue::new(false);
249
250    if matches!(direction, SyncDirection::Both | SyncDirection::LeftToRight) {
251        #[cfg(feature = "ssr")]
252        {
253            if immediate {
254                let assign_ltr = Rc::clone(&assign_ltr);
255                right.try_update(move |right| assign_ltr(right, &left.get_untracked()));
256            }
257        }
258
259        stop_watch_left = Some(Effect::watch(
260            move || left.get(),
261            move |new_value, _, _| {
262                if !is_sync_update.get_value() || !matches!(direction, SyncDirection::Both) {
263                    is_sync_update.set_value(true);
264                    right.try_update(|right| {
265                        assign_ltr(right, new_value);
266                    });
267                } else {
268                    is_sync_update.set_value(false);
269                }
270            },
271            immediate,
272        ));
273    }
274
275    if matches!(direction, SyncDirection::Both | SyncDirection::RightToLeft) {
276        #[cfg(feature = "ssr")]
277        {
278            if immediate && matches!(direction, SyncDirection::RightToLeft) {
279                let assign_rtl = Rc::clone(&assign_rtl);
280                left.try_update(move |left| assign_rtl(left, &right.get_untracked()));
281            }
282        }
283
284        stop_watch_right = Some(Effect::watch(
285            move || right.get(),
286            move |new_value, _, _| {
287                if !is_sync_update.get_value() || !matches!(direction, SyncDirection::Both) {
288                    is_sync_update.set_value(true);
289                    left.try_update(|left| assign_rtl(left, new_value));
290                } else {
291                    is_sync_update.set_value(false);
292                }
293            },
294            immediate,
295        ));
296    }
297
298    move || {
299        if let Some(stop_watch_left) = &stop_watch_left {
300            stop_watch_left.stop();
301        }
302        if let Some(stop_watch_right) = &stop_watch_right {
303            stop_watch_right.stop();
304        }
305    }
306}
307
308/// Direction of syncing.
309#[derive(Clone, Copy, Debug, PartialEq, Eq, Default)]
310pub enum SyncDirection {
311    LeftToRight,
312    RightToLeft,
313    #[default]
314    Both,
315}
316
317pub type AssignFn<T, S> = Rc<dyn Fn(&mut T, &S)>;
318
319/// Transforms or assigns for syncing.
320pub enum SyncTransforms<L, R> {
321    /// Transform the signal into each other by calling the transform functions.
322    /// The values are then simply assigned.
323    Transforms {
324        /// Transforms the left signal into the right signal.
325        ltr: Rc<dyn Fn(&L) -> R>,
326        /// Transforms the right signal into the left signal.
327        rtl: Rc<dyn Fn(&R) -> L>,
328    },
329
330    /// Assign the signals to each other. Instead of using `=` to assign the signals,
331    /// these functions are called.
332    Assigns {
333        /// Assigns the left signal to the right signal.
334        ltr: AssignFn<R, L>,
335        /// Assigns the right signal to the left signal.
336        rtl: AssignFn<L, R>,
337    },
338}
339
340impl<T> Default for SyncTransforms<T, T>
341where
342    T: Clone,
343{
344    fn default() -> Self {
345        Self::Assigns {
346            ltr: Rc::new(|right, left| *right = left.clone()),
347            rtl: Rc::new(|left, right| *left = right.clone()),
348        }
349    }
350}
351
352impl<L, R> SyncTransforms<L, R>
353where
354    L: 'static,
355    R: 'static,
356{
357    /// Returns assign functions for both directions that respect the value of this enum.
358    pub fn assigns(&self) -> (AssignFn<R, L>, AssignFn<L, R>) {
359        match self {
360            SyncTransforms::Transforms { ltr, rtl } => {
361                let ltr = Rc::clone(ltr);
362                let rtl = Rc::clone(rtl);
363                (
364                    Rc::new(move |right, left| *right = ltr(left)),
365                    Rc::new(move |left, right| *left = rtl(right)),
366                )
367            }
368            SyncTransforms::Assigns { ltr, rtl } => (Rc::clone(ltr), Rc::clone(rtl)),
369        }
370    }
371}
372
373/// Options for [`sync_signal_with_options`].
374#[derive(DefaultBuilder)]
375pub struct SyncSignalOptions<L, R> {
376    /// If `true`, the signals will be immediately synced when this function is called.
377    /// If `false`, a signal is only updated when the other signal's value changes.
378    /// Defaults to `true`.
379    immediate: bool,
380
381    /// Direction of syncing. Defaults to `SyncDirection::Both`.
382    direction: SyncDirection,
383
384    /// How to transform or assign the values to each other
385    /// If `L` and `R` are identical this defaults to the simple `=` operator. If the types are
386    /// not the same, then you have to choose to either use [`SyncSignalOptions::with_transforms`]
387    /// or [`SyncSignalOptions::with_assigns`].
388    #[builder(skip)]
389    transforms: SyncTransforms<L, R>,
390}
391
392impl<L, R> SyncSignalOptions<L, R> {
393    /// Initializes options with transforms functions that convert the signals into each other.
394    pub fn with_transforms(
395        transform_ltr: impl Fn(&L) -> R + 'static,
396        transform_rtl: impl Fn(&R) -> L + 'static,
397    ) -> Self {
398        Self {
399            immediate: true,
400            direction: SyncDirection::Both,
401            transforms: SyncTransforms::Transforms {
402                ltr: Rc::new(transform_ltr),
403                rtl: Rc::new(transform_rtl),
404            },
405        }
406    }
407
408    /// Initializes options with assign functions that replace the default `=` operator.
409    pub fn with_assigns(
410        assign_ltr: impl Fn(&mut R, &L) + 'static,
411        assign_rtl: impl Fn(&mut L, &R) + 'static,
412    ) -> Self {
413        Self {
414            immediate: true,
415            direction: SyncDirection::Both,
416            transforms: SyncTransforms::Assigns {
417                ltr: Rc::new(assign_ltr),
418                rtl: Rc::new(assign_rtl),
419            },
420        }
421    }
422}
423
424impl<T> Default for SyncSignalOptions<T, T>
425where
426    T: Clone,
427{
428    fn default() -> Self {
429        Self {
430            immediate: true,
431            direction: Default::default(),
432            transforms: Default::default(),
433        }
434    }
435}
leptos_use/sync_signal.rs

leptos_use/
sync_signal.rs
