lit-apollo: ApolloQuery

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

returnPartialData

boolean | undefined

Opt into receiving partial results from the cache for queries that are not fully satisfied by the cache.

query

null | ComponentDocument<D, V>

A GraphQL document containing a single query.

pollInterval

number | undefined

The time interval (in milliseconds) on which this query should be refetched from the server.

partialRefetch

boolean | undefined

Set to retry any partial query results.

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.

partial

boolean

True when the query returned partial data.

If data was read from the cache with missing fields, partial will be true. Otherwise, partial will be falsy.

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

notifyOnNetworkStatusChange

boolean | undefined

Whether or not updates to the network status should trigger next on the observer of this query.

noAutoSubscribe

no-auto-subscribe

boolean

When true, the component will not automatically subscribe to new data. Call the subscribe() method to do so.

nextFetchPolicy

next-fetch-policy

this['controller']['options']['nextFetchPolicy'] | undefined

Set to prevent subsequent network requests when the fetch policy is 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.

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.

fetchPolicy

fetch-policy

C.WatchQueryFetchPolicy | undefined

The fetchPolicy for the query.

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 cache
network-only: return result from network, fail if network call doesn't succeed, save to cache
standby: only for queries that aren't actively watched, but should be available for refetch and updateQueries.

errorPolicy

error-policy

C.ErrorPolicy | undefined

Error Policy for the query.

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 call next
all: errors are treated like data and will notify observables