Looking for reactive Apollo query controllers? See @apollo-elements/core/apollo-query-controller
.
ApolloQuery
inherits from ApolloElement
and implements the ApolloQueryInterface
.
Demo
import { ApolloQuery, html } from '@apollo-elements/lit-apollo';
import { customElement } from 'lit/decorators.js';
import { LaunchesQuery } from './Launches.query.graphql.js';
import { style } from './SpacexLaunches.css.js';
import '@apollo-elements/components/apollo-client';
@customElement('spacex-launches')
class SpacexLaunches extends ApolloQuery<typeof LaunchesQuery> {
static readonly styles = style;
variables = { limit: 3 };
query = LaunchesQuery;
render() {
const launches = this.data?.launchesPast ?? [];
return html`
<ol>${launches.map(x => html`
<li>
<article>
<span>${x.mission_name ?? ''}</span>
<img .src="${x.links?.mission_patch_small}" alt="Badge" role="presentation"/>
</article>
</li>`)}
</ol>
`;
}
}
Read the query component guides for more examples and tips.
ApolloQuery
🚀 Custom element base class that connects to your Apollo cache.
See ApolloQueryInterface
for more information on events
Properties
data
Data<D> | null
variables
Variables<D, V> | null
controller
ApolloController<D, V>
canAutoSubscribe
boolean
options
ApolloQueryControllerOptions<D, V>
Option | Type | Description |
---|---|---|
fetchPolicy | WatchQueryFetchPolicy |
The fetchPolicy for the query. |
variables | Variables<D, V> |
Variables for the query. |
noAutoSubscribe | boolean |
If true, the element will not begin querying data until you manually call subscribe |
shouldSubscribe | (op?: Partial<Operation<D, V>>) => boolean |
Determines whether the element should attempt to subscribe automatically\nOverride to prevent subscribing unless your conditions are met |
onData | (data: Data<D>) => void |
Optional callback for when a query resolves. |
onError | (error: Error) => void |
Optional callback for when an error occurs. |
Inherits from ApolloControllerOptions
networkStatus
networkStatus
is useful if you want to display a different loading indicator (or no indicator at all)
depending on your network status as it provides a more detailed view into the state of a network request
on your component than loading
does. networkStatus
is an enum with different number values between 1 and 8.
These number values each represent a different network state.
loading
: The query has never been run before and the request is now pending. A query will still have this network status even if a result was returned from the cache, but a query was dispatched anyway.setVariables
: If a query’s variables change and a network request was fired then the network status will be setVariables until the result of that query comes back. React users will see this when options.variables changes on their queries.fetchMore
: Indicates that fetchMore was called on this query and that the network request created is currently in flight.refetch
: It means that refetch was called on a query and the refetch request is currently in flight.- Unused.
poll
: Indicates that a polling query is currently in flight. So for example if you are polling a query every 10 seconds then the network status will switch to poll every 10 seconds whenever a poll request has been sent but not resolved.ready
: No request is in flight for this query, and no errors happened. Everything is OK.error
: No request is in flight for this query, but one or more errors were detected.
If the network status is less then 7 then it is equivalent to loading
being true. In fact you could
replace all of your loading
checks with networkStatus < 7
and you would not see a difference.
It is recommended that you use loading
, however.
query
null | ComponentDocument<D, V>
partial
boolean
partialRefetch
boolean | undefined
If true, perform a query refetch if the query result is marked as being partial, and the returned data is reset to an empty Object by the Apollo Client QueryManager (due to a cache miss).
The default value is false for backwards-compatibility’s sake, but should be changed to true for most use-cases.
pollInterval
number | undefined
returnPartialData
boolean | undefined
noAutoSubscribe
boolean
subscribe()
method to do so.notifyOnNetworkStatusChange
boolean | undefined
errorPolicy
C.ErrorPolicy | undefined
errorPolicy determines the level of events for errors in the execution result. The options 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 callnext
all
: errors are treated like data and will notify observables
fetchPolicy
C.WatchQueryFetchPolicy | undefined
Determines where the client may return a result from. The options are:
cache-first
(default): return result from cache, fetch from network if cached result is not available.cache-and-network
: return result from cache first (if it exists), then return network result once it’s available.cache-only
: return result from cache if available, fail otherwise.no-cache
: return result from network, fail if network call doesn’t succeed, don’t save to cachenetwork-only
: return result from network, fail if network call doesn’t succeed, save to cachestandby
: only for queries that aren’t actively watched, but should be available for refetch and updateQueries.
nextFetchPolicy
this['controller']['options']['nextFetchPolicy'] | undefined
cache-and-network
or network-only
.When someone chooses cache-and-network or network-only as their
initial FetchPolicy, they often do not want future cache updates to
trigger unconditional network requests, which is what repeatedly
applying the cache-and-network or network-only policies would seem
to imply. Instead, when the cache reports an update after the
initial network request, it may be desirable for subsequent network
requests to be triggered only if the cache result is incomplete.
The nextFetchPolicy option provides a way to update
options.fetchPolicy after the intial network request, without
having to set options.readyToReceiveDocument
boolean
client
ApolloClient<NormalizedCacheObject> | null
document
ComponentDocument<D, V> | null
DocumentNode
context
Record<string, unknown> | undefined
loading
boolean
error
Error | ApolloError | null
errors
readonly GraphQLError[]
Methods
shouldSubscribe
Determines whether the element should attempt to subscribe i.e. begin querying Override to prevent subscribing unless your conditions are metParameters
options
Partial<C.SubscriptionOptions<Variables<D, V>, Data<D>>>
Returns
boolean
refetch
publicasyncExposes theObservableQuery#refetch
method.Parameters
variables
Variables<D, V>
Returns
Promise<C.ApolloQueryResult<Data<D>>>
subscribe
publicResets the observableQuery and subscribes.Parameters
params
Partial<C.WatchQueryOptions<Variables<D, V>, Data<D>>>
Returns
C.ObservableSubscription
subscribeToMore
publicLets you pass a GraphQL subscription and updateQuery function to subscribe to more updates for your query.
The updateQuery
parameter is a function that takes the previous query data,
then a { subscriptionData: TSubscriptionResult }
object,
and returns an object with updated query data based on the new results.
Parameters
options
C.SubscribeToMoreOptions<Data<D>, TSubscriptionVariables, TSubscriptionData>
Returns
(() => void) | void
executeQuery
publicasyncExecutes a Query once and updates the with the resultParameters
params
Partial<C.QueryOptions<Variables<D, V>, Data<D>>>
Returns
Promise<C.ApolloQueryResult<Data<D>>>
fetchMore
publicasyncExposes the ObservableQuery#fetchMore
method.
https://www.apollographql.com/docs/react/api/core/ObservableQuery/#ObservableQuery.fetchMore
The optional updateQuery
parameter is a function that takes the previous query data,
then a { subscriptionData: TSubscriptionResult }
object,
and returns an object with updated query data based on the new results.
The optional variables
parameter is an optional new variables object.
Parameters
params
Partial<FetchMoreParams<D, V>>
Option | Type | Description |
---|---|---|
query | DocumentNode |
Query to fetch, defaults to this.query |
updateQuery | Function |
Function to determine how to update the cache when the query resolves. (deprecated - use field policies instead) |
variables | Variables<D, V> |
Query variables |
context | Record<string, unknown> |
Context object passed through the link execution chain. |
Returns
Promise<C.ApolloQueryResult<Data<D>>>
startPolling
publicParameters
ms
number
Returns
void
stopPolling
publicReturns
void
onData
Optional callback for when a query is completed.Parameters
data
Data<D>
Returns
void
onError
Optional callback for when an error occurs.Parameters
error
Error
Returns
void
Events
apollo-element-connected
ApolloElementEvent
apollo-element-disconnected
ApolloElementEvent
Exports
js ApolloQuery
from apollo-query.js