[![Build Status](https://travis-ci.org/Reactive-Extensions/RxJS.svg)](https://travis-ci.org/Reactive-Extensions/RxJS) [![GitHub version](https://img.shields.io/github/tag/reactive-extensions/rxjs.svg)](https://github.com/Reactive-Extensions/RxJS) [![NPM version](https://img.shields.io/npm/v/rx.svg)](https://www.npmjs.com/package/rx) [![Downloads](https://img.shields.io/npm/dm/rx.svg)](https://www.npmjs.com/package/rx) [![Bower](https://img.shields.io/bower/v/rxjs.svg)](http://bower.io/search/?q=rxjs) [![NuGet](https://img.shields.io/nuget/v/RxJS-All.svg)](http://www.nuget.org/packages/RxJS-All/) [![Join the chat at https://gitter.im/Reactive-Extensions/RxJS](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/Reactive-Extensions/RxJS?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge) **[The Need to go Reactive](#the-need-to-go-reactive)** | **[About the Reactive Extensions](#about-the-reactive-extensions)** | **[Batteries Included](#batteries-included)** | **[Why RxJS?](#why-rxjs)** | **[Dive In!](#dive-in)** | **[Resources](#resources)** | **[Getting Started](#getting-started)** | **[What about my libraries?](#what-about-my-libraries)** | **[Compatibility](#compatibility)** | **[Contributing](#contributing)** | **[License](#license)** # The Reactive Extensions for JavaScript (RxJS) 4.0... # *...is a set of libraries to compose asynchronous and event-based programs using observable collections and [Array#extras](http://blogs.msdn.com/b/ie/archive/2010/12/13/ecmascript-5-part-2-array-extras.aspx) style composition in JavaScript* The project is actively developed by [Microsoft](https://microsoft.com/), in collaboration with a community of open source developers. ## The Need to go Reactive ## Applications, especially on the web have changed over the years from being a simple static page, to DHTML with animations, to the Ajax revolution. Each time, we're adding more complexity, more data, and asynchronous behavior to our applications. How do we manage it all? How do we scale it? By moving towards "Reactive Architectures" which are event-driven, resilient and responsive. With the Reactive Extensions, you have all the tools you need to help build these systems. ## About the Reactive Extensions ## The Reactive Extensions for JavaScript (RxJS) is a set of libraries for composing asynchronous and event-based programs using observable sequences and fluent query operators that many of you already know by [Array#extras](http://blogs.msdn.com/b/ie/archive/2010/12/13/ecmascript-5-part-2-array-extras.aspx) in JavaScript. Using RxJS, developers represent asynchronous data streams with Observables, query asynchronous data streams using our many operators, and parameterize the concurrency in the asynchronous data streams using Schedulers. Simply put, RxJS = Observables + Operators + Schedulers. Whether you are authoring a web-based application in JavaScript or a server-side application in Node.js, you have to deal with asynchronous and event-based programming. Although some patterns are emerging such as the Promise pattern, handling exceptions, cancellation, and synchronization is difficult and error-prone. Using RxJS, you can represent multiple asynchronous data streams (that come from diverse sources, e.g., stock quote, tweets, computer events, web service requests, etc.), and subscribe to the event stream using the Observer object. The Observable notifies the subscribed Observer instance whenever an event occurs. Because observable sequences are data streams, you can query them using standard query operators implemented by the Observable type. Thus you can filter, project, aggregate, compose and perform time-based operations on multiple events easily by using these operators. In addition, there are a number of other reactive stream specific operators that allow powerful queries to be written. Cancellation, exceptions, and synchronization are also handled gracefully by using the methods on the Observable object. But the best news of all is that you already know how to program like this. Take for example the following JavaScript code, where we get some stock data and then manipulate and iterate the results. ```js /* Get stock data somehow */ const source = getAsyncStockData(); const subscription = source .filter(quote => quote.price > 30) .map(quote => quote.price) .forEach(price => console.log(`Prices higher than $30: ${price}`); ``` Now what if this data were to come as some sort of event, for example a stream, such as a WebSocket? Then we could pretty much write the same query to iterate our data, with very little change. ```js /* Get stock data somehow */ const source = getAsyncStockData(); const subscription = source .filter(quote => quote.price > 30) .map(quote => quote.price) .subscribe( price => console.log(`Prices higher than $30: ${price}`), err => console.log(`Something went wrong: ${err.message}`); ); /* When we're done */ subscription.dispose(); ``` The only difference is that we can handle the errors inline with our subscription. And when we're no longer interested in receiving the data as it comes streaming in, we call `dispose` on our subscription. Note the use of `subscribe` instead of `forEach`. We could also use `forEach` which is an alias for `subscribe` but we highly suggest you use `subscribe`. ## Batteries Included ## Sure, there are a lot of libraries to get started with RxJS. Confused on where to get started? Start out with the complete set of operators with [`rx.all.js`](doc/libraries/main/rx.complete.md), then you can reduce it to the number of operators that you really need, and perhaps stick with something as small as [`rx.lite.js`](doc/libraries/lite/rx.lite.md). If you're an implementor of RxJS, then you can start out with [`rx.core.js`](doc/libraries/core/rx.core.md). This set of libraries include: ### The complete library: - [`rx.all.js`](doc/libraries/main/rx.complete.md) ### Main Libraries: - [`rx.js`](doc/libraries/main/rx.md) - [`rx.aggregates.js`](doc/libraries/main/rx.aggregates.md) - [`rx.async.js`](doc/libraries/main/rx.async.md) - [`rx.binding.js`](doc/libraries/main/rx.binding.md) - [`rx.coincidence.js`](doc/libraries/main/rx.coincidence.md) - [`rx.experimental.js`](doc/libraries/main/rx.experimental.md) - [`rx.joinpatterns.js`](doc/libraries/main/rx.joinpatterns.md) - [`rx.testing.js`](doc/libraries/main/rx.testing.md) - [`rx.time.js`](doc/libraries/main/rx.time.md) - [`rx.virtualtime.js`](doc/libraries/main/rx.virtualtime.md) ### Lite Libraries: - [`rx.lite.js`](doc/libraries/lite/rx.lite.md) - [`rx.lite.extras.js`](doc/libraries/lite/rx.lite.extras.md) - [`rx.lite.aggregates.js`](doc/libraries/lite/rx.lite.aggregates.md) - [`rx.lite.async.js`](doc/libraries/lite/rx.lite.async.md) - [`rx.lite.coincidence.js`](doc/libraries/lite/rx.lite.coincidence.md) - [`rx.lite.experimental.js`](doc/libraries/lite/rx.lite.experimental.md) - [`rx.lite.joinpatterns.js`](doc/libraries/lite/rx.lite.joinpatterns.md) - [`rx.lite.testing.js`](doc/libraries/lite/rx.lite.testing.md) - [`rx.lite.time.js`](doc/libraries/lite/rx.lite.time.md) - [`rx.lite.virtualtime.js`](doc/libraries/lite/rx.lite.virtualtime.md) ### Core Libraries: - [`rx.core.js`](doc/libraries/core/rx.core.md) - [`rx.core.binding.js`](doc/libraries/core/rx.core.binding.md) - [`rx.core.testing.js`](doc/libraries/core/rx.core.testing.md) ## Why RxJS? ## One question you may ask yourself is why RxJS? What about Promises? Promises are good for solving asynchronous operations such as querying a service with an XMLHttpRequest, where the expected behavior is one value and then completion. Reactive Extensions for JavaScript unify both the world of Promises, callbacks as well as evented data such as DOM Input, Web Workers, and Web Sockets. Unifying these concepts enables rich composition. To give you an idea about rich composition, we can create an autocompletion service which takes user input from a text input and then throttles queries a service (to avoid flooding the service with calls for every key stroke). First, we'll reference the JavaScript files, including jQuery, although RxJS has no dependencies on jQuery... ```html ``` Next, we'll get the user input from an input, listening to the keyup event by using the `Rx.Observable.fromEvent` method. This will either use the event binding from [jQuery](http://jquery.com), [Zepto](http://zeptojs.com/), [AngularJS](https://angularjs.org/), [Backbone.js](http://backbonejs.org/) and [Ember.js](http://emberjs.com/) if available, and if not, falls back to the native event binding. This gives you consistent ways of thinking of events depending on your framework, so there are no surprises. ```js const $input = $('#input'); const $results = $('#results'); /* Only get the value from each key up */ var keyups = Rx.Observable.fromEvent($input, 'keyup') .pluck('target', 'value') .filter(text => text.length > 2 ); /* Now debounce the input for 500ms */ var debounced = keyups .debounce(500 /* ms */); /* Now get only distinct values, so we eliminate the arrows and other control characters */ var distinct = debounced .distinctUntilChanged(); ``` Now, let's query Wikipedia! In RxJS, we can instantly bind to any [Promises A+](https://github.com/promises-aplus/promises-spec) implementation through the `Rx.Observable.fromPromise` method. Or, directly return it and RxJS will wrap it for you. ```js function searchWikipedia (term) { return $.ajax({ url: 'https://en.wikipedia.org/w/api.php', dataType: 'jsonp', data: { action: 'opensearch', format: 'json', search: term } }).promise(); } ``` Once that is created, we can tie together the distinct throttled input and query the service. In this case, we'll call `flatMapLatest` to get the value and ensure we're not introducing any out of order sequence calls. ```js var suggestions = distinct .flatMapLatest(searchWikipedia); ``` Finally, we call the `subscribe` method on our observable sequence to start pulling data. ```js suggestions.subscribe( data => { $results .empty() .append($.map(data[1], value => $('