<commit_before>publication-client
=====

This module provides a client side module for subscribing to publications from
a [publication-server](https://github.com/mixmaxhq/publication-server).

## Installation
```
$ npm install --save @mixmaxhq/publication-client
```

## Usage

### Requirements

`publication-client` is an ES6 module, so you most likely want to use a bundler
such as [rollup](https://github.com/rollup/rollup). It also depends on
`underscore`, so make sure that the project using `publication-client` can
resolve `underscore`, this normally means either:
  - `npm install`ing the module and using [rollup-plugin-node-resolve](https://github.com/rollup/rollup-plugin-node-resolve)
  - if you already have underscore somewhere else locally in your build, you
    can make an alias to is using [rollup-plugin-alias](https://github.com/frostney/rollup-plugin-alias)

### Initialization

The only required field for creating a client is the host to connect to as a
URL. This means that if you have the publication server mounted at
`wss://sub.domain.tld/websocket` we would provide `https://sub.domain.tld` as
the URL param. Also note that you can provide query params to be passed as
part of the provided connect URL (i.e. `https://sub.domain.tld?foo=bar`).

```js
import PublicationClient from 'publication-client';

var client = new PublicationClient(`https://testing.domain.com?foo=bar`);
```

#### Checking connection state

The publication client exposes a promise that can be used to know when a client
has successfully connected.

```js
client.whenConnected().then(() => {
  console.log('connected successfully!');
});
```

### Subscribing

To subscribe to a publication, simply provide the publication name and any
parameters for it. The subscription will not begin until the connection has
been successfully connected.

```js
client.subscribe('hello', {
  actor: 'world'
});
```

Subscriptions also can be queried for 'readiness':

```js
client.subscribe('foo').whenReady().then(() => {
  console.log('subscription is ready!');
});
```

### Querying collections

The publication client also manages all collections created by the subscribed
publications. Retrieving a collection is as simple as:

```js
var collection = client.getCollection('baz');
```<commit_msg>Update README for new events<commit_after>publication-client
=====

This module provides a client side module for subscribing to publications from
a [publication-server](https://github.com/mixmaxhq/publication-server).

## Installation
```
$ npm install --save @mixmaxhq/publication-client
```

## Usage

### Requirements

`publication-client` is an ES6 module, so you most likely want to use a bundler
such as [rollup](https://github.com/rollup/rollup). It also depends on
`underscore`, so make sure that the project using `publication-client` can
resolve `underscore`, this normally means either:
  - `npm install`ing the module and using [rollup-plugin-node-resolve](https://github.com/rollup/rollup-plugin-node-resolve)
  - if you already have underscore somewhere else locally in your build, you
    can make an alias to is using [rollup-plugin-alias](https://github.com/frostney/rollup-plugin-alias)

### Initialization

The only required field for creating a client is the host to connect to as a
URL. This means that if you have the publication server mounted at
`wss://sub.domain.tld/websocket` we would provide `https://sub.domain.tld` as
the URL param. Also note that you can provide query params to be passed as
part of the provided connect URL (i.e. `https://sub.domain.tld?foo=bar`).

```js
import PublicationClient from 'publication-client';

var client = new PublicationClient(`https://testing.domain.com?foo=bar`);
```

#### Checking connection state

The publication client emits a `connected` event once it has successfully
connected.

```js
client.once('connected', () => {
  console.log('connected successfully!');
});
```

It also emits `disconnected` event as soon as it becomes disconnected, and
will emit a `connected` event if it is able to successfully connect to the
publication server again.
```js
client.on('disconnected', () => {
  console.log('Oh no! Our connection is gone!');

  client.once('connected', () => {
    console.log('Phew! We have a new connection again!');
  });
});
```

### Subscribing

To subscribe to a publication, simply provide the publication name and any
parameters for it. The subscription will not begin until the connection has
been successfully connected.

```js
client.subscribe('hello', {
  actor: 'world'
});
```

Subscriptions also can be queried for 'readiness'. They can return a Promise
via the `whenReady` function, and also emit a `ready` event.

```js
client.subscribe('foo').whenReady().then(() => {
  console.log('subscription is ready!');
});
```

#### Waiting on initial subscriptions to load
`whenReady` is provided as a convenience function if you want to be able to
wait for a single subscription or for multiple subscriptions to complete
before performing some action. For example:

```js
var sub0 = client.subscribe('sub0'),
    sub1 = client.subscribe('sub1'),
    sub2 = client.subscribe('sub2');
Promise.all(_.invoke([sub0, sub1, sub2], 'whenReady')).then(() => {
  console.log('Our initial subscriptions are all ready!');
});

``

### Querying collections

The publication client also manages all collections created by the subscribed
publications. Retrieving a collection is as simple as:

```js
var collection = client.getCollection('baz');
```
{'fraction_non_alphanumeric': 0.11894832275611968, 'fraction_numerical': 0.0019945602901178605, 'mean_word_length': 4.837037037037037, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 10, 'https://': 14, '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': '1497216', 'n_tokens_mistral': 1571, 'n_tokens_neox': 1515, 'n_words': 607}