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, V> | 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, V> | 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

Starts the subscription

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.

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, V> | 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

apolloError

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

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, V> | null

Returns

void

protected

init

inherited from ApolloController

Assigns the controller's variables and GraphQL document.

Parameters

document

ComponentDocument<D, V> | null

Returns

void

protected

notify

inherited from ApolloController

requests an update on the host with the provided properties.

Parameters

properties

Record<string, unknown>

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';