xstream - npm Package Compare versions

Comparing version 5.0.6 to 5.1.0

.markdown-doctest-setup.js

@@ -30,2 +30,6 @@ var xstream = require('./index').default;
   }
+
+  querySelector() {
+    return this;
+  }
 }
@@ -32,0 +36,0 @@

CHANGELOG.md

@@ -0,1 +1,11 @@
+<a name="5.1.0"></a>
+# [5.1.0](https://github.com/staltz/xstream/compare/v5.0.6...v5.1.0) (2016-07-01)
+
+
+### Features
+
+* **extra:** add new extra factory tween() ([9ee12a7](https://github.com/staltz/xstream/commit/9ee12a7))
+
+
+
 <a name="5.0.6"></a>
@@ -2,0 +12,0 @@ ## [5.0.6](https://github.com/staltz/xstream/compare/v5.0.5...v5.0.6) (2016-06-17)

EXTRA_DOCS.md

@@ -1,3 +0,20 @@
-# Extra operators and factories
+<!-- This EXTRA_DOCS.md file is automatically generated from source code and files in the /markdown directory. Please DO NOT send pull requests to directly modify this file. Instead, edit the JSDoc comments in source code or the md files in /markdown or the md.ejs files in /tools. -->
 
+## Extras
+
+- [`concat`](#concat) (factory)
+- [`debounce`](#debounce) (operator)
+- [`delay`](#delay) (operator)
+- [`dropRepeats`](#dropRepeats) (operator)
+- [`dropUntil`](#dropUntil) (operator)
+- [`flattenConcurrently`](#flattenConcurrently) (operator)
+- [`flattenSequentially`](#flattenSequentially) (operator)
+- [`fromDiagram`](#fromDiagram) (factory)
+- [`fromEvent`](#fromEvent) (operator)
+- [`pairwise`](#pairwise) (operator)
+- [`split`](#split) (operator)
+- [`tween`](#tween) (factory)
+
+# How to use extras
+
 The following are standalone stream operators and stream factories that may be separately imported and utilized in your project.
@@ -66,2 +83,207 @@ To use an extra operator (e.g. `delay`), import it as such:
 
+### <a id="debounce"></a> `debounce(period)`
+
+Delays events until a certain amount of silence has passed. If that timespan
+of silence is not met the event is dropped.
+
+Marble diagram:
+
+```text
+--1----2--3--4----5|
+    debounce(60)
+-----1----------4--|
+```
+
+Example:
+
+```js
+import fromDiagram from 'xstream/extra/fromDiagram'
+import debounce from 'xstream/extra/debounce'
+
+const stream = fromDiagram('--1----2--3--4----5|')
+ .compose(debounce(60))
+
+stream.addListener({
+  next: i => console.log(i),
+  error: err => console.error(err),
+  complete: () => console.log('completed')
+})
+```
+
+```text
+> 1
+> 4
+> completed
+```
+
+#### Arguments:
+
+- `period: number` The amount of silence required in milliseconds.
+
+#### Returns:  Stream 
+
+- - -
+
+### <a id="delay"></a> `delay(period)`
+
+Delays periodic events by a given time period.
+
+Marble diagram:
+
+```text
+1----2--3--4----5|
+    delay(60)
+---1----2--3--4----5|
+```
+
+Example:
+
+```js
+import fromDiagram from 'xstream/extra/fromDiagram'
+import delay from 'xstream/extra/delay'
+
+const stream = fromDiagram('1----2--3--4----5|')
+ .compose(delay(60))
+
+stream.addListener({
+  next: i => console.log(i),
+  error: err => console.error(err),
+  complete: () => console.log('completed')
+})
+```
+
+```text
+> 1  (after 60 ms)
+> 2  (after 160 ms)
+> 3  (after 220 ms)
+> 4  (after 280 ms)
+> 5  (after 380 ms)
+> completed
+```
+
+#### Arguments:
+
+- `period: number` The amount of silence required in milliseconds.
+
+#### Returns:  Stream 
+
+- - -
+
+### <a id="dropRepeats"></a> `dropRepeats(isEqual)`
+
+Drops consecutive duplicate values in a stream.
+
+Marble diagram:
+
+```text
+--1--2--1--1--1--2--3--4--3--3|
+    dropRepeats
+--1--2--1--------2--3--4--3---|
+```
+
+Example:
+
+```js
+import dropRepeats from 'xstream/extra/dropRepeats'
+
+const stream = xs.of(1, 2, 1, 1, 1, 2, 3, 4, 3, 3)
+  .compose(dropRepeats())
+
+stream.addListener({
+  next: i => console.log(i),
+  error: err => console.error(err),
+  complete: () => console.log('completed')
+})
+```
+
+```text
+> 1
+> 2
+> 1
+> 2
+> 3
+> 4
+> 3
+> completed
+```
+
+Example with a custom isEqual function:
+
+```js
+import dropRepeats from 'xstream/extra/dropRepeats'
+
+const stream = xs.of('a', 'b', 'a', 'A', 'B', 'b')
+  .compose(dropRepeats((x, y) => x.toLowerCase() === y.toLowerCase()))
+
+stream.addListener({
+  next: i => console.log(i),
+  error: err => console.error(err),
+  complete: () => console.log('completed')
+})
+```
+
+```text
+> a
+> b
+> a
+> B
+> completed
+```
+
+#### Arguments:
+
+- `isEqual: Function` An optional function of type `(x: T, y: T) => boolean` that takes an event from the input stream and
+checks if it is equal to previous event, by returning a boolean.
+
+#### Returns:  Stream 
+
+- - -
+
+### <a id="dropUntil"></a> `dropUntil(other)`
+
+Starts emitting the input stream when another stream emits a next event. The
+output stream will complete if/when the other stream completes.
+
+Marble diagram:
+
+```text
+---1---2-----3--4----5----6---
+  dropUntil( --------a--b--| )
+---------------------5----6|
+```
+
+Example:
+
+```js
+import dropUntil from 'xstream/extra/dropUntil'
+
+const other = xs.periodic(220).take(1)
+
+const stream = xs.periodic(50)
+  .take(6)
+  .compose(dropUntil(other))
+
+stream.addListener({
+  next: i => console.log(i),
+  error: err => console.error(err),
+  complete: () => console.log('completed')
+})
+```
+
+```text
+> 4
+> 5
+> completed
+```
+
+#### Arguments:
+
+#### Arguments:
+
+- `other: Stream` Some other stream that is used to know when should the output stream of this operator start emitting.
+
+#### Returns:  Stream 
+
+- - -
+
 ### <a id="flattenConcurrently"></a> `flattenConcurrently()`
@@ -181,1 +403,232 @@
 
+### <a id="fromEvent"></a> `fromEvent(node, eventType, useCapture)`
+
+Creates a stream based on DOM events of type `eventType` from the target
+node.
+
+Marble diagram:
+
+```text
+  fromEvent(node, eventType)
+---ev--ev----ev---------------
+```
+
+Example:
+
+```js
+import fromEvent from 'xstream/extra/fromEvent'
+
+const stream = fromEvent(document.querySelector('.button'), 'click')
+  .mapTo('Button clicked!')
+
+stream.addListener({
+  next: i => console.log(i),
+  error: err => console.error(err),
+  complete: () => console.log('completed')
+})
+```
+
+```text
+> 'Button clicked!'
+> 'Button clicked!'
+> 'Button clicked!'
+```
+
+#### Arguments:
+
+- `node: EventTarget` The element we want to listen to.
+- `eventType: string` The type of events we want to listen to.
+- `useCapture: boolean` An optional boolean that indicates that events of this type will be dispatched to the registered listener before being
+dispatched to any EventTarget beneath it in the DOM tree. Defaults to false.
+
+#### Returns:  Stream 
+
+- - -
+
+### <a id="pairwise"></a> `pairwise()`
+
+Group consecutive pairs of events as arrays. Each array has two items.
+
+Marble diagram:
+
+```text
+---1---2-----3-----4-----5--------|
+      pairwise
+-------[1,2]-[2,3]-[3,4]-[4,5]----|
+```
+
+Example:
+
+```js
+import pairwise from 'xstream/extra/pairwise'
+
+const stream = xs.of(1, 2, 3, 4, 5, 6).compose(pairwise)
+
+stream.addListener({
+  next: i => console.log(i),
+  error: err => console.error(err),
+  complete: () => console.log('completed')
+})
+```
+
+```text
+> [1,2]
+> [2,3]
+> [3,4]
+> [4,5]
+> [5,6]
+> completed
+```
+
+#### Returns:  Stream 
+
+- - -
+
+### <a id="split"></a> `split(separator)`
+
+Splits a stream using a separator stream. Returns a stream that emits
+streams.
+
+Marble diagram:
+
+```text
+--1--2--3--4--5--6--7--8--9|
+ split( --a----b--- )
+---------------------------|
+  :        :    :
+  1--2--3-|:    :
+           4--5|:
+                -6--7--8--9|
+```
+
+Example:
+
+```js
+import split from 'xstream/extra/split'
+import concat from 'xstream/extra/concat'
+
+const source = xs.periodic(50).take(10)
+const separator = concat(xs.periodic(167).take(2), xs.never())
+const result = source.compose(split(separator))
+
+result.addListener({
+  next: stream => {
+    stream.addListener({
+      next: i => console.log(i),
+      error: err => console.error(err),
+      complete: () => console.log('inner completed')
+    })
+  },
+  error: err => console.error(err),
+  complete: () => console.log('outer completed')
+})
+```
+
+```text
+> 0
+> 1
+> 2
+> inner completed
+> 3
+> 4
+> 5
+> inner completed
+> 6
+> 7
+> 8
+> 9
+> inner completed
+> outer completed
+```
+
+#### Arguments:
+
+- `separator: Stream` Some other stream that is used to know when to split the output stream.
+
+#### Returns:  Stream 
+
+- - -
+
+### <a id="tween"></a> `tween(config)`
+
+Creates a stream of numbers emitted in a quick burst, following a numeric
+function like sine or elastic or quadratic. tween() is meant for creating
+streams for animations.
+
+Example:
+
+```js
+import tween from 'xstream/extra/tween'
+
+const stream = tween({
+  from: 20,
+  to: 100,
+  ease: tween.exponential.easeIn,
+  duration: 1000, // milliseconds
+})
+
+stream.addListener({
+  next: (x) => console.log(x),
+  error: (err) => console.error(err),
+  complete: () => console.log('concat completed'),
+})
+```
+
+The stream would behave like the plot below:
+
+```text
+100                  #
+|
+|
+|
+|
+80                  #
+|
+|
+|
+|                  #
+60
+|
+|                 #
+|
+|                #
+40
+|               #
+|              #
+|            ##
+|         ###
+20########
++---------------------> time
+```
+
+Provide a configuration object with **from**, **to**, **duration**, **ease**,
+**interval** (optional), and this factory function will return a stream of
+numbers following that pattern. The first number emitted will be `from`, and
+the last number will be `to`. The numbers in between follow the easing
+function you specify in `ease`, and the stream emission will last in total
+`duration` milliseconds.
+
+The easing functions are attached to `tween` too, such as
+`tween.linear.ease`, `tween.power2.easeIn`, `tween.exponential.easeOut`, etc.
+Here is a list of all the available easing options:
+
+- `tween.linear` with ease
+- `tween.power2` with easeIn, easeOut, easeInOut
+- `tween.power3` with easeIn, easeOut, easeInOut
+- `tween.power4` with easeIn, easeOut, easeInOut
+- `tween.exponential` with easeIn, easeOut, easeInOut
+- `tween.back` with easeIn, easeOut, easeInOut
+- `tween.bounce` with easeIn, easeOut, easeInOut
+- `tween.circular` with easeIn, easeOut, easeInOut
+- `tween.elastic` with easeIn, easeOut, easeInOut
+- `tween.sine` with easeIn, easeOut, easeInOut
+
+#### Arguments:
+
+- `config: TweenConfig` An object with properties `from: number`, `to: number`, `duration: number`, `ease: function` (optional, defaults to
+linear), `interval: number` (optional, defaults to 15).
+
+#### Returns:  Stream 
+
+- - -
+

extra/debounce.d.ts

 import { Stream } from '../core';
+/**
+ * Delays events until a certain amount of silence has passed. If that timespan
+ * of silence is not met the event is dropped.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * --1----2--3--4----5|
+ *     debounce(60)
+ * -----1----------4--|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import fromDiagram from 'xstream/extra/fromDiagram'
+ * import debounce from 'xstream/extra/debounce'
+ *
+ * const stream = fromDiagram('--1----2--3--4----5|')
+ *  .compose(debounce(60))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 1
+ * > 4
+ * > completed
+ * ```
+ *
+ * @param {number} period The amount of silence required in milliseconds.
+ * @return {Stream}
+ */
 export default function debounce<T>(period: number): (ins: Stream<T>) => Stream<T>;

extra/debounce.js

@@ -57,2 +57,39 @@ "use strict";
 }());
+/**
+ * Delays events until a certain amount of silence has passed. If that timespan
+ * of silence is not met the event is dropped.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * --1----2--3--4----5|
+ *     debounce(60)
+ * -----1----------4--|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import fromDiagram from 'xstream/extra/fromDiagram'
+ * import debounce from 'xstream/extra/debounce'
+ *
+ * const stream = fromDiagram('--1----2--3--4----5|')
+ *  .compose(debounce(60))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 1
+ * > 4
+ * > completed
+ * ```
+ *
+ * @param {number} period The amount of silence required in milliseconds.
+ * @return {Stream}
+ */
 function debounce(period) {
@@ -59,0 +96,0 @@ return function debounceOperator(ins) {

extra/delay.d.ts

 import { Stream } from '../core';
+/**
+ * Delays periodic events by a given time period.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * 1----2--3--4----5|
+ *     delay(60)
+ * ---1----2--3--4----5|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import fromDiagram from 'xstream/extra/fromDiagram'
+ * import delay from 'xstream/extra/delay'
+ *
+ * const stream = fromDiagram('1----2--3--4----5|')
+ *  .compose(delay(60))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 1  (after 60 ms)
+ * > 2  (after 160 ms)
+ * > 3  (after 220 ms)
+ * > 4  (after 280 ms)
+ * > 5  (after 380 ms)
+ * > completed
+ * ```
+ *
+ * @param {number} period The amount of silence required in milliseconds.
+ * @return {Stream}
+ */
 export default function delay<T>(period: number): (ins: Stream<T>) => Stream<T>;

extra/delay.js

@@ -47,2 +47,41 @@ "use strict";
 }());
+/**
+ * Delays periodic events by a given time period.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * 1----2--3--4----5|
+ *     delay(60)
+ * ---1----2--3--4----5|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import fromDiagram from 'xstream/extra/fromDiagram'
+ * import delay from 'xstream/extra/delay'
+ *
+ * const stream = fromDiagram('1----2--3--4----5|')
+ *  .compose(delay(60))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 1  (after 60 ms)
+ * > 2  (after 160 ms)
+ * > 3  (after 220 ms)
+ * > 4  (after 280 ms)
+ * > 5  (after 380 ms)
+ * > completed
+ * ```
+ *
+ * @param {number} period The amount of silence required in milliseconds.
+ * @return {Stream}
+ */
 function delay(period) {
@@ -49,0 +88,0 @@ return function delayOperator(ins) {

extra/dropRepeats.d.ts

@@ -16,2 +16,67 @@ import { Operator, Stream } from '../core';
 }
+/**
+ * Drops consecutive duplicate values in a stream.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * --1--2--1--1--1--2--3--4--3--3|
+ *     dropRepeats
+ * --1--2--1--------2--3--4--3---|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import dropRepeats from 'xstream/extra/dropRepeats'
+ *
+ * const stream = xs.of(1, 2, 1, 1, 1, 2, 3, 4, 3, 3)
+ *   .compose(dropRepeats())
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 1
+ * > 2
+ * > 1
+ * > 2
+ * > 3
+ * > 4
+ * > 3
+ * > completed
+ * ```
+ *
+ * Example with a custom isEqual function:
+ *
+ * ```js
+ * import dropRepeats from 'xstream/extra/dropRepeats'
+ *
+ * const stream = xs.of('a', 'b', 'a', 'A', 'B', 'b')
+ *   .compose(dropRepeats((x, y) => x.toLowerCase() === y.toLowerCase()))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > a
+ * > b
+ * > a
+ * > B
+ * > completed
+ * ```
+ *
+ * @param {Function} isEqual An optional function of type
+ * `(x: T, y: T) => boolean` that takes an event from the input stream and
+ * checks if it is equal to previous event, by returning a boolean.
+ * @return {Stream}
+ */
 export default function dropRepeats<T>(isEqual?: (x: T, y: T) => boolean): (ins: Stream<T>) => Stream<T>;

extra/dropRepeats.js

@@ -49,2 +49,67 @@ "use strict";
 exports.DropRepeatsOperator = DropRepeatsOperator;
+/**
+ * Drops consecutive duplicate values in a stream.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * --1--2--1--1--1--2--3--4--3--3|
+ *     dropRepeats
+ * --1--2--1--------2--3--4--3---|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import dropRepeats from 'xstream/extra/dropRepeats'
+ *
+ * const stream = xs.of(1, 2, 1, 1, 1, 2, 3, 4, 3, 3)
+ *   .compose(dropRepeats())
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 1
+ * > 2
+ * > 1
+ * > 2
+ * > 3
+ * > 4
+ * > 3
+ * > completed
+ * ```
+ *
+ * Example with a custom isEqual function:
+ *
+ * ```js
+ * import dropRepeats from 'xstream/extra/dropRepeats'
+ *
+ * const stream = xs.of('a', 'b', 'a', 'A', 'B', 'b')
+ *   .compose(dropRepeats((x, y) => x.toLowerCase() === y.toLowerCase()))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > a
+ * > b
+ * > a
+ * > B
+ * > completed
+ * ```
+ *
+ * @param {Function} isEqual An optional function of type
+ * `(x: T, y: T) => boolean` that takes an event from the input stream and
+ * checks if it is equal to previous event, by returning a boolean.
+ * @return {Stream}
+ */
 function dropRepeats(isEqual) {
@@ -51,0 +116,0 @@ if (isEqual === void 0) { isEqual = null; }

extra/dropUntil.d.ts

@@ -17,2 +17,44 @@ import { Operator, Stream } from '../core';
 }
+/**
+ * Starts emitting the input stream when another stream emits a next event. The
+ * output stream will complete if/when the other stream completes.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * ---1---2-----3--4----5----6---
+ *   dropUntil( --------a--b--| )
+ * ---------------------5----6|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import dropUntil from 'xstream/extra/dropUntil'
+ *
+ * const other = xs.periodic(220).take(1)
+ *
+ * const stream = xs.periodic(50)
+ *   .take(6)
+ *   .compose(dropUntil(other))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 4
+ * > 5
+ * > completed
+ * ```
+ *
+ * #### Arguments:
+ *
+ * @param {Stream} other Some other stream that is used to know when should the
+ * output stream of this operator start emitting.
+ * @return {Stream}
+ */
 export default function dropUntil<T>(other: Stream<any>): (ins: Stream<T>) => Stream<T>;

extra/dropUntil.js

@@ -69,2 +69,44 @@ "use strict";
 exports.DropUntilOperator = DropUntilOperator;
+/**
+ * Starts emitting the input stream when another stream emits a next event. The
+ * output stream will complete if/when the other stream completes.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * ---1---2-----3--4----5----6---
+ *   dropUntil( --------a--b--| )
+ * ---------------------5----6|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import dropUntil from 'xstream/extra/dropUntil'
+ *
+ * const other = xs.periodic(220).take(1)
+ *
+ * const stream = xs.periodic(50)
+ *   .take(6)
+ *   .compose(dropUntil(other))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 4
+ * > 5
+ * > completed
+ * ```
+ *
+ * #### Arguments:
+ *
+ * @param {Stream} other Some other stream that is used to know when should the
+ * output stream of this operator start emitting.
+ * @return {Stream}
+ */
 function dropUntil(other) {
@@ -71,0 +113,0 @@ return function dropUntilOperator(ins) {

extra/fromEvent.d.ts

@@ -12,2 +12,41 @@ import { Stream, InternalProducer, InternalListener } from '../core';
 }
+/**
+ * Creates a stream based on DOM events of type `eventType` from the target
+ * node.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ *   fromEvent(node, eventType)
+ * ---ev--ev----ev---------------
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import fromEvent from 'xstream/extra/fromEvent'
+ *
+ * const stream = fromEvent(document.querySelector('.button'), 'click')
+ *   .mapTo('Button clicked!')
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 'Button clicked!'
+ * > 'Button clicked!'
+ * > 'Button clicked!'
+ * ```
+ *
+ * @param {EventTarget} node The element we want to listen to.
+ * @param {string} eventType The type of events we want to listen to.
+ * @param {boolean} useCapture An optional boolean that indicates that events of
+ * this type will be dispatched to the registered listener before being
+ * dispatched to any EventTarget beneath it in the DOM tree. Defaults to false.
+ * @return {Stream}
+ */
 export default function fromEvent(node: EventTarget, eventType: string, useCapture?: boolean): Stream<Event>;

extra/fromEvent.js

@@ -23,2 +23,41 @@ "use strict";
 exports.DOMEventProducer = DOMEventProducer;
+/**
+ * Creates a stream based on DOM events of type `eventType` from the target
+ * node.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ *   fromEvent(node, eventType)
+ * ---ev--ev----ev---------------
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import fromEvent from 'xstream/extra/fromEvent'
+ *
+ * const stream = fromEvent(document.querySelector('.button'), 'click')
+ *   .mapTo('Button clicked!')
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 'Button clicked!'
+ * > 'Button clicked!'
+ * > 'Button clicked!'
+ * ```
+ *
+ * @param {EventTarget} node The element we want to listen to.
+ * @param {string} eventType The type of events we want to listen to.
+ * @param {boolean} useCapture An optional boolean that indicates that events of
+ * this type will be dispatched to the registered listener before being
+ * dispatched to any EventTarget beneath it in the DOM tree. Defaults to false.
+ * @return {Stream}
+ */
 function fromEvent(node, eventType, useCapture) {
@@ -25,0 +64,0 @@ if (useCapture === void 0) { useCapture = false; }

extra/pairwise.d.ts

 import { Stream } from '../core';
-export default function pairwiseOperator<T>(ins: Stream<T>): Stream<[T, T]>;
+/**
+ * Group consecutive pairs of events as arrays. Each array has two items.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * ---1---2-----3-----4-----5--------|
+ *       pairwise
+ * -------[1,2]-[2,3]-[3,4]-[4,5]----|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import pairwise from 'xstream/extra/pairwise'
+ *
+ * const stream = xs.of(1, 2, 3, 4, 5, 6).compose(pairwise)
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > [1,2]
+ * > [2,3]
+ * > [3,4]
+ * > [4,5]
+ * > [5,6]
+ * > completed
+ * ```
+ *
+ * @return {Stream}
+ */
+export default function pairwise<T>(ins: Stream<T>): Stream<[T, T]>;

extra/pairwise.js

@@ -45,7 +45,43 @@ "use strict";
 }());
-function pairwiseOperator(ins) {
+/**
+ * Group consecutive pairs of events as arrays. Each array has two items.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * ---1---2-----3-----4-----5--------|
+ *       pairwise
+ * -------[1,2]-[2,3]-[3,4]-[4,5]----|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import pairwise from 'xstream/extra/pairwise'
+ *
+ * const stream = xs.of(1, 2, 3, 4, 5, 6).compose(pairwise)
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > [1,2]
+ * > [2,3]
+ * > [3,4]
+ * > [4,5]
+ * > [5,6]
+ * > completed
+ * ```
+ *
+ * @return {Stream}
+ */
+function pairwise(ins) {
     return new core_1.Stream(new PairwiseOperator(ins));
 }
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.default = pairwiseOperator;
+exports.default = pairwise;
 //# sourceMappingURL=pairwise.js.map

extra/split.d.ts

@@ -17,2 +17,62 @@ import { Operator, Stream } from '../core';
 }
+/**
+ * Splits a stream using a separator stream. Returns a stream that emits
+ * streams.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * --1--2--3--4--5--6--7--8--9|
+ *  split( --a----b--- )
+ * ---------------------------|
+ *   :        :    :
+ *   1--2--3-|:    :
+ *            4--5|:
+ *                 -6--7--8--9|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import split from 'xstream/extra/split'
+ * import concat from 'xstream/extra/concat'
+ *
+ * const source = xs.periodic(50).take(10)
+ * const separator = concat(xs.periodic(167).take(2), xs.never())
+ * const result = source.compose(split(separator))
+ *
+ * result.addListener({
+ *   next: stream => {
+ *     stream.addListener({
+ *       next: i => console.log(i),
+ *       error: err => console.error(err),
+ *       complete: () => console.log('inner completed')
+ *     })
+ *   },
+ *   error: err => console.error(err),
+ *   complete: () => console.log('outer completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 0
+ * > 1
+ * > 2
+ * > inner completed
+ * > 3
+ * > 4
+ * > 5
+ * > inner completed
+ * > 6
+ * > 7
+ * > 8
+ * > 9
+ * > inner completed
+ * > outer completed
+ * ```
+ *
+ * @param {Stream} separator Some other stream that is used to know when to
+ * split the output stream.
+ * @return {Stream}
+ */
 export default function split<T>(separator: Stream<any>): (ins: Stream<T>) => Stream<Stream<T>>;

extra/split.js

@@ -68,2 +68,62 @@ "use strict";
 exports.SplitOperator = SplitOperator;
+/**
+ * Splits a stream using a separator stream. Returns a stream that emits
+ * streams.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * --1--2--3--4--5--6--7--8--9|
+ *  split( --a----b--- )
+ * ---------------------------|
+ *   :        :    :
+ *   1--2--3-|:    :
+ *            4--5|:
+ *                 -6--7--8--9|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import split from 'xstream/extra/split'
+ * import concat from 'xstream/extra/concat'
+ *
+ * const source = xs.periodic(50).take(10)
+ * const separator = concat(xs.periodic(167).take(2), xs.never())
+ * const result = source.compose(split(separator))
+ *
+ * result.addListener({
+ *   next: stream => {
+ *     stream.addListener({
+ *       next: i => console.log(i),
+ *       error: err => console.error(err),
+ *       complete: () => console.log('inner completed')
+ *     })
+ *   },
+ *   error: err => console.error(err),
+ *   complete: () => console.log('outer completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 0
+ * > 1
+ * > 2
+ * > inner completed
+ * > 3
+ * > 4
+ * > 5
+ * > inner completed
+ * > 6
+ * > 7
+ * > 8
+ * > 9
+ * > inner completed
+ * > outer completed
+ * ```
+ *
+ * @param {Stream} separator Some other stream that is used to know when to
+ * split the output stream.
+ * @return {Stream}
+ */
 function split(separator) {
@@ -70,0 +130,0 @@ return function splitOperator(ins) {

package.json

 {
   "name": "xstream",
-  "version": "5.0.6",
+  "version": "5.1.0",
   "description": "An extremely intuitive, small, and fast functional reactive stream library for JavaScript",
@@ -19,3 +19,3 @@ "main": "index.js",
     "page-content": "npm run compile && rm -rf .ignore/ && mkdirp .ignore/ && npm run changelog && node tools/make-toc.js && node tools/make-factories.js && node tools/make-methods.js && cat markdown/header.md markdown/generated-toc.md markdown/overview.md markdown/generated-factories.md markdown/generated-methods.md markdown/footer.md > .ignore/content.md",
-    "extra-docs": "node tools/make-extras.js && cp markdown/generated-extras.md EXTRA_DOCS.md",
+    "extra-docs": "node tools/make-extras.js && rm EXTRA_DOCS.md && cp markdown/generated-extras.md EXTRA_DOCS.md",
     "readme": "npm run page-content && cat markdown/readme-title.md .ignore/content.md > README.md",
@@ -22,0 +22,0 @@ "postreadme": "npm run extra-docs",

src/extra/debounce.ts

@@ -59,2 +59,39 @@ import {Operator, Stream} from '../core';
 
+/**
+ * Delays events until a certain amount of silence has passed. If that timespan
+ * of silence is not met the event is dropped.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * --1----2--3--4----5|
+ *     debounce(60)
+ * -----1----------4--|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import fromDiagram from 'xstream/extra/fromDiagram'
+ * import debounce from 'xstream/extra/debounce'
+ *
+ * const stream = fromDiagram('--1----2--3--4----5|')
+ *  .compose(debounce(60))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 1
+ * > 4
+ * > completed
+ * ```
+ *
+ * @param {number} period The amount of silence required in milliseconds.
+ * @return {Stream}
+ */
 export default function debounce<T>(period: number): (ins: Stream<T>) => Stream<T> {
@@ -61,0 +98,0 @@ return function debounceOperator(ins: Stream<T>) {

src/extra/delay.ts

@@ -49,2 +49,41 @@ import {Operator, Stream} from '../core';
 
+/**
+ * Delays periodic events by a given time period.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * 1----2--3--4----5|
+ *     delay(60)
+ * ---1----2--3--4----5|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import fromDiagram from 'xstream/extra/fromDiagram'
+ * import delay from 'xstream/extra/delay'
+ *
+ * const stream = fromDiagram('1----2--3--4----5|')
+ *  .compose(delay(60))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 1  (after 60 ms)
+ * > 2  (after 160 ms)
+ * > 3  (after 220 ms)
+ * > 4  (after 280 ms)
+ * > 5  (after 380 ms)
+ * > completed
+ * ```
+ *
+ * @param {number} period The amount of silence required in milliseconds.
+ * @return {Stream}
+ */
 export default function delay<T>(period: number): (ins: Stream<T>) => Stream<T> {
@@ -51,0 +90,0 @@ return function delayOperator(ins: Stream<T>): Stream<T> {

src/extra/dropRepeats.ts

@@ -51,2 +51,67 @@ import {Operator, Stream} from '../core';
 
+/**
+ * Drops consecutive duplicate values in a stream.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * --1--2--1--1--1--2--3--4--3--3|
+ *     dropRepeats
+ * --1--2--1--------2--3--4--3---|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import dropRepeats from 'xstream/extra/dropRepeats'
+ *
+ * const stream = xs.of(1, 2, 1, 1, 1, 2, 3, 4, 3, 3)
+ *   .compose(dropRepeats())
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 1
+ * > 2
+ * > 1
+ * > 2
+ * > 3
+ * > 4
+ * > 3
+ * > completed
+ * ```
+ *
+ * Example with a custom isEqual function:
+ *
+ * ```js
+ * import dropRepeats from 'xstream/extra/dropRepeats'
+ *
+ * const stream = xs.of('a', 'b', 'a', 'A', 'B', 'b')
+ *   .compose(dropRepeats((x, y) => x.toLowerCase() === y.toLowerCase()))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > a
+ * > b
+ * > a
+ * > B
+ * > completed
+ * ```
+ *
+ * @param {Function} isEqual An optional function of type
+ * `(x: T, y: T) => boolean` that takes an event from the input stream and
+ * checks if it is equal to previous event, by returning a boolean.
+ * @return {Stream}
+ */
 export default function dropRepeats<T>(isEqual: (x: T, y: T) => boolean = null): (ins: Stream<T>) => Stream<T> {
@@ -53,0 +118,0 @@ return function dropRepeatsOperator(ins: Stream<T>): Stream<T> {

src/extra/dropUntil.ts

@@ -71,2 +71,44 @@ import {Operator, InternalListener, Stream, OutSender, emptyIL} from '../core';
 
+/**
+ * Starts emitting the input stream when another stream emits a next event. The
+ * output stream will complete if/when the other stream completes.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * ---1---2-----3--4----5----6---
+ *   dropUntil( --------a--b--| )
+ * ---------------------5----6|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import dropUntil from 'xstream/extra/dropUntil'
+ *
+ * const other = xs.periodic(220).take(1)
+ *
+ * const stream = xs.periodic(50)
+ *   .take(6)
+ *   .compose(dropUntil(other))
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 4
+ * > 5
+ * > completed
+ * ```
+ *
+ * #### Arguments:
+ *
+ * @param {Stream} other Some other stream that is used to know when should the
+ * output stream of this operator start emitting.
+ * @return {Stream}
+ */
 export default function dropUntil<T>(other: Stream<any>): (ins: Stream<T>) => Stream<T> {
@@ -73,0 +115,0 @@ return function dropUntilOperator(ins: Stream<T>): Stream<T> {

src/extra/fromEvent.ts

@@ -25,2 +25,41 @@ import {Stream, InternalProducer, InternalListener} from '../core';
 
+/**
+ * Creates a stream based on DOM events of type `eventType` from the target
+ * node.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ *   fromEvent(node, eventType)
+ * ---ev--ev----ev---------------
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import fromEvent from 'xstream/extra/fromEvent'
+ *
+ * const stream = fromEvent(document.querySelector('.button'), 'click')
+ *   .mapTo('Button clicked!')
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 'Button clicked!'
+ * > 'Button clicked!'
+ * > 'Button clicked!'
+ * ```
+ *
+ * @param {EventTarget} node The element we want to listen to.
+ * @param {string} eventType The type of events we want to listen to.
+ * @param {boolean} useCapture An optional boolean that indicates that events of
+ * this type will be dispatched to the registered listener before being
+ * dispatched to any EventTarget beneath it in the DOM tree. Defaults to false.
+ * @return {Stream}
+ */
 export default function fromEvent(node: EventTarget,
@@ -27,0 +66,0 @@ eventType: string,

src/extra/pairwise.ts

@@ -47,4 +47,40 @@ import {Operator, Stream} from '../core';
 
-export default function pairwiseOperator<T>(ins: Stream<T>): Stream<[T, T]> {
+/**
+ * Group consecutive pairs of events as arrays. Each array has two items.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * ---1---2-----3-----4-----5--------|
+ *       pairwise
+ * -------[1,2]-[2,3]-[3,4]-[4,5]----|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import pairwise from 'xstream/extra/pairwise'
+ *
+ * const stream = xs.of(1, 2, 3, 4, 5, 6).compose(pairwise)
+ *
+ * stream.addListener({
+ *   next: i => console.log(i),
+ *   error: err => console.error(err),
+ *   complete: () => console.log('completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > [1,2]
+ * > [2,3]
+ * > [3,4]
+ * > [4,5]
+ * > [5,6]
+ * > completed
+ * ```
+ *
+ * @return {Stream}
+ */
+export default function pairwise<T>(ins: Stream<T>): Stream<[T, T]> {
   return new Stream<[T, T]>(new PairwiseOperator(ins));
 }

src/extra/split.ts

@@ -71,2 +71,62 @@ import {Operator, InternalListener, Stream, OutSender, emptyIL} from '../core';
 
+/**
+ * Splits a stream using a separator stream. Returns a stream that emits
+ * streams.
+ *
+ * Marble diagram:
+ *
+ * ```text
+ * --1--2--3--4--5--6--7--8--9|
+ *  split( --a----b--- )
+ * ---------------------------|
+ *   :        :    :
+ *   1--2--3-|:    :
+ *            4--5|:
+ *                 -6--7--8--9|
+ * ```
+ *
+ * Example:
+ *
+ * ```js
+ * import split from 'xstream/extra/split'
+ * import concat from 'xstream/extra/concat'
+ *
+ * const source = xs.periodic(50).take(10)
+ * const separator = concat(xs.periodic(167).take(2), xs.never())
+ * const result = source.compose(split(separator))
+ *
+ * result.addListener({
+ *   next: stream => {
+ *     stream.addListener({
+ *       next: i => console.log(i),
+ *       error: err => console.error(err),
+ *       complete: () => console.log('inner completed')
+ *     })
+ *   },
+ *   error: err => console.error(err),
+ *   complete: () => console.log('outer completed')
+ * })
+ * ```
+ *
+ * ```text
+ * > 0
+ * > 1
+ * > 2
+ * > inner completed
+ * > 3
+ * > 4
+ * > 5
+ * > inner completed
+ * > 6
+ * > 7
+ * > 8
+ * > 9
+ * > inner completed
+ * > outer completed
+ * ```
+ *
+ * @param {Stream} separator Some other stream that is used to know when to
+ * split the output stream.
+ * @return {Stream}
+ */
 export default function split<T>(separator: Stream<any>): (ins: Stream<T>) => Stream<Stream<T>> {
@@ -73,0 +133,0 @@ return function splitOperator(ins: Stream<T>): Stream<Stream<T>> {

tsconfig.json

@@ -32,2 +32,3 @@ {
     "src/extra/split.ts",
+    "src/extra/tween.ts",
     "src/index.ts"
@@ -34,0 +35,0 @@ ],

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

790993

increased by7.55%

Number of package files

144

increased by3.6%

Lines of code

14974

increased by13.36%

No dependency changes