<commit_before># RxJS Primer

Brand new to RxJS? In this article we will take a crash course through all the
major concepts you will need to begin getting a grasp on, and start being
productive with RxJS. Hold on tight and let's get started!

## What is an Observable?

An observable represents a stream, or source of data that can arrive over time.
You can create an observable from nearly anything, but the most common use case
in RxJS is from events. This can be anything from mouse moves, button clicks,
input into a text field, or even route changes. The easiest way to create an
observable is through the built in creation functions. For example, we can use
the [`fromEvent`](../operators/creation/fromevent.md) helper function to create
an observable of mouse click events:

```js
// import the fromEvent operator
import { fromEvent } from 'rxjs';

// grab button reference
const button = document.getElementById('myButton');

// create an observable of button clicks
const myObservable = fromEvent(button, 'click');
```

At this point we have an observable but it's not doing anything. **This is
because observables are cold, or do not activate a producer (like wiring up an
event listener), until there is a...**

## Subscription

Subscriptions are what set everything in motion. You can think of this like a
faucet, you have a stream of water ready to be tapped (observable), someone just
needs to turn the handle. In the case of observables, that role belongs to the
`subscriber`.

To create a subscription, you call the `subscribe` method, supplying a function
(or object) - also known as an `observer`. This is where you can decide how to
**react**(-ive programming) to each event. Let's walk through what happens in
the previous scenario when a subscription is created:

```js
// import the fromEvent operator
import { fromEvent } from 'rxjs';

// grab button reference
const button = document.getElementById('myButton');

// create an observable of button clicks
const myObservable = fromEvent(button, 'click');

// for now, let's just log the event on each click
const subscription = myObservable.subscribe(event => console.log(event));
```

In the example above, calling `myObservable.subscribe()` will:

1. Set up an event listener on our button for click events.
2. Call the function we passed to the subscribe method (observer) on each click
   event.
3. Return a subscription object with an `unsubscribe` which contains clean up
   logic, like removing appropriate event listeners.

The subscribe method also accepts an object map to handle the case of error or
completion. You probably won't use this as much as simply supplying a function,
but it's good to be aware of should the need arise:

```js
// instead of a function, we will pass an object with next, error, and complete methods
const subscription = myObservable.subscribe({
  // on successful emissions
  next: event => console.log(event),
  // on errors
  error: error => console.log(error),
  // called once on completion
  complete: () => console.log('complete!')
});
```

It's important to note that each subscription will create a new execution
context. This means calling `subscribe` a second time will create a new event
listener:

```js
// addEventListener called
const subscription = myObservable.subscribe(event => console.log(event));

// addEvent listener called again!
const secondSubscription = myObservable.subscribe(event => console.log(event));

// clean up with unsubscribe
subscription.unsubscribe();
secondSubscription.unsubscribe();
```

By default, a subscription creates a one on one, one-sided conversation between
the observable and observer. This is like your boss (the observable) yelling
(emitting) at you (the observer) for merging a bad PR. This is also known as
**unicasting**. If you prefer a conference talk scenario - one observable, many
observers - you will take a different approach which includes **multicasting**
with `Subjects` (either explicitly or behind the scenes). More on that in a
future article!

It's worth noting that when we discuss an Observable source emitting data to
observers, this is a push based model. The source doesn't know or care what
subscribers do with the data, it simply pushes it down the line.

While working on a stream of events is nice, it's only so useful on it's own.
**What makes RxJS the "lodash for events" are its...**

## Operators

Operators offer a way to manipulate values from a source, returning an
observable of the transformed values. Many of the RxJS operators will look
familiar if you are used to JavaScripts `Array` methods. For instance, if you
want to transform emitted values from an observable source, you can use
[`map`](../operators/transformation/map.md):

```js
// import the from operator
import { of } from 'rxjs';
/*
 *  'of' allows you to deliver values in a sequence
 *  In this case, it will emit 1,2,3,4,5 in order.
 */
const dataSource = of(1, 2, 3, 4, 5);

// subscribe to our source observable
const subscription = dataSource
  .pipe(
    // add 1 to each emitted value
    map(value => value + 1)
  )
  // log: 2, 3, 4, 5, 6
  .subscribe(value => console.log(value));
```

Or if you want to filter for specific values, you can use
[`filter`](../operators/filtering/filter.md):<commit_msg>style(article): add import to example<commit_after># RxJS Primer

Brand new to RxJS? In this article we will take a crash course through all the
major concepts you will need to begin getting a grasp on, and start being
productive with RxJS. Hold on tight and let's get started!

