Absinthe Socket
npm install @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
- 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.
$ npm install --save phoenix @absinthe/socket
$ yarn add phoenix @absinthe/socket
``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
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
|};
`
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
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
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")
});
`
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>
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
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
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);
``
MIT :copyright: Jumpn Limited.