Apollo Progressive Fragment Matcher

A smart alternative to the introspection fragment matcher.

---

Motivation

Error: You are using the simple (heuristic) fragment matcher... 😱

GraphQL APIs are evolving, and usage of Unions and Interfaces are much more common now then they use to be. Some time ago this kind of feature was considered advanced; I don't think that's true today. The GraphQL clients all need a way to distinguish data between two or more fragments that rely on inherited types (unions & interfaces), what I call the Human and Droid problem.

Apollo has long solved this issue by providing the IntrospectionFragmentMatcher. This fragment matcher, though, requires, that you provide a introspectionQueryResultData, which is your API's introspection query result. Introspection queries result can be huge.

What if we could avoid pre-fetching the introspection? What if we could introspect as we go?

Welcome ProgressiveFragmentMatcher.

Usage

Installation

npm i apollo-progressive-fragment-matcher apollo-link graphql invariant

ProgressiveFragmentMatcher

The Progressive Fragment Matcher has two strategies for matching fragment types:

Progressive introspection (default)

This strategy transforms the outgoing queries to request introspection information on the requesting types. It does cache the results, meaning if on a second query you use the same fragment type, it won't introspect again (nor transform the query, which can be expensive).

This strategy is much like what ApolloClient normally does to inject __typename fields.

Good:

• Easy to install;
• Drop-in replacement for IntrospectionFragmentMatcher;

Bad:

• Query transforms are expensive;

Usage

import ApolloClient from 'apollo-client'
import { InMemoryCache } from 'apollo-cache-inmemory'
import { from } from 'apollo-link'
import { HttpLink } from 'apollo-link-http'
import { ProgressiveFragmentMatcher } from 'apollo-progressive-fragment-matcher'

const fragmentMatcher = new ProgressiveFragmentMatcher()

const client = new ApolloClient({
  cache: new InMemoryCache({ fragmentMatcher }),
  link: from([fragmentMatcher.link(), new HttpLink()]),
})

Extension based

This strategy is very performatic on the client side, because it does not depend on query transformation. What this strategy does is send the server an extension flag ({ possibleTypes: true }) to request the server to send possible types of any returned type in the query - regardless of the fragments requested.

This strategy requires you have control of the server, and currently only works with ApolloServer custom extensions implementation.

Good:

• Fast on client;
• Persisted queries supported;

Bad:

• Requires server control;

Usage

client:

import ApolloClient from 'apollo-client'
import { InMemoryCache } from 'apollo-cache-inmemory'
import { from } from 'apollo-link'
import { HttpLink } from 'apollo-link-http'
import { ProgressiveFragmentMatcher } from 'apollo-progressive-fragment-matcher'

const fragmentMatcher = new ProgressiveFragmentMatcher({
  strategy: 'extension',
})

const client = new ApolloClient({
  cache: new InMemoryCache({ fragmentMatcher }),
  link: from([fragmentMatcher.link(), new HttpLink()]),
})

server

import { ApolloServer } from 'apollo-server'
import { PossibleTypesExtension } from 'apollo-progressive-fragment-matcher'

const server = new ApolloServer({
  typeDefs,
  resolvers,
  extensions: [() => new PossibleTypesExtension()],
})

server.listen() // start server

Due to a limitation on ApolloClient's customizing capabilities, both strategies require you append a link created from the fragment matcher instance.

Warning ⚠️

Although well tested, this project is in an experimental stage.

About persisted queries

I have not yet stressed it out on complicating circustances such as persistend queries. I've marked the extension strategy as supporting persisted queries due to the nature of this operation - it relies on no query transformation, therefore should be compatible with persisted queries, but no test prove this concept yet.