readmeTemplate.ejs

# <%= name %>

> <%= description %>

<!-- START doctoc -->
<!-- END doctoc -->

## 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 <%= name %>
```

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

```
$ yarn add phoenix <%= name %>
```

## Types

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

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

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

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

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

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

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

## API

## License

[<%= license %>](LICENSE.txt) :copyright: Jumpn Limited.