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

//! # Map Module
//!
//! This module provides transformation and memoization capabilities for reactive values.
//!
//! The `Map` type enables you to transform values from one type to another while preserving
//! the reactive nature of the computation. It automatically caches the result of the transformation
//! for better performance, invalidating the cache only when the source value changes.
//!
//! ## Usage Example
//!
//! ```rust
//! use nami::{binding, Binding, Signal};
//! use nami::map::map;
//!
//! let number: Binding<i32> = binding(5);
//! let doubled = map(number, |n: i32| n * 2);
//!
//! assert_eq!(doubled.get(), 10);
//!
//! // The transformation is automatically cached
//! doubled.get(); // Uses cached value, doesn't recompute
//! ```

use core::{marker::PhantomData, panic::Location};

use crate::{Signal, SignalIdentity, watcher::Context};

/// A reactive computation that transforms values from a source computation.
///
/// `Map<C, F, Output>` applies a transformation function `F` to the results
/// of a source computation `C`, producing a value of type `Output`. The result
/// is automatically cached and only recomputed when the source value changes.
#[derive(Debug)]
pub struct Map<C, F, Output> {
    source: C,
    f: F,
    discriminator: usize,
    _marker: PhantomData<Output>,
}

impl<C, F, Output> Map<C, F, Output>
where
    C: Signal,
    F: 'static + Clone + Fn(C::Output) -> Output,
    Output: 'static, // Prevents confusing `does implement Signal` errors, but fast fail.
{
    /// Creates a new `Map` that transforms values from `source` using function `f`.
    ///
    /// # Parameters
    ///
    /// * `source`: The source computation whose results will be transformed
    /// * `f`: The transformation function to apply to the source's results
    ///
    /// # Returns
    ///
    /// A new `Map` instance that will transform values from the source.
    #[track_caller]
    pub fn new(source: C, f: F) -> Self {
        Self {
            source,
            f,
            discriminator: SignalIdentity::call_site_discriminator::<(F, Output)>(
                Location::caller(),
            ),
            _marker: PhantomData,
        }
    }
}

/// Helper function to create a new `Map` transformation.
///
/// This is a convenience wrapper around `Map::new()` with improved type inference.
///
/// # Parameters
///
/// * `source`: The source computation whose results will be transformed
/// * `f`: The transformation function to apply to the source's results
///
/// # Returns
///
/// A new `Map` instance that will transform values from the source.
///
/// # Example
///
/// ```rust
/// use nami::{binding, Binding, Signal};
/// use nami::map::map;
///
/// let counter: Binding<i32> = binding(1);
/// let doubled = map(counter, |n: i32| n * 2);
/// assert_eq!(doubled.get(), 2);
/// ```
#[track_caller]
pub fn map<C, F, Output>(source: C, f: F) -> Map<C, F, Output>
where
    C: Signal + 'static,
    Output: 'static,
    F: 'static + Clone + Fn(C::Output) -> Output,
{
    Map::new(source, f)
}

impl<C: Clone, F: Clone, Output> Clone for Map<C, F, Output> {
    fn clone(&self) -> Self {
        Self {
            source: self.source.clone(),
            f: self.f.clone(),
            discriminator: self.discriminator,
            _marker: PhantomData,
        }
    }
}

impl<C, F, Output> Signal for Map<C, F, Output>
where
    C: Signal,
    F: 'static + Clone + Fn(C::Output) -> Output,
    Output: 'static,
{
    type Output = Output;
    type Guard = C::Guard;

    /// Computes the transformed value, using the cache when available.
    fn get(&self) -> Output {
        (self.f)(self.source.get())
    }

    fn identity(&self) -> Option<SignalIdentity> {
        self.source
            .identity()
            .map(|identity| identity.with_discriminator(self.discriminator))
    }

    /// Registers a watcher to be notified when the transformed value changes.
    fn watch(&self, watcher: impl Fn(Context<Self::Output>) + 'static) -> Self::Guard {
        let this = self.clone();

        self.source.watch(move |context| {
            let context = context.map(|value| (this.f)(value));
            watcher(context);
        })
    }
}

impl_signal_ops!(Map<C, F, Output>, [C, F, Output], Output);