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, {
    onSubscriptionData: ({ 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

options

ApolloSubscriptionControllerOptions<D, V>

public

canAutoSubscribe

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.

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	TypedDocumentNode`{lang=ts}
variables	`Variables<D, V>`	An object containing all of the variables your subscription needs to execute.

void

hostDisconnected

Returns

void

hostConnected

Returns

void

public

cancel

Ends the subscription

Returns

void

Private API

Private Properties

private

observableSubscription

ZenObservable.Subscription

private

observable

Observable<FetchResult<Data<D>>>

private

#lastSubscriptionDocument

DocumentNode

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>

protected

emitter

inherited from ApolloController

EventTarget

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

Private Methods

protected

variablesChanged

Parameters

variables

Variables<D, V>

Returns

void

private

shouldSubscribe

Parameters

opts

Partial<SubscriptionOptions<Variables<D, V>, Data<D>>>

Property	Type	Description
query	`DocumentNode	TypedDocumentNode`{lang=ts}
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	TypedDocumentNode`{lang=ts}
variables	`Variables<D, V>`	An object containing all of the variables your subscription needs to execute.

Returns

void

private

endSubscription

protected

documentChanged

Parameters

doc

ComponentDocument<D> | null

Returns

void

protected

clientChanged

Returns

void

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	TypedDocumentNode`{lang=ts}
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

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

Exports

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