ApolloSubscription

Subscription components update in real time in reaction to events on your GraphQL server. They are ideal for uses like chat rooms or stock tickers.

Subscription components inherit the ApolloElementInterface.

Common interface for subscription elements

See ApolloElementInterface for more information on events

Properties

documentType

static(read-only)
'document'|'query'|'mutation'|'subscription'

controller

public
ApolloController<D, V>

data

public
Data<D> | null
Latest Data.Latest subscription data.

variables

public
Variables<D, V> | null
Subscription variables.

An object map from variable name to variable value, where the variables are used within the GraphQL subscription.

Setting variables will initiate the subscription, unless noAutoSubscribe is also set.

subscription

public
ComponentDocument<D, V> | null
A GraphQL document containing a single subscription.

canAutoSubscribe

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

fetchPolicy

public
string | undefined
Specifies the FetchPolicy to be used for this subscription.

pollInterval

public
number | undefined
The time interval (in milliseconds) on which this subscription should be refetched from the server.

noAutoSubscribe

public
boolean
If true, the element will not begin querying data until you manually call subscribe

shouldResubscribe

public
boolean | ((options: SubscriptionDataOptions<Data<D>, Variables<D, V>>) => boolean)
Determines if your subscription should be unsubscribed and subscribed again.

skip

public
boolean
If true, the query will be skipped entirely

client

public
ApolloClient | null
The Apollo Client instance.

document

public
ComponentDocument<D, V> | null
Operation document.GraphQL operation document i.e. query, subscription, or mutation. Must be a parsed GraphQL DocumentNode, so use graphql-tag.

error

public
Error | null
Latest error

errors

public
readonly GraphQLError[]
Latest errors

loading

public
boolean
Whether a request is in flight.

context

public
Record<string, unknown> | undefined
Context passed to the link execution chain.

errorPolicy

public
ErrorPolicy | undefined
Error Policy for the operation.

Much like fetchPolicy, errorPolicy allows you to control how GraphQL errors from the server are sent to your UI code. By default, the error policy treats any GraphQL Errors as network errors and ends the request chain. It doesn’t save any data in the cache, and renders your UI with the error property set to an ApolloError. By changing this policy per request, you can adjust how GraphQL Errors are managed by your UI. The possible options for errorPolicy are:

  • none (default): any errors from the request are treated like runtime errors and the observable is stopped (XXX this is default to lower breaking changes going from AC 1.0 => 2.0)
  • ignore: errors from the request do not stop the observable, but also don’t call next
  • all: errors are treated like data and will notify observables

readyToReceiveDocument

public
boolean
True when the element is connected and ready to receive its GraphQL document

Methods

onSubscriptionData

publicCallback for when data is updated

Parameters

_result

OnSubscriptionDataParams<Data<D>>

Returns

void

onSubscriptionComplete

publicCallback for when subscription completes.

Returns

void

onError

publicCallback for when error is updated

Parameters

error

Error

Returns

void

subscribe

publicResets the subscription and subscribes.

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

publicCancels and clears the subscription

Returns

void

shouldSubscribe

publicDetermines whether the element should attempt to subscribe automatically Override to prevent subscribing unless your conditions are met

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

Events

apollo-subscription-result

ApolloSubscriptionResultEvent
The subscription updated

apollo-error

CustomEvent<ApolloError>
The subscription produced an error

apollo-element-connected

ApolloElementEvent
The element connected to the DOM

apollo-element-disconnected

ApolloElementEvent
The element disconnected from the DOM

Private Methods

documentChanged

protectedLifecycle callback that reacts to changes in the GraphQL document

Parameters

document

ComponentDocument<D, V> | null

Returns

void

variablesChanged

protectedLifecycle callback that reacts to changes in the operation variables

Parameters

variables

Variables<D, V> | null

Returns

void

Exports

js CustomElement from types.js

js ControllerHost from types.js

js ApolloElementElement from types.js

js ApolloMutationElement from types.js

js ApolloQueryElement from types.js

js ApolloSubscriptionElement from types.js

js GraphQLError from types.js