Controllers: ApolloSubscriptionController

ApolloSubscriptionController lets you subscribe to real-time updated from your GraphQL server. Pass it a GraphQL subscription document, and any options you choose, and it will update its host when it’s state (e.g. data, error, or loading) changes.

The (optional) third argument to the constructor is an ApolloSubscriptionControllerOptions object.

Apollo Elements controllers are not limited to Lit. Use them with any object that implements the ReactiveControllerHost interface. See ControllerHostMixin for an example.

 
import { ApolloSubscriptionController } from '@apollo-elements/core';
import { customElement, query } from 'lit/decorators.js';
import { html, LitElement } from 'lit';

import { UserJoinedSubscription } from './UserJoined.subscription.graphql.js';

import { Snackbar } from '@material/mwc-snackbar';

@customElement('user-joined')
class UserJoined extends LitElement {
  userJoined = new ApolloSubscriptionController(this, UserJoinedSubscription, {
    onData: ({ subscriptionData }) => {
      this.last = subscriptionData.userJoined,
      this.snackbar.show();
    }
  });

  @query('mwc-snackbar'): Snackbar;

  render() {
    return html`
      <mwc-snackbar labeltext="${this.userJoined?.data?.name}"></mwc-snackbar>
    `;
  }
}

Properties

options

ApolloControllerOptions<D, V>
Options to customize the subscription and to interface with the controller.
Option Type Description
client ApolloClient ApolloClient instance for the subscription.
fetchPolicy FetchPolicy See fetchPolicy
noAutoSubscribe boolean If set, the component will not subscribe until called explicitly. See noAutoSubscribe
onError (error: ApolloError) => void Callback for when subscription produces an error
onData (result: OnSubscriptionDataParams<Data<D>>) => void Callback for when subscription produces new data
onSubscriptionComplete () => void Callback for when the subscription ends
shouldResubscribe boolean Determines if your subscription should be unsubscribed and subscribed again
shouldSubscribe (op?: Partial<Operation<D, V>>) => boolean Predicate which determines whether to automatically subscribe. See shouldSubscribe
skip boolean When true, the subscription will not fetch at all.
subscription DocumentNode Subscription GraphQL Document
variables Variables<D, V> Subscription variables

Inherits from ApolloControllerOptions

subscription

ComponentDocument<D, V> | null

canAutoSubscribe

public(read-only)
boolean
Flags an element that’s ready and able to auto-subscribe

called

boolean

data

Data<D> | null
Latest data for the operation, or null.

error

Error | null
Latest error from the operation, or null.

errors

readonly GraphQLError[]
Latest errors from the operation, or [].

loading

boolean
Whether a request is in-flight.

client

ApolloClient | null
The ApolloClient instance for this controller.

document

ComponentDocument<D, V> | null
The GraphQL document for the operation.

variables

Variables<D, V> | null
Variables for the operation.

Methods

hostConnected

Returns

void

hostDisconnected

Returns

void

subscribe

publicStarts the subscription

Parameters

params

Partial<SubscriptionDataOptions<D, V>>
Option Type Description
client ApolloClient Apollo Client to use for the subscription.
context Record<string, unknown> Context object passed through the link execution chain.
errorPolicy ErrorPolicy Error policy to use for the subscription. See errorPolicy
fetchPolicy FetchPolicy See fetchPolicy
shouldResubscribe boolean Boolean, or a predicate function of SubscriptionDataOptions that determines if your subscription should be unsubscribed and subscribed again
skip boolean If skip is true, the subscription will be skipped entirely.
subscription DocumentNode GraphQL document with a single subscription.
variables Variables<D, V> An object containing all of the variables your subscription needs to execute.

Returns

void

cancel

publicEnds the subscription

Returns

void

Events

apollo-controller-connected

ApolloControllerConnectedEvent
The controller’s host connected to the DOM.

apollo-controller-disconnected

ApolloControllerDisconnectedEvent
The controller’s host disconnected from the DOM.

Private Properties

observable

