Apollo Elements Apollo Elements Guides API Blog Toggle darkmode

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

subscription

ComponentDocument<D> | null
public

canAutoSubscribe

(read-only)
boolean

Flags an element that's ready and able to auto-subscribe

called

inherited from ApolloController
boolean

client

inherited from ApolloController
ApolloClient<NormalizedCacheObject> | null

The ApolloClient instance for this controller.

data

inherited from ApolloController
Data<D> | null

Latest data for the operation, or null.

document

inherited from ApolloController
ComponentDocument<D> | null

The GraphQL document for the operation.

error

inherited from ApolloController
ApolloError | null

Latest error from the operation, or null.

errors

inherited from ApolloController
readonly GraphQLError[]

Latest errors from the operation, or [].

loading

inherited from ApolloController
boolean

Whether a request is in-flight.

options

inherited from ApolloController
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

variables

inherited from ApolloController
Variables<D, V> | null

Variables for the operation.

Methods

public

subscribe

Starts 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
public

cancel

Ends the subscription

Returns

void

hostConnected

inherited from ApolloController

Returns

void

hostDisconnected

inherited from ApolloController

Returns

void

Events

Name Type Description
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 API

Private Properties

private

observableSubscription

ObservableSubscription | undefined
private

observable

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

#lastSubscriptionDocument

DocumentNode | undefined
private

#hasDisconnected

boolean
private

#client

inherited from ApolloController
ApolloClient<NormalizedCacheObject> | null
private

#document

inherited from ApolloController
ComponentDocument<D> | null
private

#options

inherited from ApolloController
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
protected

emitter

inherited from ApolloController
EventTarget

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

Private Methods

private

shouldSubscribe

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
private

onComplete

Shuts down the subscription

Returns

void
private

nextError

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

Parameters

error

ApolloError
private

nextData

Sets 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
private

initObservable

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
private

endSubscription

private

canSubscribe

Determines whether the element is able to automatically subscribe

Parameters

options

Partial<SubscriptionOptions<Variables<D, V> | null, 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
private

[update]

inherited from ApolloController

requests an update on the host.

Parameters

properties

Record<string, unknown>

Returns

void
protected

clientChanged

inherited from ApolloController

callback for when the Apollo client changes.

Parameters

client

ApolloClient<NormalizedCacheObject> | null

Returns

void
protected

documentChanged

inherited from ApolloController

callback for when the GraphQL document changes.

Parameters

doc

ComponentDocument<D> | null

Returns

void
protected

init

inherited from ApolloController

Assigns the controller's variables and GraphQL document.

Parameters

document

ComponentDocument<D> | null

Returns

void
protected

notify

inherited from ApolloController

Notifies about updated properties.

Parameters

keys

(keyof this)[]

Returns

void
protected

optionsChanged

inherited from ApolloController

callback 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
protected

variablesChanged

inherited from ApolloController

callback for when the GraphQL variables change.

Parameters

variables

Variables<D, V>

Returns

void

Exports

import { ApolloSubscriptionController } from '@apollo-elements/core/apollo-subscription-controller';