npm package: @r26d/absinthe-apollo-socket
Description: Absinthe Socket - Allows the connection
Latest version: 1.1.4

# @r26d/absinthe-apollo-socket

> Absinthe Socket - Allows the connection

<!-- START doctoc generated TOC please keep comment here to allow auto update -->
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
<!-- END doctoc -->

- [Features](#features)
- [Installation](#installation)
  - [Using npm](#using-npm)
  - [Using yarn](#using-yarn)
- [API](#api)
  - [cancel](#cancel)
    - [Parameters](#parameters)
    - [Examples](#examples)
  - [create](#create)
    - [Parameters](#parameters-1)
    - [Examples](#examples-1)
  - [observe](#observe)
    - [Parameters](#parameters-2)
    - [Examples](#examples-2)
  - [send](#send)
    - [Parameters](#parameters-3)
    - [Examples](#examples-3)
  - [toObservable](#toobservable)
    - [Parameters](#parameters-4)
    - [Examples](#examples-4)
  - [unobserve](#unobserve)
    - [Parameters](#parameters-5)
    - [Examples](#examples-5)
  - [unobserveOrCancel](#unobserveorcancel)
    - [Parameters](#parameters-6)
    - [Examples](#examples-6)
- [License](#license)

<!-- END doctoc generated TOC please keep comment here to allow auto update -->

## Features

*   Immutable functional API

> All received and returned objects with the exception of AbsintheSocket
> instances (there are plans to make this immutable too) are treated in an
> immutable way. Objects have no methods and instead we provide independant
> stateless functions to interact with them.

*   Lazy connect / join

> If provided phoenix socket instance is not connected, then instead of
> connecting at creation time, connection will be established on the next
> invocation of [send](#send).

*   Handle pending operations on connection lost

> Pending mutations will be aborted, queries will be resent, and subscriptions
> reestablished.

*   Cancellable requests

> Calling [cancel](#cancel) removes given notifier from absintheSocket instance
> and sends a Cancel event to all its observers and unsubscribes in case it
> holds a subscription request.

*   Operations deduplication

> If an already sent request is given to [send](#send), then instead of sending
> it again, the notifier associated with it will be returned.

*   Observer support of recoverable errors

> Since connection lost is handled, then two events needs to exist to represent
> this fact: Error (recoverable), Abort (unrecoverable).

*   Multiple observers per request

> Calling [send](#send) returns a notifier which allows attaching any number of
> observers that will be notified when result arrives.

*   Observer interaction depending on operation type

> For the case of subscriptions, *Start* event is dispatched when the
> subscription is established, while for the other types
> (queries and mutations), when the request is sent.

## Installation

### Using [npm](https://docs.npmjs.com/cli/npm)

    $ npm install --save phoenix @r26d/absinthe-apollo-socket

### Using [yarn](https://yarnpkg.com)

    $ yarn add phoenix @r26d/absinthe-apollo-socket

## API

<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### cancel

Cancels a notifier sending a Cancel event to all its observers and
unsubscribing in case it holds a subscription request

#### Parameters

*   `absintheSocket` &#x20;
*   `notifier` &#x20;

#### Examples

```javascript
import * as withAbsintheSocket from "@absinthe/socket";

withAbsintheSocket.cancel(absintheSocket, notifier);
```

### create

Creates an Absinthe Socket using the given Phoenix Socket instance

#### Parameters

*   `phoenixSocket` &#x20;

#### Examples

```javascript
import * as withAbsintheSocket from "@absinthe/socket";
import {Socket as PhoenixSocket} from "phoenix";

const absintheSocket = withAbsintheSocket.create(
  new PhoenixSocket("ws://localhost:4000/socket")
);
```

### observe

Observes given notifier using the provided observer

#### Parameters

*   `absintheSocket` &#x20;
*   `notifier` &#x20;
*   `observer` &#x20;

#### Examples

```javascript
import * as withAbsintheSocket from "@absinthe/socket"

const logEvent = eventName => (...args) => console.log(eventName, ...args);

const updatedNotifier = withAbsintheSocket.observe(absintheSocket, notifier, {
  onAbort: logEvent("abort"),
  onError: logEvent("error"),
  onStart: logEvent("open"),
  onResult: logEvent("result")
});
```

### send

Sends given request and returns an object (notifier) to track its progress
(see observe function)

#### Parameters

*   `absintheSocket` &#x20;
*   `request` &#x20;

#### Examples

```javascript
import * as withAbsintheSocket from "@absinthe/socket";

const operation = `
  subscription userSubscription($userId: ID!) {
    user(userId: $userId) {
      id
      name
    }
  }
`;

// This example uses a subscription, but the functionallity is the same for
// all operation types (queries, mutations and subscriptions)

const notifier = withAbsintheSocket.send(absintheSocket, {
  operation,
  variables: {userId: 10}
});
```

### toObservable

Creates an Observable that will follow the given notifier

#### Parameters

*   `absintheSocket` **AbsintheSocket**&#x20;
*   `notifier` **Notifier\<Result, Variables>**&#x20;
*   `options` **[Object](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object)?**  (optional, default `{}`)

    *   `options.unsubscribe` **function (): [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)?**&#x20;
    *   `options.onError` **function (error: [Error](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Error)): [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)?**&#x20;
    *   `options.onStart` **function (notifier: Notifier\<Result, Variables>): [undefined](https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/undefined)?**&#x20;
    *   `options.handlers` **...any**&#x20;

#### Examples

```javascript
import * as withAbsintheSocket from "@absinthe/socket";

const unobserveOrCancelIfNeeded = (absintheSocket, notifier, observer) => {
  if (notifier && observer) {
    withAbsintheSocket.unobserveOrCancel(absintheSocket, notifier, observer);
  }
};

const logEvent = eventName => (...args) => console.log(eventName, ...args);

const observable = withAbsintheSocket.toObservable(absintheSocket, notifier, {
  onError: logEvent("error"),
  onStart: logEvent("open"),
  unsubscribe: unobserveOrCancelIfNeeded
});
```

Returns **Observable**&#x20;

### unobserve

Detaches observer from notifier

#### Parameters

*   `absintheSocket` &#x20;
*   `notifier` &#x20;
*   `observer` &#x20;

#### Examples

```javascript
import * as withAbsintheSocket from "@absinthe/socket";

withAbsintheSocket.unobserve(absintheSocket, notifier, observer);
```

### unobserveOrCancel

Cancels notifier if there are no more observers apart from the one given, or
detaches given observer from notifier otherwise

#### Parameters

*   `absintheSocket` &#x20;
*   `notifier` &#x20;
*   `observer` &#x20;

#### Examples

```javascript
import * as withAbsintheSocket from "@absinthe/socket";

withAbsintheSocket.unobserve(absintheSocket, notifier, observer);
```

## License

[MIT](LICENSE.txt) :copyright:  r26D LLC