95 | * It should generally be avoided in favour of {@link listen(Handler)} so you don't 96 | * miss any updates, but in many circumstances it makes sense. 97 | *
98 | * NOTE: In the Java and other versions of Sodium, using sample() inside map(), filter() and 99 | * merge() is encouraged. In the Javascript/Typescript version, not so much, for the 100 | * following reason: The memory management is different in the Javascript version, and this 101 | * requires us to track all dependencies. In order for the use of sample() inside 102 | * a closure to be correct, the cell that was sample()d inside the closure would have to be 103 | * declared explicitly using the helpers lambda1(), lambda2(), etc. Because this is 104 | * something that can be got wrong, we don't encourage this kind of use of sample() in 105 | * Javascript. Better and simpler to use snapshot(). 106 | *
107 | * NOTE: If you need to sample() a cell, you have to make sure it's "alive" in terms of
108 | * memory management or it will ignore updates. To make a cell work correctly
109 | * with sample(), you have to ensure that it's being used. One way to guarantee this is
110 | * to register a dummy listener on the cell. It will also work to have it referenced
111 | * by something that is ultimately being listened to.
112 | */
113 | sample() : A {
114 | return Transaction.run(() => { return this.sampleNoTrans__(); });
115 | }
116 |
117 | sampleNoTrans__() : A { // TO DO figure out how to hide this
118 | return this.value;
119 | }
120 |
121 | /**
122 | * A variant of {@link sample()} that works with {@link CellLoop}s when they haven't been looped yet.
123 | * It should be used in any code that's general enough that it could be passed a {@link CellLoop}.
124 | * @see Stream#holdLazy(Lazy) Stream.holdLazy()
125 | */
126 | sampleLazy() : Lazy {
127 | const me = this;
128 | return Transaction.run(() => me.sampleLazyNoTrans__());
129 | }
130 |
131 | sampleLazyNoTrans__() : Lazy { // TO DO figure out how to hide this
132 | const me = this,
133 | s = new LazySample(me);
134 | Transaction.currentTransaction.sample(() => {
135 | s.value = me.valueUpdate != null ? me.valueUpdate : me.sampleNoTrans__();
136 | s.hasValue = true;
137 | s.cell = null;
138 | });
139 | return new Lazy(() => {
140 | if (s.hasValue)
141 | return s.value;
142 | else
143 | return s.cell.sample();
144 | });
145 | }
146 |
147 | /**
148 | * Transform the cell's value according to the supplied function, so the returned Cell
149 | * always reflects the value of the function applied to the input Cell's value.
150 | * @param f Function to apply to convert the values. It must be referentially transparent.
151 | */
152 | map(f : ((a : A) => B) | Lambda1
11 | * This is an OPERATIONAL primitive, which is not part of the main Sodium
12 | * API. It breaks the property of non-detectability of cell steps/updates.
13 | * The rule with this primitive is that you should only use it in functions
14 | * that do not allow the caller to detect the cell updates.
15 | */
16 | static updates(c : Cell) : Stream {
17 | /* Don't think this is needed
18 | const out = new StreamWithSend(null);
19 | out.setVertex__(new Vertex("updates", 0, [
20 | new Source(
21 | c.getStream__().getVertex__(),
22 | () => {
23 | return c.getStream__().listen_(out.getVertex__(), (a : A) => {
24 | out.send_(a);
25 | }, false);
26 | }
27 | ),
28 | new Source(
29 | c.getVertex__(),
30 | () => {
31 | return () => { };
32 | }
33 | )
34 | ]
35 | ));
36 | return out;
37 | */
38 | return c.getStream__();
39 | }
40 |
41 | /**
42 | * A stream that is guaranteed to fire once in the transaction where value() is invoked, giving
43 | * the current value of the cell, and thereafter behaves like {@link updates(Cell)},
44 | * firing for each update/step of the cell's value.
45 | *
46 | * This is an OPERATIONAL primitive, which is not part of the main Sodium
47 | * API. It breaks the property of non-detectability of cell steps/updates.
48 | * The rule with this primitive is that you should only use it in functions
49 | * that do not allow the caller to detect the cell updates.
50 | */
51 | static value(c : Cell) : Stream {
52 | return Transaction.run(() => {
53 | const sSpark = new StreamWithSend
89 | * In the case where two events are simultaneous (i.e. both
90 | * within the same transaction), the event from this will take precedence, and
91 | * the event from s will be dropped.
92 | * If you want to specify your own combining function, use {@link Stream#merge(Stream, Lambda2)}.
93 | * s1.orElse(s2) is equivalent to s1.merge(s2, (l, r) -> l).
94 | *
95 | * The name orElse() is used instead of merge() to make it really clear that care should
96 | * be taken, because events can be dropped.
97 | */
98 | orElse(s : Stream) : Stream {
99 | return this.merge(s, (left : A, right: A) => {
100 | return left;
101 | });
102 | }
103 |
104 | /**
105 | * Merge two streams of the same type into one, so that events on either input appear
106 | * on the returned stream.
107 | *
108 | * If the events are simultaneous (that is, one event from this and one from s
109 | * occurring in the same transaction), combine them into one using the specified combining function
110 | * so that the returned stream is guaranteed only ever to have one event per transaction.
111 | * The event from this will appear at the left input of the combining function, and
112 | * the event from s will appear at the right.
113 | * @param f Function to combine the values. It may construct FRP logic or use
114 | * {@link Cell#sample()}. Apart from this the function must be referentially transparent.
115 | */
116 | merge(s : Stream, f : ((left : A, right : A) => A) | Lambda2
242 | * There is an implicit delay: State updates caused by event firings being held with
243 | * {@link Stream#hold(Object)} don't become visible as the cell's current value until
244 | * the following transaction. To put this another way, {@link Stream#snapshot(Cell, Lambda2)}
245 | * always sees the value of a cell as it was before any state changes from the current
246 | * transaction.
247 | */
248 | snapshot
271 | * There is an implicit delay: State updates caused by event firings being held with
272 | * {@link Stream#hold(Object)} don't become visible as the cell's current value until
273 | * the following transaction. To put this another way, snapshot()
274 | * always sees the value of a cell as it was before any state changes from the current
275 | * transaction.
276 | */
277 | snapshot3
301 | * There is an implicit delay: State updates caused by event firings being held with
302 | * {@link Stream#hold(Object)} don't become visible as the cell's current value until
303 | * the following transaction. To put this another way, snapshot()
304 | * always sees the value of a cell as it was before any state changes from the current
305 | * transaction.
306 | */
307 | snapshot4
334 | * There is an implicit delay: State updates caused by event firings being held with
335 | * {@link Stream#hold(Object)} don't become visible as the cell's current value until
336 | * the following transaction. To put this another way, snapshot()
337 | * always sees the value of a cell as it was before any state changes from the current
338 | * transaction.
339 | */
340 | snapshot5
368 | * There is an implicit delay: State updates caused by event firings being held with
369 | * {@link Stream#hold(Object)} don't become visible as the cell's current value until
370 | * the following transaction. To put this another way, snapshot()
371 | * always sees the value of a cell as it was before any state changes from the current
372 | * transaction.
373 | */
374 | snapshot6