@absinthe/socket

> Absinthe Socket

- Features
- Installation
- Using npm
- Using yarn
- Types
- API
- cancel
- Parameters
- Examples
- create
- Parameters
- Examples
- observe
- Parameters
- Examples
- send
- Parameters
- Examples
- toObservable
- Parameters
- Examples
- unobserve
- Parameters
- Examples
- unobserveOrCancel
- Parameters
- Examples
- License

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.
- Handle pending operations on connection lost
> Pending mutations will be aborted, queries will be resent, and subscriptions
> reestablished.
- Cancellable requests
> Calling 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, 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 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

$3

$ npm install --save phoenix @absinthe/socket

$3

$ yarn add phoenix @absinthe/socket

Types

``flowtype
type RequestStatus = "canceled" | "canceling" | "pending" | "sent" | "sending";

// from @jumpn/utils-graphql
type GqlRequest = {
operation: string,
variables?: Variables
};

// from @jumpn/utils-graphql
type GqlResponse = {
data?: Data,
errors?: Array
};

// from @jumpn/utils-graphql
type GqlOperationType = "mutation" | "query" | "subscription";

type Observer = {|
onAbort?: (error: Error) => any,
onCancel?: () => any,
onError?: (error: Error) => any,
onStart?: (notifier: Notifier) => any,
onResult?: (result: Result) => any
|};

type Notifier = {|
activeObservers: $ReadOnlyArray>,
canceledObservers: $ReadOnlyArray>,
isActive: boolean,
operationType: GqlOperationType,
request: GqlRequest,
requestStatus: RequestStatus,
subscriptionId?: string
|};

type AbsintheSocket = {|
channel: Channel,
channelJoinCreated: boolean,
notifiers: Array>,
phoenixSocket: PhoenixSocket
|};
`

API

$3

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

#### Parameters

- absintheSocket AbsintheSocket
- notifier Notifier<any, any>

#### Examples

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

withAbsintheSocket.cancel(absintheSocket, notifier);
`

Returns AbsintheSocket

$3

Creates an Absinthe Socket using the given Phoenix Socket instance

#### Parameters

- phoenixSocket PhoenixSocket

#### Examples

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

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

Returns AbsintheSocket

$3

Observes given notifier using the provided observer

#### Parameters

- absintheSocket AbsintheSocket
- notifier Notifier<Result, Variables>
- observer Observer<Result, Variables>

#### 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")
});
`

$3

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

#### Parameters

- absintheSocket AbsintheSocket
- request GqlRequest<Variables>

#### 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}
});
`

Returns Notifier<Result, Variables>

$3

Creates an Observable that will follow the given notifier

#### Parameters

- absintheSocket AbsintheSocket
- notifier Notifier<Result, Variables>
- options Object? (optional, default {})
- options.unsubscribe function (): undefined?
- options.onError function (error: Error): undefined?
- options.onStart function (notifier: Notifier<Result, Variables>): undefined?
- options.handlers ...any

#### 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

$3

Detaches observer from notifier

#### Parameters

- absintheSocket AbsintheSocket
- notifier Notifier<any, any>
- observer Observer<any, any>

#### Examples

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

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

Returns AbsintheSocket

$3

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

#### Parameters

- absintheSocket AbsintheSocket
- notifier Notifier<Result, Variables>
- observer Observer<Result, Variables>

#### Examples

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

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

License

MIT :copyright: Jumpn Limited.