nami 0.11.0

A powerful, lightweight reactive framework.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148

//! Debounce utilities for throttling signal updates.
//!
//! This module provides helpers that debounce reactive updates.
use alloc::{boxed::Box, rc::Rc};
use core::{cell::RefCell, fmt::Debug, time::Duration};
use executor_core::{DefaultExecutor, LocalExecutor, Task};
use nami_core::watcher::Context;

use crate::{
    Signal,
    utils::sleep,
    watcher::{WatcherManager, WatcherManagerGuard},
};
use nami_core::{SignalIdentity, observe::Origin};

/// A debounce wrapper that delays signal updates until a specified duration has passed
/// without new updates. This helps reduce the frequency of updates for rapidly changing signals.
pub struct Debounce<S, E>
where
    S: Signal,
{
    signal: S,
    duration: Duration,
    watchers: WatcherManager<S::Output>,
    executor: E,
    timer: Rc<RefCell<Option<Box<dyn Task<()>>>>>,
    guard: Rc<RefCell<Option<S::Guard>>>,
}

impl<S, E> Debug for Debounce<S, E>
where
    S: Signal + Debug,
    E: Debug,
{
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        f.debug_struct("Debounce")
            .field("signal", &self.signal)
            .field("duration", &self.duration)
            .field("watchers", &"<...>")
            .field("executor", &self.executor)
            .field("timer", &"<...>")
            .field("guard", &"<...>")
            .finish()
    }
}

impl<S, E> Clone for Debounce<S, E>
where
    S: Signal,
    E: Clone,
{
    fn clone(&self) -> Self {
        Self {
            signal: self.signal.clone(),
            duration: self.duration,
            watchers: self.watchers.clone(),
            executor: self.executor.clone(),
            timer: self.timer.clone(),
            guard: self.guard.clone(),
        }
    }
}

impl<S, E> Debounce<S, E>
where
    E: LocalExecutor + Clone + 'static,
    S: Signal,
{
    /// Creates a new debounce wrapper.
    #[track_caller]
    pub fn with_executor(signal: S, duration: Duration, executor: E) -> Self {
        let timer = Rc::default();
        let origin = Origin::capture::<Self>(SignalIdentity::from_rc(&timer));
        Self {
            signal,
            watchers: WatcherManager::with_origin(origin),
            duration,
            executor,
            timer,
            guard: Rc::default(),
        }
    }
}

impl<S> Debounce<S, DefaultExecutor>
where
    S: Signal,
{
    /// Creates a new debounce wrapper with the default executor.
    pub fn new(signal: S, duration: Duration) -> Self
    where
        S: Signal,
        S::Output: Clone + 'static,
    {
        Self::with_executor(signal, duration, executor_core::DefaultExecutor)
    }
}

impl<S, E> Signal for Debounce<S, E>
where
    S: Signal,
    S::Output: Clone + 'static,
    E: LocalExecutor + Clone + 'static,
{
    type Output = S::Output;
    type Guard = WatcherManagerGuard<S::Output>;

    fn get(&self) -> Self::Output {
        self.signal.get()
    }

    fn watch(&self, watcher: impl Fn(Context<Self::Output>) + 'static) -> Self::Guard {
        let signal = self.signal.clone();
        let watchers = self.watchers.clone();
        let executor = self.executor.clone();
        let timer = self.timer.clone();
        let duration = self.duration;

        // Ensure we only set up the upstream watcher once
        let _signal_guard = self.guard.borrow_mut().get_or_insert_with(|| {
            signal.watch(move |ctx| {
                // Cancel any existing timer by dropping the previous task
                let _previous_task = timer.borrow_mut().take();

                let watchers = watchers.clone();
                let timer = timer.clone();

                if watchers.is_empty() {
                    return;
                }

                let delayed_context = ctx;
                let task = executor.spawn_local(async move {
                    sleep(duration).await;
                    if watchers.is_empty() {
                        return;
                    }
                    let context = delayed_context;
                    watchers.notify(&context);
                });

                *timer.borrow_mut() = Some(Box::new(task));
            })
        });

        self.watchers.register_as_guard(watcher)
    }
}