docs(extras): add fromEvent to EXTRA_DOCS.md

EXTRA_DOCS.md

@@ -11,6 +11,7 @@
 - [`flattenConcurrently`](#flattenConcurrently) (operator)
 - [`flattenSequentially`](#flattenSequentially) (operator)
 - [`fromDiagram`](#fromDiagram) (factory)
+- [`fromEvent`](#fromEvent) (factory)
 - [`pairwise`](#pairwise) (operator)
 - [`sampleCombine`](#sampleCombine) (operator)
 - [`split`](#split) (operator)
@@ -285,7 +286,7 @@ checks if it is equal to previous event, by returning a boolean.
 ### <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.
+output stream will emit no items if another stream is empty.
 
 Marble diagram:
 
@@ -323,7 +324,7 @@ stream.addListener({
 
 #### Arguments:
 
-- `other: Stream` Some other stream that is used to know when should the output stream of this operator start emitting.
+- `other: Stream` Some other stream that is used to know when the output stream of this operator should start emitting.
 
 #### Returns:  Stream 
 
@@ -443,6 +444,99 @@ the error which `#` represents.
 
 - - -
 
+### <a id="fromEvent"></a> `fromEvent(element, eventName, useCapture)`
+
+Creates a stream based on either:
+- DOM events with the name `eventName` from a provided target node
+- Events with the name `eventName` from a provided NodeJS EventEmitter
+
+When creating a stream from EventEmitters, if the source event has more than
+one argument all the arguments will be aggregated into an array in the
+result stream.
+
+(Tip: when using this factory with TypeScript, you will need types for
+Node.js because fromEvent knows how to handle both DOM events and Node.js
+EventEmitter. Just install `@types/node`)
+
+Marble diagram:
+
+```text
+  fromEvent(element, eventName)
+---ev--ev----ev---------------
+```
+
+Examples:
+
+```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!'
+```
+
+```js
+import fromEvent from 'xstream/extra/fromEvent'
+import {EventEmitter} from 'events'
+
+const MyEmitter = new EventEmitter()
+const stream = fromEvent(MyEmitter, 'foo')
+
+stream.addListener({
+  next: i => console.log(i),
+  error: err => console.error(err),
+  complete: () => console.log('completed')
+})
+
+MyEmitter.emit('foo', 'bar')
+```
+
+```text
+> 'bar'
+```
+
+```js
+import fromEvent from 'xstream/extra/fromEvent'
+import {EventEmitter} from 'events'
+
+const MyEmitter = new EventEmitter()
+const stream = fromEvent(MyEmitter, 'foo')
+
+stream.addListener({
+  next: i => console.log(i),
+  error: err => console.error(err),
+  complete: () => console.log('completed')
+})
+
+MyEmitter.emit('foo', 'bar', 'baz', 'buzz')
+```
+
+```text
+> ['bar', 'baz', 'buzz']
+```
+
+#### Arguments:
+
+- `element: EventTarget|EventEmitter` The element upon which to listen.
+- `eventName: string` The name of the event for which to listen.
+- `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.

src/extra/fromEvent.ts

@@ -45,6 +45,9 @@ function isEmitter(element: any): element is EventEmitter {
   return element.emit && element.addListener;
 }
 
+function fromEvent<T = any>(element: EventEmitter, eventName: string): Stream<T>;
+function fromEvent<T extends Event = Event>(element: EventTarget, eventName: string, useCapture?: boolean): Stream<T>;
+
 /**
  * Creates a stream based on either:
  * - DOM events with the name `eventName` from a provided target node
@@ -134,10 +137,6 @@ function isEmitter(element: any): element is EventEmitter {
  * dispatched to any EventTarget beneath it in the DOM tree. Defaults to false.
  * @return {Stream}
  */
-
-function fromEvent<T = any>(element: EventEmitter, eventName: string): Stream<T>;
-function fromEvent<T extends Event = Event>(element: EventTarget, eventName: string, useCapture?: boolean): Stream<T>;
-
 function fromEvent<T = any>(element: EventEmitter | EventTarget,
                             eventName: string,
                             useCapture: boolean = false): Stream<T> {