private
Observable<FetchResult<Data<D>>> | undefined

observableSubscription

private
Subscription | undefined

#hasDisconnected

private
boolean

#lastSubscriptionDocument

private
DocumentNode | undefined

#options

private
ApolloControllerOptions<D, V>
Option Type Description
client ApolloClient<NormalizedCacheObject> The ApolloClient instance for the controller.
variables Variables<D, V> Variables for the operation.
context any Context passed to the link execution chain.
errorPolicy ErrorPolicy the error policy for the operation
hostElement HTMLElement When provided, the controller will fall back to this element to fire events

#client

private
ApolloClient | null

#document

private
ComponentDocument<D, V> | null

emitter

protected
EventTarget
The event emitter to use when firing events, usually the host element.

Private Methods

canSubscribe

privateDetermines whether the element is able to automatically subscribe

Parameters

options

Partial<SubscriptionOptions<Variables<D, V>, Data<D>>>
Property Type Description
query DocumentNode See query
variables Variables<D, V> See variables
fetchPolicy FetchPolicy See fetchPolicy
errorPolicy ErrorPolicy See errorPolicy
context Record<string, unknown> Context object passed through the link execution chain.

Returns

boolean

initObservable

private

Parameters

params

Partial<SubscriptionDataOptions<D, V>>
Option Type Description
client ApolloClient Apollo Client to use for the subscription.
context Record<string, unknown> Context object passed through the link execution chain.
errorPolicy ErrorPolicy Error policy to use for the subscription. See errorPolicy
fetchPolicy FetchPolicy See fetchPolicy
shouldResubscribe boolean Boolean, or a predicate function of SubscriptionDataOptions that determines if your subscription should be unsubscribed and subscribed again
skip boolean If skip is true, the subscription will be skipped entirely.
subscription DocumentNode GraphQL document with a single subscription.
variables Variables<D, V> An object containing all of the variables your subscription needs to execute.

Returns

void

nextData

privateSets data, loading, and error on the instance when new subscription results arrive.

Parameters

result

FetchResult<Data<D>>
Property Type Description
data Data<D, V> The result of a successful execution of the mutation
errors readonly GraphQLError[] included when any errors occurred as a non-empty array
extensions boolean Reserved for adding non-standard properties
context Record<string, unknown> See context

nextError

privateSets error and loading on the instance when the subscription errors.

Parameters

apolloError

Error

onComplete

privateShuts down the subscription

Returns

void

endSubscription

private

shouldSubscribe

private

Parameters

opts

Partial<SubscriptionOptions<Variables<D, V>, Data<D>>>
Property Type Description
query DocumentNode See query
variables Variables<D, V> See variables
fetchPolicy FetchPolicy See fetchPolicy
errorPolicy ErrorPolicy See errorPolicy
context Record<string, unknown> Context object passed through the link execution chain.

Returns

boolean

clientChanged

protectedcallback for when the Apollo client changes.

Parameters

client

ApolloClient | null

Returns

void

documentChanged

protectedcallback for when the GraphQL document changes.

Parameters

doc

ComponentDocument<D, V> | null

Returns

void

variablesChanged

protectedcallback for when the GraphQL variables change.

Parameters

variables

Variables<D, V>

Returns

void

notify

protectedrequests an update on the host with the provided properties.

Parameters

properties

Record<string, unknown>

Returns

void

optionsChanged

protectedcallback for when the options change.

Parameters

options

ApolloControllerOptions<D, V>
Option Type Description
client ApolloClient<NormalizedCacheObject> The ApolloClient instance for the controller.
variables Variables<D, V> Variables for the operation.
context any Context passed to the link execution chain.
errorPolicy ErrorPolicy the error policy for the operation
hostElement HTMLElement When provided, the controller will fall back to this element to fire events

Returns

void

init

protectedAssigns the controller’s variables and GraphQL document.

Parameters

document

ComponentDocument<D, V> | null

Returns

void

Exports

js ApolloSubscriptionController from apollo-subscription-controller.js