Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/jumpn/absinthe-phoenix-socket
Absinthe Phoenix Socket
https://github.com/jumpn/absinthe-phoenix-socket
absinthe absinthe-graphql elixir-phoenix functional-programming graphql immutable phoenix
Last synced: 20 days ago
JSON representation
Absinthe Phoenix Socket
- Host: GitHub
- URL: https://github.com/jumpn/absinthe-phoenix-socket
- Owner: jumpn
- License: mit
- Created: 2017-09-25T01:16:28.000Z (over 7 years ago)
- Default Branch: master
- Last Pushed: 2017-11-06T01:33:44.000Z (over 7 years ago)
- Last Synced: 2024-12-21T15:48:51.778Z (about 2 months ago)
- Topics: absinthe, absinthe-graphql, elixir-phoenix, functional-programming, graphql, immutable, phoenix
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/@jumpn/absinthe-phoenix-socket
- Size: 481 KB
- Stars: 2
- Watchers: 5
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE.txt
Awesome Lists containing this project
README
# @jumpn/absinthe-phoenix-socket
> Absinthe Phoenix Socket
- [Features](#features)
- [Installation](#installation)
- [Using npm](#using-npm)
- [Using yarn](#using-yarn)
- [Types](#types)
- [API](#api)
- [cancel](#cancel)
- [create](#create)
- [observe](#observe)
- [send](#send)
- [toObservable](#toobservable)
- [unobserve](#unobserve)
- [License](#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](#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 @jumpn/absinthe-phoenix-socket
### Using [yarn](https://yarnpkg.com)
$ yarn add @jumpn/absinthe-phoenix-socket
## Types
```flowtype
// from @jumpn/utils-graphql
type GqlRequest = {
operation: string,
variables?: Variables
};
type Event = "Abort" | "Cancel" | "Error" | "Start" | "Result";
type Observer = {
onAbort: (error: Error) => any,
onCancel: (error: Error) => any,
onError: (error: Error) => any,
onStart: () => any,
onResult: (result: Result) => any
};
type Notifier = {
observers: Array>,
operationType: GqlOperationType,
request: GqlRequest<*>,
subscriptionId?: string
};
type AbsintheSocket = {
channel: Channel,
channelJoinCreated: boolean,
notifiers: Array>,
phoenixSocket: PhoenixSocket
};
```
## API
### cancel
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>**
**Examples**
```javascript
import * as AbsintheSocket from "@jumpn/absinthe-phoenix-socket";
AbsintheSocket.cancel(absintheSocket, notifier);
```
Returns **AbsintheSocket**
### create
Creates an Absinthe Socket using the given Phoenix Socket instance
**Parameters**
- `phoenixSocket` **PhoenixSocket**
**Examples**
```javascript
import * as AbsintheSocket from "@jumpn/absinthe-phoenix-socket";
import {Socket as PhoenixSocket} from "phoenix";
const absintheSocket = AbsintheSocket.create(
new PhoenixSocket("ws://localhost:4000/socket")
);
```
Returns **AbsintheSocket**
### observe
Observes given notifier using the provided observer
**Parameters**
- `absintheSocket` **AbsintheSocket**
- `notifier` **Notifier<Result>**
- `observer` **Observer<Result>**
**Examples**
```javascript
import AbsintheSocket from "@jumpn/absinthe-phoenix-socket"
const logEvent = eventName => (...args) => console.log(eventName, ...args);
const updatedNotifier = AbsintheSocket.observe(absintheSocket, notifier, {
onAbort: logEvent("abort"),
onError: logEvent("error"),
onStart: logEvent("open"),
onResult: logEvent("result")
});
```
Returns **AbsintheSocket**
### send
Sends given request and returns an object (notifier) to track its progress
(see observe function)
**Parameters**
- `absintheSocket` **AbsintheSocket**
- `request` **GqlRequest<any>**
**Examples**
```javascript
import * as AbsintheSocket from "@jumpn/absinthe-phoenix-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 = AbsintheSocket.send(absintheSocket, {
operation,
variables: {userId: 10}
});
```
Returns **Notifier<any>**
### toObservable
Creates an Observable that will follow the given notifier
**Parameters**
- `absintheSocket` **AbsintheSocket**
- `notifier` **Notifier<Result>**
- `options` **[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object)?** (optional, default `{}`)
- `options.onError` **function (error: [Error](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)): [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)?**
- `options.onStart` **function (notifier: Notifier<Result>): [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)?**
- `options.unsubscribe` **function (): [undefined](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/undefined)?**
Returns **Observable**
### unobserve
Detaches observer from notifier
**Parameters**
- `absintheSocket` **AbsintheSocket**
- `notifier` **Notifier<any>**
- `observer` **Observer<any>**
**Examples**
```javascript
import * as AbsintheSocket from "@jumpn/absinthe-phoenix-socket";
AbsintheSocket.unobserve(absintheSocket, notifier, observer);
```
Returns **AbsintheSocket**
## License
[MIT](LICENSE.txt) :copyright: **Jumpn Limited** / Mauro Titimoli ([email protected])