-
Notifications
You must be signed in to change notification settings - Fork 19
/
api.html
1931 lines (1503 loc) · 108 KB
/
api.html
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
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!DOCTYPE html>
<!-- This file is generated. See package.json -->
<html>
<head>
<title>Bacon.js 1.0 - API reference</title>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width" />
<meta name="keywords" content="bacon.js, FPR, functional reactive programming, javascript, reactive programming" />
<meta name="description" content="Bacon.js is a functional reactive programming library for javascript." />
<link rel="stylesheet" type="text/css" href="normalize.css" >
<link rel="stylesheet" type="text/css" href="foundation.min.css" >
<link rel="stylesheet" type="text/css" href="codemirror/codemirror.css" >
<link rel="stylesheet" type="text/css" href="marble.css">
<link rel="stylesheet" type="text/css" href="bacon.css" >
<link href='//fonts.googleapis.com/css?family=Yanone+Kaffeesatz' rel='stylesheet' type='text/css'>
<script src="//codeorigin.jquery.com/jquery-2.1.1.min.js"></script>
<script src="//cdnjs.cloudflare.com/ajax/libs/bacon.js/3.0.17/Bacon.min.js"></script>
<script>
Bacon.$.init($)
</script>
<script src="codemirror/codemirror.js"></script>
<script src="codemirror/javascript.js"></script>
<script src="marble.js"></script>
<script src="example.js"></script>
</script>
</head>
<body>
<div class="grid row">
<div class="large-4 columns sidebar">
<div class="logo">
<a href="index.html"><img alt="bacon.js logo" src="logo.png" /></a>
</div>
<div class="download">
<a class="button big-button" href="http://cdnjs.cloudflare.com/ajax/libs/bacon.js/3.0.17/Bacon.js" download>
Download Bacon.js
<small>v3.0.17</small>
<a class="github" href="https://github.com/baconjs/bacon.js#install-and-usage">[More install options]</a>
</a>
</div>
<div class="menu">
<div class="row">
<div class="large-12 small-6 columns">
<p> <a href="api.html"> API docs <small>(1.0)</small> </a> </p>
<ul>
<li><a href="#creating-streams">Creating streams</a>
<ul>
<li><a href="#$-aseventstream">$.asEventStream</a></li>
<li><a href="#bacon-frompromise">Bacon.fromPromise</a></li>
<li><a href="#bacon-fromevent">Bacon.fromEvent</a></li>
<li><a href="#bacon-fromcallback">Bacon.fromCallback</a></li>
<li><a href="#bacon-fromcallback-object">Bacon.fromCallback</a></li>
<li><a href="#bacon-fromnodecallback">Bacon.fromNodeCallback</a></li>
<li><a href="#bacon-fromesobservable">Bacon.fromESObservable</a></li>
<li><a href="#bacon-fromnodecallback-object">Bacon.fromNodeCallback</a></li>
<li><a href="#bacon-frompoll">Bacon.fromPoll</a></li>
<li><a href="#bacon-once">Bacon.once</a></li>
<li><a href="#bacon-fromarray">Bacon.fromArray</a></li>
<li><a href="#bacon-interval">Bacon.interval</a></li>
<li><a href="#bacon-sequentially">Bacon.sequentially</a></li>
<li><a href="#bacon-repeatedly">Bacon.repeatedly</a></li>
<li><a href="#bacon-repeat">Bacon.repeat</a></li>
<li><a href="#bacon-never">Bacon.never</a></li>
<li><a href="#bacon-later">Bacon.later</a></li>
<li><a href="#new-bacon-eventstream">new Bacon.EventStream</a></li>
<li><a href="#property-toeventstream">property.toEventStream</a></li>
</ul></li>
<li><a href="#baconfrombinder-for-custom-streams">Bacon.fromBinder for custom streams</a>
<ul>
<li><a href="#bacon-frombinder">Bacon.fromBinder</a></li>
<li><a href="#bacon-nomore">Bacon.noMore</a></li>
<li><a href="#bacon-more">Bacon.more</a></li>
</ul></li>
<li><a href="#common-methods-in-eventstreams-and-properties">Common methods in EventStreams and Properties</a>
<ul>
<li><a href="#observable-subscribe">observable.subscribe</a></li>
<li><a href="#observable-onvalue">observable.onValue</a></li>
<li><a href="#observable-onvalues">observable.onValues</a></li>
<li><a href="#observable-onerror">observable.onError</a></li>
<li><a href="#observable-onend">observable.onEnd</a></li>
<li><a href="#observable-topromise">observable.toPromise</a></li>
<li><a href="#observable-firsttopromise">observable.firstToPromise</a></li>
<li><a href="#observable-toesobservable">observable.toESObservable</a></li>
<li><a href="#observable-map">observable.map</a></li>
<li><a href="#stream-map">stream.map</a></li>
<li><a href="#observable-maperror">observable.mapError</a></li>
<li><a href="#observable-errors">observable.errors</a></li>
<li><a href="#observable-skiperrors">observable.skipErrors</a></li>
<li><a href="#observable-mapend">observable.mapEnd</a></li>
<li><a href="#observable-filter">observable.filter</a></li>
<li><a href="#observable-filter-property">observable.filter</a></li>
<li><a href="#observable-skipduplicates">observable.skipDuplicates</a></li>
<li><a href="#observable-take">observable.take</a></li>
<li><a href="#observable-takeuntil">observable.takeUntil</a></li>
<li><a href="#observable-takewhile">observable.takeWhile</a></li>
<li><a href="#observable-takewhile-property">observable.takeWhile</a></li>
<li><a href="#observable-first">observable.first</a></li>
<li><a href="#observable-last">observable.last</a></li>
<li><a href="#observable-skip">observable.skip</a></li>
<li><a href="#observable-concat">observable.concat</a></li>
<li><a href="#observable-delay">observable.delay</a></li>
<li><a href="#observable-throttle">observable.throttle</a></li>
<li><a href="#observable-debounce">observable.debounce</a></li>
<li><a href="#observable-debounceimmediate">observable.debounceImmediate</a></li>
<li><a href="#observable-bufferingthrottle">observable.bufferingThrottle</a></li>
<li><a href="#observable-doaction">observable.doAction</a></li>
<li><a href="#observable-doerror">observable.doError</a></li>
<li><a href="#observable-not">observable.not</a></li>
<li><a href="#observable-flatmap">observable.flatMap</a></li>
<li><a href="#observable-flatmaplatest">observable.flatMapLatest</a></li>
<li><a href="#observable-flatmapfirst">observable.flatMapFirst</a></li>
<li><a href="#observable-flatmaperror">observable.flatMapError</a></li>
<li><a href="#observable-flatmapwithconcurrencylimit">observable.flatMapWithConcurrencyLimit</a></li>
<li><a href="#observable-flatmapconcat">observable.flatMapConcat</a></li>
<li><a href="#observable-scan">observable.scan</a></li>
<li><a href="#observable-fold">observable.fold</a></li>
<li><a href="#observable-reduce">observable.reduce</a></li>
<li><a href="#observable-diff">observable.diff</a></li>
<li><a href="#observable-zip">observable.zip</a></li>
<li><a href="#observable-slidingwindow">observable.slidingWindow</a></li>
<li><a href="#observable-log">observable.log</a></li>
<li><a href="#observable-dolog">observable.doLog</a></li>
<li><a href="#observable-combine">observable.combine</a></li>
<li><a href="#observable-withstatemachine">observable.withStateMachine</a></li>
<li><a href="#observable-decode">observable.decode</a></li>
<li><a href="#observable-awaiting">observable.awaiting</a></li>
<li><a href="#observable-endonerror">observable.endOnError</a></li>
<li><a href="#observable-endonerror-f">observable.endOnError</a></li>
<li><a href="#observable-withhandler">observable.withHandler</a></li>
<li><a href="#observable-name">observable.name</a></li>
<li><a href="#observable-withdescription">observable.withDescription</a></li>
<li><a href="#observable-groupby">observable.groupBy</a></li>
</ul></li>
<li><a href="#eventstream">EventStream</a>
<ul>
<li><a href="#bacon-eventstream">Bacon.EventStream</a></li>
<li><a href="#stream-merge">stream.merge</a></li>
<li><a href="#stream-holdwhen">stream.holdWhen</a></li>
<li><a href="#stream-startwith">stream.startWith</a></li>
<li><a href="#stream-skipwhile">stream.skipWhile</a></li>
<li><a href="#stream-skipwhile-property">stream.skipWhile</a></li>
<li><a href="#stream-skipuntil">stream.skipUntil</a></li>
<li><a href="#stream-bufferwithtime">stream.bufferWithTime</a></li>
<li><a href="#stream-bufferwithtime-f">stream.bufferWithTime</a></li>
<li><a href="#stream-bufferwithcount">stream.bufferWithCount</a></li>
<li><a href="#stream-bufferwithtimeorcount">stream.bufferWithTimeOrCount</a></li>
<li><a href="#stream-toproperty">stream.toProperty</a></li>
<li><a href="#stream-toproperty-initialValue">stream.toProperty</a></li>
<li><a href="#stream-flatscan">stream.flatScan</a></li>
</ul></li>
<li><a href="#property">Property</a>
<ul>
<li><a href="#bacon-property">Bacon.Property</a></li>
<li><a href="#bacon-constant">Bacon.constant</a></li>
<li><a href="#property-assign">property.assign</a></li>
<li><a href="#property-sample">property.sample</a></li>
<li><a href="#property-sampledby">property.sampledBy</a></li>
<li><a href="#property-sampledby-property">property.sampledBy</a></li>
<li><a href="#property-sampledby-f">property.sampledBy</a></li>
<li><a href="#property-changes">property.changes</a></li>
<li><a href="#property-and">property.and</a></li>
<li><a href="#property-or">property.or</a></li>
<li><a href="#property-startwith">property.startWith</a></li>
</ul></li>
<li><a href="#combining-multiple-streams-and-properties">Combining multiple streams and properties</a>
<ul>
<li><a href="#bacon-combineasarray">Bacon.combineAsArray</a></li>
<li><a href="#bacon-combineasarray-multiple-streams">Bacon.combineAsArray</a></li>
<li><a href="#bacon-combinewith">Bacon.combineWith</a></li>
<li><a href="#bacon-combinewith-streams-array">Bacon.combineWith</a></li>
<li><a href="#bacon-combinewith-streams-array-f-last">Bacon.combineWith</a></li>
<li><a href="#bacon-combinewith-f-last">Bacon.combineWith</a></li>
<li><a href="#bacon-combinetemplate">Bacon.combineTemplate</a></li>
<li><a href="#bacon-mergeall">Bacon.mergeAll</a></li>
<li><a href="#bacon-concatall">Bacon.concatAll</a></li>
<li><a href="#bacon-zipasarray">Bacon.zipAsArray</a></li>
<li><a href="#bacon-zipasarray-multiple-streams">Bacon.zipAsArray</a></li>
<li><a href="#bacon-zipwith">Bacon.zipWith</a></li>
<li><a href="#bacon-zipwith-f-first">Bacon.zipWith</a></li>
<li><a href="#bacon-zipwith-f-first-varargs">Bacon.zipWith</a></li>
<li><a href="#bacon-zipwith-varargs-f-last">Bacon.zipWith</a></li>
<li><a href="#bacon-onvalues">Bacon.onValues</a></li>
</ul></li>
<li><a href="#function-construction-rules">Function Construction rules</a></li>
<li><a href="#lazy-evaluation">Lazy evaluation</a></li>
<li><a href="#latest-value-of-property-or-eventstream">Latest value of Property or EventStream</a></li>
<li><a href="#bus">Bus</a>
<ul>
<li><a href="#new-bacon-bus">new Bacon.Bus</a></li>
<li><a href="#bus-push">bus.push</a></li>
<li><a href="#bus-end">bus.end</a></li>
<li><a href="#bus-error">bus.error</a></li>
<li><a href="#bus-plug">bus.plug</a></li>
</ul></li>
<li><a href="#event">Event</a>
<ul>
<li><a href="#bacon-event">Bacon.Event</a></li>
<li><a href="#bacon-next">Bacon.Next</a></li>
<li><a href="#bacon-end">Bacon.End</a></li>
<li><a href="#bacon-error">Bacon.Error</a></li>
<li><a href="#bacon-initial">Bacon.Initial</a></li>
<li><a href="#event-properties-and-methods">Event properties and methods</a></li>
<li><a href="#event-value">event.value</a></li>
<li><a href="#event-hasvalue">event.hasValue</a></li>
<li><a href="#event-isnext">event.isNext</a></li>
<li><a href="#event-isinitial">event.isInitial</a></li>
<li><a href="#event-iserror">event.isError</a></li>
<li><a href="#event-isend">event.isEnd</a></li>
<li><a href="#event-error">event.error</a></li>
</ul></li>
<li><a href="#errors">Errors</a>
<ul>
<li><a href="#bacon-retry">Bacon.retry</a></li>
</ul></li>
<li><a href="#join-patterns">Join Patterns</a>
<ul>
<li><a href="#bacon-when">Bacon.when</a></li>
<li><a href="#bacon-update">Bacon.update</a></li>
<li><a href="#join-patterns-as-a-chemical-machine">Join patterns as a "chemical machine"</a></li>
<li><a href="#join-patterns-and-properties">Join patterns and properties</a></li>
<li><a href="#join-patterns-and-baconbus">Join patterns and Bacon.bus</a></li>
</ul></li>
<li><a href="#introspection-and-metadata">Introspection and metadata</a>
<ul>
<li><a href="#observable-tostring">observable.toString</a></li>
<li><a href="#observable-deps">observable.deps</a></li>
<li><a href="#observable-internaldeps">observable.internalDeps</a></li>
<li><a href="#observable-desc">observable.desc</a></li>
<li><a href="#bacon-spy">Bacon.spy</a></li>
</ul></li>
<li><a href="#cleaning-up">Cleaning up</a></li>
<li><a href="#eventstream-and-property-semantics">EventStream and Property semantics</a></li>
<li><a href="#atomic-updates">Atomic updates</a></li>
<li><a href="#for-rxjs-users">For RxJs Users</a></li>
</ul>
<p> <a href="api2.html"> API docs <small>(2.0)</small> </a> </p>
<p> <a href="api3/index.html"> API docs <small>(3.0)</small> </a> </p>
<p> <a href="tutorials.html"> Tutorials </a> </p>
<p> <a href="https://github.com/baconjs/bacon.js#install">Install/Download</a> </p>
</div>
<div class="large-12 small-6 columns">
<p> <a href="https://github.com/baconjs/bacon.js/wiki/FAQ">FAQ</a> </p>
</div>
<div class="large-12 small-6 columns">
<p><a href="https://reaktor.com/"><img src="supported-by-reaktor.png" class="sponsor reaktor"></a></p>
</div>
</div>
</div>
</div>
<div class="large-8 columns">
<div class="main">
<h1>API</h1>
<h2><a name="creating-streams"></a>Creating streams</h2>
<p><a name="$-aseventstream"></a>
<a href="#$-aseventstream" title="$.asEventStream(eventName : String)"><code>$.asEventStream(eventName)</code></a> creates an EventStream from events on a
jQuery or Zepto.js object. You can pass optional arguments to add a
jQuery live selector and/or a function that processes the jQuery
event and its parameters, if given, like this:</p>
<pre><code class="language-js"><textarea class="code">$("#my-div").asEventStream("click", ".more-specific-selector")
$("#my-div").asEventStream("click", ".more-specific-selector", function(event, args) { return args[0] })
$("#my-div").asEventStream("click", function(event, args) { return args[0] })
</textarea></code></pre>
<p><a name="bacon-frompromise"></a>
<a href="#bacon-frompromise" title="Bacon.fromPromise(promise : Promise[A] [, abort : boolean][, eventTransformer]) : EventStream[A]"><code>Bacon.fromPromise(promise [, abort] [, eventTransformer])</code></a> creates an EventStream from a Promise object such as JQuery Ajax.
This stream will contain a single value or an error, followed immediately by stream end.
You can use the optional abort flag (i.e. ´fromPromise(p, true)´ to have the <code>abort</code> method of the given promise be called when all subscribers have been removed from the created stream.
You can also pass an optional function that transforms the promise value into Events. The default is to transform the value into <code>[new Bacon.Next(value), new Bacon.End()]</code>.
Check out this <a href="https://github.com/raimohanska/baconjs-examples/blob/master/resources/public/index.html">example</a>.</p>
<p><a name="bacon-fromevent"></a>
<a href="#bacon-fromevent" title="Bacon.fromEvent(target : EventTarget | EventEmitter, eventName : String [, eventTransformer]) : EventStream"><code>Bacon.fromEvent(target, eventName [, eventTransformer])</code></a> creates an EventStream from events
on a DOM EventTarget or Node.JS EventEmitter object, or an object that supports event listeners using <code>on</code>/<code>off</code> methods.
You can also pass an optional function that transforms the emitted
events' parameters.</p>
<pre><code class="language-js"><textarea class="code">Bacon.fromEvent(document.body, "click").onValue(function() { alert("Bacon!") })
</textarea></code></pre>
<p><a name="bacon-fromcallback"></a>
<a href="#bacon-fromcallback" title="Bacon.fromCallback(f : (A -> void) -> void [, args...]) : EventStream[A]"><code>Bacon.fromCallback(f [, args...])</code></a> creates an EventStream from a function that
accepts a callback. The function is supposed to call its callback just
once. For example:</p>
<pre><code class="language-js"><textarea class="code">Bacon.fromCallback(function(callback) {
setTimeout(function() {
callback("Bacon!")
}, 1000)
})
</textarea></code></pre>
<p>This would create a stream that outputs a single value "Bacon!" and ends
after that. The use of setTimeout causes the value to be delayed by 1
second.</p>
<p>You can also give any number of arguments to <a href="#bacon-fromcallback"><code>fromCallback</code></a>, which will be
passed to the function. These arguments can be simple variables, Bacon
EventStreams or Properties. For example the following will output "Bacon rules":</p>
<pre><code class="language-js"><textarea class="code">bacon = Bacon.constant('bacon')
Bacon.fromCallback(function(a, b, callback) {
callback(a + ' ' + b);
}, bacon, 'rules').log();
</textarea></code></pre>
<p><a name="bacon-fromcallback-object"></a>
<a href="#bacon-fromcallback-object" title="Bacon.fromCallback(object, methodName [, args...]) : EventStream[A]"><code>Bacon.fromCallback(object, methodName [, args...])</code></a> a variant of fromCallback which calls the named method of a given object.</p>
<p><a name="bacon-fromnodecallback"></a>
<a href="#bacon-fromnodecallback" title="Bacon.fromNodeCallback(f : (E -> A -> void) -> void [, args...]) : EventStream[A]"><code>Bacon.fromNodeCallback(f [, args...])</code></a> behaves the same way as <a href="#bacon-fromcallback"><code>Bacon.fromCallback</code></a>,
except that it expects the callback to be called in the Node.js convention:
<code>callback(error, data)</code>, where error is null if everything is fine. For example:</p>
<pre><code class="language-js"><textarea class="code">var Bacon = require('baconjs').Bacon,
fs = require('fs');
var read = Bacon.fromNodeCallback(fs.readFile, 'input.txt');
read.onError(function(error) { console.log("Reading failed: " + error); });
read.onValue(function(value) { console.log("Read contents: " + value); });
</textarea></code></pre>
<p><a name="bacon-fromesobservable"></a>
<a href="#bacon-fromesobservable" title="Bacon.fromESObservable(observable : ESObservable[A]) : EventStream[A]"><code>Bacon.fromESObservable(observable)</code></a> creates an EventStream from an
<a href="https://github.com/tc39/proposal-observable">ES Observable</a>. Input can be any
ES Observable implementation including RxJS and Kefir.</p>
<p><a name="bacon-fromnodecallback-object"></a>
<a href="#bacon-fromnodecallback-object" title="Bacon.fromNodeCallback(object, methodName [, args...])"><code>Bacon.fromNodeCallback(object, methodName [, args...])</code></a> a variant of fromNodeCallback which calls the named method of a given object.</p>
<p><a name="bacon-frompoll"></a>
<a href="#bacon-frompoll" title="Bacon.fromPoll(interval : Number, f : -> Event[A]) : EventStream[A]"><code>Bacon.fromPoll(interval, f)</code></a> polls given function with given interval.
Function should return Events: either <a href="#bacon-next"><code>Bacon.Next</code></a> or <a href="#bacon-end"><code>Bacon.End</code></a>. Polling occurs only
when there are subscribers to the stream. Polling ends permanently when
<code>f</code> returns <a href="#bacon-end"><code>Bacon.End</code></a>.</p>
<p><a name="bacon-once"></a>
<a href="#bacon-once" title="Bacon.once(value : Event[A] | A) : EventStream[A]"><code>Bacon.once(value)</code></a> creates an EventStream that delivers the given
single value for the first subscriber. The stream will end immediately
after this value. You can also send an <a href="#bacon-error"><code>Bacon.Error</code></a> event instead of a
value: <code>Bacon.once(new Bacon.Error("fail"))</code>.</p>
<p><a name="bacon-fromarray"></a>
<a href="#bacon-fromarray" title="Bacon.fromArray(values : Array[Event[A] | A]) : EventStream[A]"><code>Bacon.fromArray(values)</code></a> creates an EventStream that delivers the given
series of values (given as array) to the first subscriber. The stream ends after these
values have been delivered. You can also send <a href="#bacon-error"><code>Bacon.Error</code></a> events, or
any combination of pure values and error events like this:
`Bacon.fromArray([1, new Bacon.Error()])</p>
<p><a name="bacon-interval"></a>
<a href="#bacon-interval" title="Bacon.interval(interval : Number, value : A) : EventStream[A]"><code>Bacon.interval(interval, value)</code></a> repeats the single element
indefinitely with the given interval (in milliseconds)</p>
<p><a name="bacon-sequentially"></a>
<a href="#bacon-sequentially" title="Bacon.sequentially(interval : Number, values : Array[A]) : EventStream[A]"><code>Bacon.sequentially(interval, values)</code></a> creates a stream containing given
values (given as array). Delivered with given interval in milliseconds.</p>
<p><a name="bacon-repeatedly"></a>
<a href="#bacon-repeatedly" title="Bacon.repeatedly(interval : Number, values : Array[A]) : EventStream[A]"><code>Bacon.repeatedly(interval, values)</code></a> repeats given elements indefinitely
with given interval in milliseconds. For example, <code>repeatedly(10, [1,2,3])</code>
would lead to <code>1,2,3,1,2,3...</code> to be repeated indefinitely.</p>
<p><a name="bacon-repeat"></a>
<a href="#bacon-repeat" title="Bacon.repeat(fn: Number -> Observable[A]): EventStream[A]"><code>Bacon.repeat(fn)</code></a> Calls generator function which is expected to return an observable. The returned EventStream contains
values and errors from the spawned observable. When the spawned observable ends, the generator is called
again to spawn a new observable.</p>
<p>This is repeated until the generator returns a falsy value
(such as <code>undefined</code> or <code>false</code>).</p>
<p>The generator function is called with one argument — iteration number starting from <code>0</code>.</p>
<p>Here's an example:</p>
<pre><code class="language-js"><textarea class="code">Bacon.repeat(function(i) {
if (i < 3) {
return Bacon.once(i);
} else {
return false;
}
}).log()
</textarea></code></pre>
<p>The example will produce values 0, 1 and 2.</p>
<p><a name="bacon-never"></a>
<a href="#bacon-never" title="Bacon.never() : EventStream"><code>Bacon.never()</code></a> creates an EventStream that immediately ends.</p>
<p><a name="bacon-later"></a>
<a href="#bacon-later" title="Bacon.later(delay : Number, value : A) : EventStream[A]"><code>Bacon.later(delay, value)</code></a> creates a single-element stream that
produces given value after given delay (milliseconds).</p>
<p><a name="new-bacon-eventstream"></a>
<a href="#new-bacon-eventstream" title="new Bacon.EventStream(subscribe)"><code>new Bacon.EventStream(subscribe)</code></a> creates an <a href="#eventstream"><code>EventStream</code></a> with the given subscribe function.</p>
<p><a href="#property-changes"><code>property.changes</code></a> creates a stream of changes to the <a href="#property"><code>Property</code></a>. The stream <em>does not</em> include
an event for the current value of the Property at the time this method was called.</p>
<p><a name="property-toeventstream"></a>
<a href="#property-toeventstream" title="property.toEventStream(@ : Property[A]) : EventStream[A]"><code>property.toEventStream()</code></a> creates an EventStream based on this Property. The stream contains also an event for the current
value of this Property at the time this method was called.</p>
<p><a href="#new-bacon-bus"><code>new Bacon.Bus()</code></a> creates a pushable/pluggable stream (see <a href="#bus">Bus</a> section below)</p>
<p>Pro tip: you can also put Errors into streams created with the
constructors above, by using an <a href="#bacon-error"><code>Bacon.Error</code></a> object instead of a plain
value.</p>
<h2><a name="baconfrombinder-for-custom-streams"></a>Bacon.fromBinder for custom streams</h2>
<p>If none of the factory methods above apply, you may of course roll your own EventStream by using <a href="#bacon-frombinder"><code>Bacon.fromBinder</code></a>.</p>
<p><a name="bacon-frombinder"></a>
<a href="#bacon-frombinder" title="Bacon.fromBinder(subscribe)"><code>Bacon.fromBinder(subscribe)</code></a> The parameter <code>subscribe</code> is a function that accepts a <code>sink</code> which is a function that your <code>subscribe</code> function can "push" events to.</p>
<p>For example:</p>
<pre><code class="language-js"><textarea class="code">var stream = Bacon.fromBinder(function(sink) {
sink("first value")
sink([new Bacon.Next("2nd"), new Bacon.Next("3rd")])
sink(new Bacon.Next(function() {
return "This one will be evaluated lazily"
}))
sink(new Bacon.Error("oops, an error"))
sink(new Bacon.End())
return function() {
// unsub functionality here, this one's a no-op
}
})
stream.log()
</textarea></code></pre>
<p>As shown in the example, you can push</p>
<ul>
<li>A plain value, like <code>"first value"</code></li>
<li>An <a href="#event"><code>Event</code></a> object including <a href="#bacon-error"><code>Bacon.Error</code></a> (wraps an error) and <a href="#bacon-end"><code>Bacon.End</code></a> (indicates
stream end).</li>
<li>An array of <a href="#event">event</a> objects at once</li>
</ul>
<p>Other examples can be found on <a href="http://jsfiddle.net/PG4c4/">JSFiddle</a> and the
<a href="http://baconjs.blogspot.fi/2013/12/wrapping-things-in-bacon.html">Bacon.js blog</a>.</p>
<p>The <code>subscribe</code> function must return a function. Let's call that function
<code>unsubscribe</code>. The returned function can be used by the subscriber (directly or indirectly) to
unsubscribe from the EventStream. It should release all resources that the subscribe function reserved.</p>
<p>The <code>sink</code> function may return <a href="#bacon-nomore"><code>Bacon.noMore</code></a> (as well as <a href="#bacon-more"><code>Bacon.more</code></a>
or any other value). If it returns <a href="#bacon-nomore"><code>Bacon.noMore</code></a>, no further events will be consumed
by the subscriber. The <code>subscribe</code> function may choose to clean up all resources at this point (e.g.,
by calling <code>unsubscribe</code>). This is usually not necessary, because further calls to <code>sink</code> are ignored,
but doing so can increase performance in <a href="https://github.com/baconjs/bacon.js/issues/484">rare cases</a>.</p>
<p>The EventStream will wrap your <code>subscribe</code> function so that it will
only be called when the first stream listener is added, and the <code>unsubscribe</code>
function is called only after the last listener has been removed.
The subscribe-unsubscribe cycle may of course be repeated indefinitely,
so prepare for multiple calls to the subscribe function.</p>
<p>A note about the <code>new Bacon.Next(..)</code> constructor: You can use it like</p>
<pre><code class="language-js"><textarea class="code">new Bacon.Next("value")
</textarea></code></pre>
<p>But the canonical way would be</p>
<pre><code class="language-js"><textarea class="code">new Bacon.Next(function() { return "value"; })
</textarea></code></pre>
<p>The former version is safe only when you know that the actual value in
the stream is not a function.</p>
<p>The idea in using a function instead of a plain value is that the internals on Bacon.js take
advantage of <a href="#lazy-evaluation">lazy evaluation</a> by deferring the evaluations of values
created by <a href="#observable-map"><code>map</code></a>, <a href="#combining-multiple-streams-and-properties"><code>combine</code></a>.</p>
<p><a name="bacon-nomore"></a>
<a href="#bacon-nomore" title="Bacon.noMore"><code>Bacon.noMore</code></a> The opaque value <code>sink</code> function may return. See <a href="#bacon-frombinder"><code>Bacon.fromBinder</code></a>.</p>
<p><a name="bacon-more"></a>
<a href="#bacon-more" title="Bacon.more"><code>Bacon.more</code></a> The opaque value <code>sink</code> function may return. See <a href="#bacon-frombinder"><code>Bacon.fromBinder</code></a>.</p>
<h2><a name="common-methods-in-eventstreams-and-properties"></a>Common methods in EventStreams and Properties</h2>
<p>Both EventStream and Property share the Observable interface, and hence share a lot of methods.
Methods typically return observables so that methods can be chained; exceptions are noted.
Common methods are listed below.</p>
<p><a name="observable-subscribe"></a>
<a href="#observable-subscribe" title="observable.subscribe(f)"><code>observable.subscribe(f)</code></a> subscribes given handler function to event stream. Function will receive <a href="#event">event</a> objects
for all new value, end and error events in the stream.
The subscribe() call returns a <code>unsubscribe</code> function that you can call to unsubscribe.
You can also unsubscribe by returning <a href="#bacon-nomore"><code>Bacon.noMore</code></a> from the handler function as a reply
to an Event.
<code>stream.subscribe</code> and <code>property.subscribe</code> behave similarly, except that the latter also
pushes the initial value of the property, in case there is one.</p>
<p><a name="observable-onvalue"></a>
<a href="#observable-onvalue" title="observable.onValue(@ : Observable[A], f : A -> void) : Unsubscriber"><code>observable.onValue(f)</code></a> subscribes a given handler function to the observable. Function will be called for each new value.
This is the simplest way to assign a side-effect to an observable. The difference
to the <code>subscribe</code> method is that the actual stream values are
received, instead of <a href="#event"><code>Event</code></a> objects.
The <a href="#function-construction-rules">Function Construction rules</a> below apply here.
Just like <code>subscribe</code>, this method returns a function for unsubscribing.
<code>stream.onValue</code> and <code>property.onValue</code> behave similarly, except that the latter also
pushes the initial value of the property, in case there is one.</p>
<p><a name="observable-onvalues"></a>
<a href="#observable-onvalues" title="observable.onValues(f)"><code>observable.onValues(f)</code></a> like <a href="#stream-onvalue"><code>onValue</code></a>, but splits the value (assuming its an
array) as function arguments to <code>f</code>.</p>
<p><a name="observable-onerror"></a>
<a href="#observable-onerror" title="observable.onError(@ : Observable[A], f : Error -> void) : Unsubscriber"><code>observable.onError(f)</code></a> subscribes a callback to error events. The function will be called for each error in the stream.
Just like <code>subscribe</code>, this method returns a function for unsubscribing.</p>
<p><a name="observable-onend"></a>
<a href="#observable-onend" title="observable.onEnd(f : -> void) : Unsubscriber"><code>observable.onEnd(f)</code></a> subscribes a callback to stream end. The function will be called when the stream ends.
Just like <code>subscribe</code>, this method returns a function for unsubscribing.</p>
<p><a name="observable-topromise"></a>
<a href="#observable-topromise" title="observable.toPromise(@ : Observable[A] [, PromiseCtr]) : Promise[A]"><code>observable.toPromise([PromiseCtr])</code></a> returns a Promise which will be resolved with the last event coming from an Observable.
The global ES6 promise implementation will be used unless a promise constructor is given.
Use a shim if you need to support legacy browsers or platforms.
<a href="http://caniuse.com/#feat=promises">caniuse promises</a>.</p>
<p><a name="observable-firsttopromise"></a>
<a href="#observable-firsttopromise" title="observable.firstToPromise(@ : Observable[A] [, PromiseCtr]) : Promise[A]"><code>observable.firstToPromise([PromiseCtr])</code></a> returns a Promise which will be resolved with the first event coming from an Observable.
Like <a href="#observable-topromise"><code>toPromise</code></a>, the global ES6 promise implementation will be used unless a promise
constructor is given.</p>
<p><a name="observable-toesobservable"></a>
<a href="#observable-toesobservable" title="observable.toESObservable() : ESObservable[A]"><code>observable.toESObservable()</code></a> Aliased as <code>observable[Symbol.observable]()</code>. Returns an
<a href="https://github.com/zenparsing/es-observable">ES Observable</a> containing the
events from Bacon observable. This allows Bacon observables to be used with
<code>Observable.from</code> and provides interoperability with other ES observable
implementations such as RxJS and Kefir.</p>
<p><a name="observable-map"></a>
<a href="#observable-map" title="observable.map(@ : Observable[A], f : A -> B) : Observable[B]"><code>observable.map(f)</code></a> maps values using given function, returning a new
stream/property. Instead of a function, you can also provide a constant
value. Further, you can use a property extractor string like
".keyCode". So, if f is a string starting with a
dot, the elements will be mapped to the corresponding field/function in the event
value. For instance map(".keyCode") will pluck the keyCode field from
the input values. If keyCode was a function, the result stream would
contain the values returned by the function.
The <a href="#function-construction-rules">Function Construction rules</a> below apply here.
The <a href="#observable-map"><code>map</code></a> method, among many others, uses <a href="#lazy-evaluation">lazy evaluation</a>.</p>
<p><a name="stream-map"></a>
<a href="#stream-map" title="stream.map(property)"><code>stream.map(property)</code></a> maps the stream events to the current value of
the given property. This is equivalent to <a href="#property-sampledby"><code>property.sampledBy(stream)</code></a>.</p>
<p><a name="observable-maperror"></a>
<a href="#observable-maperror" title="observable.mapError(@ : Observable[A], f : E -> A) : Observable[A]"><code>observable.mapError(f)</code></a> maps errors using given function. More
specifically, feeds the "error" field of the error event to the function
and produces a <a href="#bacon-next"><code>Next</code></a> event based on the return value.
The <a href="#function-construction-rules">Function Construction rules</a> below apply here.
You can omit the argument to produce a <a href="#bacon-next"><code>Next</code></a> event with <code>undefined</code> value.</p>
<p><a name="observable-errors"></a>
<a href="#observable-errors" title="observable.errors(@ : Observable[A]) : Observable[A]"><code>observable.errors()</code></a> returns a stream containing <a href="#bacon-error"><code>Error</code></a> events only.
Same as filtering with a function that always returns false.</p>
<p><a name="observable-skiperrors"></a>
<a href="#observable-skiperrors" title="observable.skipErrors(@ : Observable[A]) : Observable[A]"><code>observable.skipErrors()</code></a> skips all errors.</p>
<p><a name="observable-mapend"></a>
<a href="#observable-mapend" title="observable.mapEnd(@ : Observable[A], f : -> Observable[A]) : Observable[A]"><code>observable.mapEnd(f)</code></a> Adds an extra <a href="#bacon-next"><code>Next</code></a> event just before End. The value is created
by calling the given function when the source stream ends. Instead of a
function, a static value can be used. You can omit the argument to
produce a Next event with <code>undefined</code> value.</p>
<p><a name="observable-filter"></a>
<a href="#observable-filter" title="observable.filter(@ : Observable[A], f : A -> Bool) : Observable[A]"><code>observable.filter(f)</code></a> filters values using given predicate function.
Instead of a function, you can use a constant value (<code>true</code> to include all, <code>false</code> to exclude all) or a
property extractor string (like ".isValuable") instead. Just like with
<a href="#observable-map"><code>map</code></a>, indeed.</p>
<p><a name="observable-filter-property"></a>
<a href="#observable-filter-property" title="observable.filter(property)"><code>observable.filter(property)</code></a> filters values based on the value of a
property. Event will be included in output <a href="http://en.wikipedia.org/wiki/If_and_only_if">if and only if</a> the property holds <code>true</code>
at the time of the event.</p>
<p><a name="observable-skipduplicates"></a>
<a href="#observable-skipduplicates" title="observable.skipDuplicates([isEqual])"><code>observable.skipDuplicates(isEqual)</code></a> drops consecutive equal elements. So,
from <code>[1, 2, 2, 1]</code> you'd get <code>[1, 2, 1]</code>. Uses the <code>===</code> operator for equality
checking by default. If the isEqual argument is supplied, checks by calling
isEqual(oldValue, newValue). For instance, to do a deep comparison,you can
use the isEqual function from <a href="http://underscorejs.org/">underscore.js</a>
like <code>stream.skipDuplicates(_.isEqual)</code>.</p>
<p><a name="observable-take"></a>
<a href="#observable-take" title="observable.take(@ : Observable[A], n : Number) : Observable[A]"><code>observable.take(n)</code></a> takes at most n values from the stream and then ends the stream. If the stream has
fewer than n values then it is unaffected.
Equal to <a href="#bacon-never"><code>Bacon.never()</code></a> if <code>n <= 0</code>.</p>
<p><a name="observable-takeuntil"></a>
<a href="#observable-takeuntil" title="observable.takeUntil(@ : Observable[A], stream : EventStream[B]) : Observable[A]"><code>observable.takeUntil(stream)</code></a> takes elements from source until a Next event appears in the other stream.
If other stream ends without value, it is ignored.</p>
<p><a name="observable-takewhile"></a>
<a href="#observable-takewhile" title="observable.takeWhile(@ : Observable[A], f : A -> Bool) : Observable[A]"><code>observable.takeWhile(f)</code></a> takes while given predicate function holds true, and then ends.
<a href="#function-construction-rules">Function Construction rules</a> apply.</p>
<p><a name="observable-takewhile-property"></a>
<a href="#observable-takewhile-property" title="observable.takeWhile(property)"><code>observable.takeWhile(property)</code></a> takes values while the value of a property holds true, and then ends.</p>
<p><a name="observable-first"></a>
<a href="#observable-first" title="observable.first(@ : Observable[A]) : Observable[A]"><code>observable.first()</code></a> takes the first element from the stream. Essentially <code>observable.take(1)</code>.</p>
<p><a name="observable-last"></a>
<a href="#observable-last" title="observable.last(@ : Observable[A]) : Observable[A]"><code>observable.last()</code></a> takes the last element from the stream. None, if stream is empty.</p>
<p><em>Note:</em> <code>neverEndingStream.last()</code> creates the stream which doesn't produce any events and never ends.</p>
<p><a name="observable-skip"></a>
<a href="#observable-skip" title="observable.skip(n)"><code>observable.skip(n)</code></a> skips the first n elements from the stream</p>
<p><a name="observable-concat"></a>
<a href="#observable-concat" title="observable.concat(other)"><code>observable.concat(other)</code></a> concatenates two streams/properties into one stream/property so that
it will deliver events from <code>observable</code> until it ends and then deliver
events from <code>other</code>. This means too that events from <code>other</code>,
occurring before the end of <code>observable</code> will not be included in the result
stream/property.</p>
<div class="bacon-marble">
<div class="bacon-input" x-bacon-input="Bacon.sequentially(200, [9,0,2]).filter(function(x) { return x })"></div>
<div class="bacon-input" x-bacon-input="Bacon.sequentially(200, [0,1,0,12,8,0]).filter(function(x) { return x })"></div>
<div class="bacon-output" x-bacon-output="function(a,b) { return a.concat(b) }"></div>
</div>
<p><a name="observable-delay"></a>
<a href="#observable-delay" title="observable.delay(delay)"><code>observable.delay(delay)</code></a> delays the stream/property by given amount of milliseconds. Does not delay the initial value of a <a href="#property"><code>Property</code></a>.</p>
<pre><code class="language-js"><textarea class="code">var delayed = source.delay(2)
</textarea></code></pre>
<pre><code><textarea class="code">source: asdf----asdf----
delayed: --asdf----asdf--
</textarea></code></pre>
<p><a name="observable-throttle"></a>
<a href="#observable-throttle" title="observable.throttle(delay)"><code>observable.throttle(delay)</code></a> throttles stream/property by given amount
of milliseconds. Events are emitted with the minimum interval of
<a href="#observable-delay"><code>delay</code></a>. The implementation is based on <a href="#stream-bufferwithtime"><code>stream.bufferWithTime</code></a>.
Does not affect emitting the initial value of a <a href="#property"><code>Property</code></a>.</p>
<p>Example:</p>
<pre><code class="language-js"><textarea class="code">var throttled = source.throttle(2)
</textarea></code></pre>
<pre><code><textarea class="code">source: asdf----asdf----
throttled: --s--f----s--f--
</textarea></code></pre>
<p><a name="observable-debounce"></a>
<a href="#observable-debounce" title="observable.debounce(delay)"><code>observable.debounce(delay)</code></a> throttles stream/property by given amount
of milliseconds, but so that event is only emitted after the given
"quiet period". Does not affect emitting the initial value of a Property.
The difference of <a href="#observable-throttle"><code>throttle</code></a> and <a href="#observable-debounce"><code>debounce</code></a> is the same as it is in the
same methods in jQuery.</p>
<p>Example:</p>
<pre><code><textarea class="code">source: asdf----asdf----
source.debounce(2): -----f-------f--
</textarea></code></pre>
<p><a name="observable-debounceimmediate"></a>
<a href="#observable-debounceimmediate" title="observable.debounceImmediate(delay)"><code>observable.debounceImmediate(delay)</code></a> passes the first event in the
stream through, but after that, only passes events after a given number
of milliseconds have passed since previous output.</p>
<p>Example:</p>
<pre><code><textarea class="code">source: asdf----asdf----
source.debounceImmediate(2): a-d-----a-d-----
</textarea></code></pre>
<p><a name="observable-bufferingthrottle"></a>
<a href="#observable-bufferingthrottle" title="observable.bufferingThrottle(@ : Observable[A], minimumInterval) : EventStream[A]"><code>observable.bufferingThrottle(minimumInterval)</code></a> throttles the observable using a buffer so that at most one value event in minimumInteval is issued.
Unlike <a href="#observable-throttle"><code>throttle</code></a>, it doesn't discard the excessive events but buffers them instead, outputting
them with a rate of at most one value per minimumInterval.</p>
<p>Example:</p>
<pre><code class="language-js"><textarea class="code">var throttled = source.bufferingThrottle(2)
</textarea></code></pre>
<pre><code><textarea class="code">source: asdf----asdf----
throttled: a-s-d-f-a-s-d-f-
</textarea></code></pre>
<p><a name="observable-doaction"></a>
<a href="#observable-doaction" title="observable.doAction(f)"><code>observable.doAction(f)</code></a> returns a stream/property where the function f
is executed for each value, before dispatching to subscribers. This is
useful for debugging, but also for stuff like calling the
<code>preventDefault()</code> method for events. In fact, you can
also use a property-extractor string instead of a function, as in
<code>".preventDefault"</code>.</p>
<p>Please note that for Properties, it's not guaranteed that the function will be called exactly once
per event; when a Property loses all of its subscribers it will re-emit its current value when a
new subscriber is added.</p>
<p><a name="observable-doerror"></a>
<a href="#observable-doerror" title="observable.doError(f)"><code>observable.doError(f)</code></a> returns a stream/property where the function f
is executed for each error, before dispatching to subscribers.
That is, same as <a href="#observable-doaction"><code>doAction</code></a> but for errors.</p>
<p><a name="observable-not"></a>
<a href="#observable-not" title="observable.not(@ : Obserable[A]) : Observable[Bool]"><code>observable.not()</code></a> returns a stream/property that inverts boolean values</p>
<p><a name="observable-flatmap"></a>
<a href="#observable-flatmap" title="observable.flatMap(@ : Observable[A], f : A -> Observable[B] | Event[B] | B) : EventStream[B]"><code>observable.flatMap(f)</code></a> for each element in the source stream, spawn a new
stream using the function <code>f</code>. Collect events from each of the spawned
streams into the result <a href="#eventstream"><code>EventStream</code></a>. Note that instead of a function, you can provide a
stream/property too. Also, the return value of function <code>f</code> can be either an
<code>Observable</code> (stream/property) or a constant value. The result of
<a href="#observable-flatmap"><code>flatMap</code></a> is always an <a href="#eventstream"><code>EventStream</code></a>.</p>
<p>The <a href="#function-construction-rules">Function Construction rules</a> below apply here.</p>
<p><code>stream.flatMap()</code> can be used conveniently with <a href="#bacon-once"><code>Bacon.once()</code></a> and <a href="#bacon-never"><code>Bacon.never()</code></a> for converting and filtering at the same time, including only some of the results.</p>
<p>Example - converting strings to integers, skipping empty values:</p>
<pre><code class="language-js"><textarea class="code">stream.flatMap(function(text) {
return (text != "") ? parseInt(text) : Bacon.never()
})
</textarea></code></pre>
<p><a name="observable-flatmaplatest"></a>
<a href="#observable-flatmaplatest" title="observable.flatMapLatest(f)"><code>observable.flatMapLatest(f)</code></a> like <a href="#observable-flatmap"><code>flatMap</code></a>, but instead of including events from
all spawned streams, only includes them from the latest spawned stream.
You can think this as switching from stream to stream.
Note that instead of a function, you can provide a stream/property too.</p>
<p>The <a href="#function-construction-rules">Function Construction rules</a> below apply here.</p>
<p><a name="observable-flatmapfirst"></a>
<a href="#observable-flatmapfirst" title="observable.flatMapFirst(f)"><code>observable.flatMapFirst(f)</code></a> like <a href="#observable-flatmap"><code>flatMap</code></a>, but only spawns a new
stream if the previously spawned stream has ended.</p>
<p>The <a href="#function-construction-rules">Function Construction rules</a> below apply here.</p>
<p><a name="observable-flatmaperror"></a>
<a href="#observable-flatmaperror" title="observable.flatMapError(f)"><code>observable.flatMapError(f)</code></a> like <a href="#observable-flatmap"><code>flatMap</code></a>, but is applied only on <a href="#bacon-error"><code>Error</code></a> events. Returned values go into the
value stream, unless an error event is returned. As an example, one type of error could result in a retry and another just
passed through, which can be implemented using flatMapError.</p>
<p><a name="observable-flatmapwithconcurrencylimit"></a>
<a href="#observable-flatmapwithconcurrencylimit" title="observable.flatMapWithConcurrencyLimit(@ : Observable[A], limit : Number, f : A -> Observable[B] | Event[B] | B) : EventStream[B]"><code>observable.flatMapWithConcurrencyLimit(limit, f)</code></a> a super method of <em>flatMap</em> family. It limits the number of open spawned streams and buffers incoming events.
<a href="#observable-flatmapconcat"><code>flatMapConcat</code></a> is <code>flatMapWithConcurrencyLimit(1)</code> (only one input active),
and <a href="#observable-flatmap"><code>flatMap</code></a> is <code>flatMapWithConcurrencyLimit ∞</code> (all inputs are piped to output).</p>
<p>The <a href="#function-construction-rules">Function Construction rules</a> below apply here.</p>
<p><a name="observable-flatmapconcat"></a>
<a href="#observable-flatmapconcat" title="observable.flatMapConcat(@ : Observable[A], f : A -> Observable[B] | Event[B] | B) : EventStream[B]"><code>observable.flatMapConcat(f)</code></a> a <a href="#observable-flatmapwithconcurrencylimit"><code>flatMapWithConcurrencyLimit</code></a> with limit of 1.</p>
<p>The <a href="#function-construction-rules">Function Construction rules</a> below apply here.</p>
<p><a name="observable-scan"></a>
<a href="#observable-scan" title="observable.scan(seed, f) : Property[A]"><code>observable.scan(seed, f)</code></a> scans stream/property with given seed value and
accumulator function, resulting to a Property. For example, you might
use zero as seed and a "plus" function as the accumulator to create
an "integral" property. Instead of a function, you can also supply a
method name such as ".concat", in which case this method is called on
the accumulator value and the new stream value is used as argument.</p>
<p>Example:</p>
<pre><code class="language-js"><textarea class="code">var plus = function (a,b) { return a + b }
Bacon.sequentially(1, [1,2,3]).scan(0, plus)
</textarea></code></pre>
<p>This would result to following elements in the result stream:</p>
<pre><code>seed value = 0
0 + 1 = 1
1 + 2 = 3
3 + 3 = 6
</code></pre>
<p>When applied to a Property as in <code>r = p.scan(seed, f)</code>, there's a (hopefully insignificant) catch:
The starting value for <code>r</code> depends on whether <code>p</code> has an
initial value when scan is applied. If there's no initial value, this works
identically to EventStream.scan: the <code>seed</code> will be the initial value of
<code>r</code>. However, if <code>r</code> already has a current/initial value <code>x</code>, the
seed won't be output as is. Instead, the initial value of <code>r</code> will be <code>f(seed, x)</code>. This makes sense,
because there can only be 1 initial value for a Property at a time.</p>
<p><a name="observable-fold"></a>
<a href="#observable-fold" title="observable.fold(seed, f) : Property[A]"><code>observable.fold(seed, f)</code></a> is like <a href="#observable-scan"><code>scan</code></a> but only emits the final
value, i.e. the value just before the observable ends. Returns a
<a href="#property"><code>Property</code></a>.</p>
<p><a name="observable-reduce"></a>
<a href="#observable-reduce" title="observable.reduce(seed,f)"><code>observable.reduce(seed, f)</code></a> synonym for <a href="#observable-fold"><code>fold</code></a>.</p>
<p><a name="observable-diff"></a>
<a href="#observable-diff" title="observable.diff(start, f)"><code>observable.diff(start, f)</code></a> returns a Property that represents the result of a comparison
between the previous and current value of the Observable. For the initial value of the Observable,
the previous value will be the given start.</p>
<p>Example:</p>
<pre><code class="language-js"><textarea class="code">var distance = function (a,b) { return Math.abs(b - a) }
Bacon.sequentially(1, [1,2,3]).diff(0, distance)
</textarea></code></pre>
<p>This would result to following elements in the result stream:</p>
<pre><code>1 - 0 = 1
2 - 1 = 1
3 - 2 = 1</code></pre>
<p><a name="observable-zip"></a>
<a href="#observable-zip" title="observable.zip(other [, f])"><code>observable.zip(other [, f])</code></a> return an EventStream with elements
pair-wise lined up with events from this and the other EventStream or Property.
A zipped stream will publish only when it has a value from each
source and will only produce values up to when any single source ends.</p>
<p>The given function <code>f</code> is used to create the result value from value in the two
sources. If no function is given, the values are zipped into an array.</p>
<p>Be careful not to have too much "drift" between streams. If one stream
produces many more values than some other excessive buffering will
occur inside the zipped observable.</p>
<p>Example 1:</p>
<pre><code class="language-js"><textarea class="code">var x = Bacon.fromArray([1, 2])
var y = Bacon.fromArray([3, 4])
x.zip(y, function(x, y) { return x + y })
# produces values 4, 6
</textarea></code></pre>
<p>See also <a href="#bacon-zipwith"><code>zipWith</code></a> and <a href="#bacon-zipasarray"><code>zipAsArray</code></a> for zipping more than 2 sources.</p>
<p><a name="observable-slidingwindow"></a>
<a href="#observable-slidingwindow" title="observable.slidingWindow(max[, min])"><code>observable.slidingWindow(max [, min])</code></a> returns a Property that represents a
"sliding window" into the history of the values of the Observable. The
result Property will have a value that is an array containing the last <code>n</code>
values of the original observable, where <code>n</code> is at most the value of the
<code>max</code> argument, and at least the value of the <code>min</code> argument. If the
<code>min</code> argument is omitted, there's no lower limit of values.</p>
<p>For example, if you have a stream <code>s</code> with value a sequence 1 - 2 - 3 - 4 - 5, the
respective values in <code>s.slidingWindow(2)</code> would be [] - [1] - [1,2] -
[2,3] - [3,4] - [4,5]. The values of <code>s.slidingWindow(2,2)</code>would be
[1,2] - [2,3] - [3,4] - [4,5].</p>
<p><a name="observable-log"></a>
<a href="#observable-log" title="observable.log()"><code>observable.log()</code></a> logs each value of the Observable to the console.
It optionally takes arguments to pass to console.log() alongside each
value. To assist with chaining, it returns the original Observable. Note
that as a side-effect, the observable will have a constant listener and
will not be garbage-collected. So, use this for debugging only and
remove from production code. For example:</p>
<pre><code class="language-js"><textarea class="code">myStream.log("New event in myStream")
</textarea></code></pre>
<p>or just</p>
<pre><code class="language-js"><textarea class="code">myStream.log()
</textarea></code></pre>
<p><a name="observable-dolog"></a>
<a href="#observable-dolog" title="observable.doLog()"><code>observable.doLog()</code></a> logs each value of the Observable to the console. doLog() behaves like <a href="#observable-log"><code>log</code></a>
but does not subscribe to the event stream. You can think of doLog() as a
logger function that – unlike log() – is safe to use in production. doLog() is
safe, because it does not cause the same surprising side-effects as log()
does.</p>
<p><a name="observable-combine"></a>
<a href="#observable-combine" title="observable.combine(property2, f)"><code>observable.combine(property2, f)</code></a> combines the latest values of the two
streams or properties using a two-arg function. Similarly to <a href="#observable-scan"><code>scan</code></a>, you can use a
method name instead, so you could do <code>a.combine(b, ".concat")</code> for two
properties with array value. The result is a Property.</p>
<p><a name="observable-withstatemachine"></a>
<a href="#observable-withstatemachine" title="observable.withStateMachine(initState, f)"><code>observable.withStateMachine(initState, f)</code></a> lets you run a state machine
on an observable. Give it an initial state object and a state
transformation function that processes each incoming event and
returns an array containing the next state and an array of output
events. Here's an example where we calculate the total sum of all
numbers in the stream and output the value on stream end:</p>
<pre><code class="language-js"><textarea class="code">Bacon.fromArray([1,2,3])
.withStateMachine(0, function(sum, event) {
if (event.hasValue())
return [sum + event.value(), []]
else if (event.isEnd())
return [undefined, [new Bacon.Next(sum), event]]
else
return [sum, [event]]
})
</textarea></code></pre>
<p><a name="observable-decode"></a>
<a href="#observable-decode" title="observable.decode(mapping)"><code>observable.decode(mapping)</code></a> decodes input using the given mapping. Is a
bit like a switch-case or the decode function in Oracle SQL. For
example, the following would map the value 1 into the string "mike"
and the value 2 into the value of the <code>who</code> property.</p>
<pre><code class="language-js"><textarea class="code">property.decode({1 : "mike", 2 : who})
</textarea></code></pre>
<p>This is actually based on <a href="#bacon-combinetemplate"><code>combineTemplate</code></a> so you can compose static
and dynamic data quite freely, as in</p>
<pre><code class="language-js"><textarea class="code">property.decode({1 : { type: "mike" }, 2 : { type: "other", whoThen : who }})
</textarea></code></pre>
<p>The return value of <a href="#observable-decode"><code>decode</code></a> is always a <a href="#property"><code>Property</code></a>.</p>
<p><a name="observable-awaiting"></a>
<a href="#observable-awaiting" title="observable.awaiting(otherObservable)"><code>observable.awaiting(otherObservable)</code></a> creates a Property that indicates whether
<code>observable</code> is awaiting <code>otherObservable</code>, i.e. has produced a value after the latest
value from <code>otherObservable</code>. This is handy for keeping track whether we are
currently awaiting an AJAX response:</p>
<pre><code class="language-js"><textarea class="code">var showAjaxIndicator = ajaxRequest.awaiting(ajaxResponse)
</textarea></code></pre>
<p><a name="observable-endonerror"></a>
<a href="#observable-endonerror" title="observable.endOnError()"><code>observable.endOnError()</code></a> ends the <code>Observable</code> on first <a href="#bacon-error"><code>Error</code></a> event. The
error is included in the output of the returned <code>Observable</code>.</p>
<p><a name="observable-endonerror-f"></a>
<a href="#observable-endonerror-f" title="observable.endOnError(f)"><code>observable.endOnError(f)</code></a> ends the <code>Observable</code> on first <a href="#bacon-error"><code>Error</code></a> event for which
the given predicate function returns true. The error is included in the
output of the returned <code>Observable</code>. The <a href="#function-construction-rules">Function Construction rules</a> apply, so
you can do for example <code>.endOnError(".serious")</code>.</p>
<p><a name="observable-withhandler"></a>
<a href="#observable-withhandler" title="observable.withHandler(f)"><code>observable.withHandler(f)</code></a> lets you do more custom event handling: you
get all events to your function and you can output any number of events
and end the stream if you choose. For example, to send an error and end
the stream in case a value is below zero:</p>
<pre><code class="language-js"><textarea class="code">if (event.hasValue() && event.value() < 0) {
this.push(new Bacon.Error("Value below zero"));
return this.push(end());
} else {
return this.push(event);
}
</textarea></code></pre>
<p>Note that it's important to return the value from <code>this.push</code> so that
the connection to the underlying stream will be closed when no more
events are needed.</p>
<p><a name="observable-name"></a>
<a href="#observable-name" title="observable.name(@ : Observable[A], newName : String) : Observable[A]"><code>observable.name(newName)</code></a> sets the name of the observable. Overrides the default
implementation of <a href="#observable-tostring"><code>toString</code></a> and <code>inspect</code>.
Returns itself.</p>
<p><a name="observable-withdescription"></a>
<a href="#observable-withdescription" title="observable.withDescription(@ : Observable[A], param...) : Observable[A]"><code>observable.withDescription(param...)</code></a> Sets the structured description of the observable. The <a href="#observable-tostring"><code>toString</code></a> and <code>inspect</code> methods
use this data recursively to create a string representation for the observable. This method
is probably useful for Bacon core / library / plugin development only.</p>
<p>For example:</p>