## What is an Observable?

An observable represents a stream, or source of data that can arrive over time.
You can create an observable from nearly anything, but the most common use case
in RxJS is from events. This can be anything from mouse moves, button clicks,
input into a text field, or even route changes. The easiest way to create an
observable is through the built in creation functions. For example, we can use
the [`fromEvent`](../operators/creation/fromevent.md) helper function to create
an observable of mouse click events:

```js
// import the fromEvent operator
import { fromEvent } from 'rxjs';

// grab button reference
const button = document.getElementById('myButton');

// create an observable of button clicks
const myObservable = fromEvent(button, 'click');
```

At this point we have an observable but it's not doing anything. **This is
because observables are cold, or do not activate a producer (like wiring up an
event listener), until there is a...**

## Subscription

Subscriptions are what set everything in motion. You can think of this like a
faucet, you have a stream of water ready to be tapped (observable), someone just
needs to turn the handle. In the case of observables, that role belongs to the
`subscriber`.

To create a subscription, you call the `subscribe` method, supplying a function
(or object) - also known as an `observer`. This is where you can decide how to
**react**(-ive programming) to each event. Let's walk through what happens in
the previous scenario when a subscription is created:

```js
// import the fromEvent operator
import { fromEvent } from 'rxjs';

// grab button reference
const button = document.getElementById('myButton');

// create an observable of button clicks
const myObservable = fromEvent(button, 'click');

// for now, let's just log the event on each click
const subscription = myObservable.subscribe(event => console.log(event));
```

In the example above, calling `myObservable.subscribe()` will:

1. Set up an event listener on our button for click events.
2. Call the function we passed to the subscribe method (observer) on each click
   event.
3. Return a subscription object with an `unsubscribe` which contains clean up
   logic, like removing appropriate event listeners.

The subscribe method also accepts an object map to handle the case of error or
completion. You probably won't use this as much as simply supplying a function,
but it's good to be aware of should the need arise:

```js
// instead of a function, we will pass an object with next, error, and complete methods
const subscription = myObservable.subscribe({
  // on successful emissions
  next: event => console.log(event),
  // on errors
  error: error => console.log(error),
  // called once on completion
  complete: () => console.log('complete!')
});
```

It's important to note that each subscription will create a new execution
context. This means calling `subscribe` a second time will create a new event
listener:

```js
// addEventListener called
const subscription = myObservable.subscribe(event => console.log(event));

// addEvent listener called again!
const secondSubscription = myObservable.subscribe(event => console.log(event));

// clean up with unsubscribe
subscription.unsubscribe();
secondSubscription.unsubscribe();
```

By default, a subscription creates a one on one, one-sided conversation between
the observable and observer. This is like your boss (the observable) yelling
(emitting) at you (the observer) for merging a bad PR. This is also known as
**unicasting**. If you prefer a conference talk scenario - one observable, many
observers - you will take a different approach which includes **multicasting**
with `Subjects` (either explicitly or behind the scenes). More on that in a
future article!

It's worth noting that when we discuss an Observable source emitting data to
observers, this is a push based model. The source doesn't know or care what
subscribers do with the data, it simply pushes it down the line.

While working on a stream of events is nice, it's only so useful on it's own.
**What makes RxJS the "lodash for events" are its...**

## Operators

Operators offer a way to manipulate values from a source, returning an
observable of the transformed values. Many of the RxJS operators will look
familiar if you are used to JavaScripts `Array` methods. For instance, if you
want to transform emitted values from an observable source, you can use
[`map`](../operators/transformation/map.md):

```js
// import the from operator
import { of } from 'rxjs';
import { map } from 'rxjs/operators';
/*
 *  'of' allows you to deliver values in a sequence
 *  In this case, it will emit 1,2,3,4,5 in order.
 */
const dataSource = of(1, 2, 3, 4, 5);

// subscribe to our source observable
const subscription = dataSource
  .pipe(
    // add 1 to each emitted value
    map(value => value + 1)
  )
  // log: 2, 3, 4, 5, 6
  .subscribe(value => console.log(value));
```

Or if you want to filter for specific values, you can use
[`filter`](../operators/filtering/filter.md):
{'fraction_non_alphanumeric': 0.08032015065913371, 'fraction_numerical': 0.003766478342749529, 'mean_word_length': 4.289342629482071, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 19, 'https://': 0, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '735170', 'n_tokens_mistral': 2859, 'n_tokens_neox': 2704, 'n_words': 1517}