@r26d/absinthe-apollo-socket

Absinthe Socket - Allows the connection

• Features
• Installation
  • Using npm
  • Using yarn
• 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

Using npm

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

Using yarn

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

API

cancel

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

Parameters

• absintheSocket
• notifier

Examples

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

withAbsintheSocket.cancel(absintheSocket, notifier);

create

Creates an Absinthe Socket using the given Phoenix Socket instance

Parameters

• phoenixSocket

Examples

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
• notifier
• observer

Examples

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
• request

Examples

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

• 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

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

unobserve

Detaches observer from notifier

Parameters

• absintheSocket
• notifier
• observer

Examples

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
• notifier
• observer

Examples

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

withAbsintheSocket.unobserve(absintheSocket, notifier, observer);

License

MIT :copyright: r26D LLC