ObservableOperators

A library of Reactive Operators built with ECMAScript Observables from the ground up.

• Flexible - Operators can be expressed in functional or fluent format
• Small - If you want everything there's RxJS, this library has a small set of canonical operators
• Well documented

Install

Install with npm or yarn:

npm install observable-operators

You will need an ES Observable polyfill. I recommend zen-observable.

Use

This library's default export will add all available methods to the Observable constructor and prototype so that they may be chained in the reactive style:

import addAll from 'observable-operators';

addAll();

Observable.fromEvent(document, 'click')
  .merge(otherClicks)
  .map(parseEvent)
  .filter(theOnesICareAbout)
  .subscribe(console.log);

With require the addAll method can be called inline:

require('observable-operators').addAll();

Observable and Observable.prototype will not be modified unless this function is invoked. If you wish to have all operators available, you should import this module somewhere high-up so that it runs before the rest of your code.

Specifying another target

If you do not wish to modify the global Observable you can pass in a different target object:

addAll(MyObservable)

This will allow chaining on your custom Observable as long as it has the core methods specified in the Observable proposal.

Method types

This library distinguishes between Operators and Creators

• Operators: Functions that take at least one Observable as input and return something else (either another Observable, a Promise, or other value). All Operators take an Observable as the first argument. This allows them to be used either directly as functions:

  import { map } from 'observable-operators';
  
  map(Observable.of(1, 2, 3), x => x + 1)
    .subscribe(console.log)

  or as chainable methods once the operators are added to Observable.prototype:

  Observable.of(1, 2, 3)
    .map(x => x + 1)
    .merge(otherStream)
    .filter(isOdd)
    .subscribe(console.log)

  The helper method addOperators is used to add operators to Observable.prototype as part of the library's root method. If you wish to cherrypick operators you can do so:

  import { addOperators, filter, merge } from 'observable-operators'
  
  addOperators(Observable.prototype, [filter, merge])

• Creators: Functions that take other things as inputs and return Observables. Creators may be used directly as functions:

  import { fromEvent } from 'observable-operators'
  
  fromEvent(document, 'click').subscribe(handleEvent)

  or once added to the Observable constructor or another constructor, may be accessed as static methods:

  Observable.fromEvent(document, 'click').subscribe(handleEvent)

  If used as static methods creators will return an instance of the Constructor method to which they are assigned:

  MyObservable.interval(1) instanceof MyObservable // true

  If used directly as a function, a Constructor may be passed in as an optional final argument:

    interval(1000, MyObservable) instanceof MyObservable // true

  By default, creators will return an instance of the global Observable.

  The helper function addCreators is used to add creators to the Observable constructor as part of the library's root method. If you wish to cherrypick creators you may do so:

  import { addCreators, interval, fromEvent } from 'observable-operators'
  
  addCreators(Observable, [interval, fromEvent])

Available Methods

Creators

• defer
• error
• fromEvent
• fromPromise
• interval

Operators

• catchError
• concat
• debounce
• delay
• filter
• flatMap
• forEach
• map
• merge
• reduce
• scan
• skip
• skipLast
• skipUntil
• startWith
• take
• takeLast
• takeUntil
• throttle
• toArray
• transform

Motivation

There are great existing reactive observable libraries out there already such as most.js and RxJS, but none of them that are built from the bottom up on top of the ECMAScript Observable proposal that will (hopefully) be part of the language. This is that library.