(why the hell did I) build a GraphQL client for the browser

Exploring why and how I ended up building @swan-io/graphql-client. From its exposed API to its cache engine, with a few extras.

Transcript

1. build a GraphQL client for the browser why the hell did I
2. build a GraphQL client for the browser why the hell did I
3. lead engineering manager chief shitpost of fi cer @ swan Matthias Le Brun @bloodyowl
4. our product is a GraphQL API* * and some frontend interfaces I promise my job is real
5. → dashboard → auth → banking* → onboarding* * open-source our apps
6. consume GraphQL APIs our apps
7. need a GraphQL client our apps
8. but existing clients … → designed for a single schema → caching requires introspection → caching issues anyway → impact on bundle size → hard to extend/contribute
9. «how hard can it be to build a GQL client from scratch?» — me, clueless about how hard it can be to build a GQL client from scratch
10. «how hard can it be to build a GQL client from scratch?» — me, clueless about how hard it can be to build a GQL client from scratch
11. 1. the API 2. the engine 3. the extras
12. current state of the ecosystem API const UserProfile = () => { const { loading, data, error } = useQuery(query, {}); // ... };
13. error handling in GraphQL ambiguities { "status": null } + Create your fi rst status Error loading status
14. error handling in GraphQL ambiguities if you want to guarantee that the UI is consistent with the data, query success is all or nothing
15. API structure if (error) { return <ErrorView /> ; } return <Data data={data} /> ;
16. API @swan-io/boxed type Option<T> = Some<T> | None<T>; type Result<T, E> = Ok<T> | Error<E>; type AsyncData<T> = | NotAsked<T> | Loading<T> | Done<T>; open-source!
17. usage API const MyComponent = () => { const [data] = useQuery(query, {}); return match(data) .with(AsyncData.P.NotAsked, AsyncData.P.Loading, () => <LoadingView /> ) .with(AsyncData.P.Done(Result.P.Error(P.select())), (error) => ( <ErrorView error={error} /> )) .with(AsyncData.P.Done(Result.P.Ok(P.select())), (data) => { // show your data }) .exhaustive(); };
18. usage API const UserPage = ({ userId }: Props) => { const [updateUsername, usernameUpdate] = useMutation(updateUsernameMutation); const [username, setUsername] = useState(""); const onSubmit = (event) => { event.preventDefault(); updateUsername({ userId, username }); }; const isLoading = usernameUpdate.isLoading(); // ... };
19. advantages API → no possible mixing of state → exhaustivity checks → no impossible states
20. 1. the API 2. the engine 3. the extras
21. engine what is a GraphQL client? fetch relay
22. engine 1. no cache 2. operation cache 3. normalized cache levels of caching
23. engine → levels of caching → no cache API render query result
24. engine → levels of caching → operation cache API render query result cache if query<variables> not in cache
25. engine → levels of caching → operation cache API render query result cache → returns cache if available → calls API systemically to refresh stale while revalidate
26. engine → levels of caching → operation cache API render mutation result mutation invalidation
27. engine → levels of caching → operation cache API render mutation result mutation invalidation API render query result cache prime manual refresh
28. engine → levels of caching → normalized cache result User<1> Post<4> Comment<10>
29. engine → levels of caching → normalized cache result User<1> Post<4> Comment<10> mutation prime
30. engine → levels of caching → normalized cache mutation invalidation API render mutation result cache prime
31. engine how can we normalize cache with minimal information? normalized cache
32. engine normalized cache how can we normalize cache with minimal information? types
33. engine normalized cache add the __typename everywhere in queries
34. query typename export const addTypenames = (documentNode: DocumentNode): DocumentNode => { return visit(documentNode, { [Kind.SELECTION_SET]: (selectionSet): SelectionSetNode => { if ( selectionSet.selections.find( (selection) => selection.kind === Kind.FIELD && selection.name.value === "__typename", ) ) { return selectionSet; } else { return { ... selectionSet, selections: [TYPENAME_NODE, ... selectionSet.selections], }; } }, }); };
35. engine what's a cache entry? → root types (Query, Mutation) → IDed objects
36. engine caveat the client expects you query IDs systematically eslint plugin or codegen transforms can do that for you
37. engine what's a cache entry? anything else needs to be cached in its closest cached ancestor entry
38. engine cache structure Map { Symbol(Query) => { Symbol(user({"id":1})) => Symbol(User<1>), } Symbol(User<1>) => { Symbol(id) => 1, Symbol(username) => "bloodyowl" } }
39. engine cache structure Map { Symbol(Query) > Symbol(user({"id":1})) > } Symbol(User<1>) > Symbol(id) > Symbol(username) > } } Symbol(Query) Symbol(User<1>) → entries
40. engine cache structure Map { Symbol(Query) > Symbol(user({"id":1})) > } Symbol(User<1>) > Symbol(id) > Symbol(username) > } } Symbol(user({"id":1})) Symbol(id) Symbol(username) → fi elds with their arguments
41. engine cache structure Map { Symbol(Query) > Symbol(user({"id":1})) > } Symbol(User<1>) > Symbol(id) > Symbol(username) > } } Symbol(User<1>), → pointers to cache entries
42. engine cache: respond to query the engine runs the query against the cache
43. engine cache: respond to query how do you know if the cache has enough data to return a result while the API is loading?
44. engine cache structure Symbol(User<1>) > Symbol(__requestedKeys) > Symbol(id) > Symbol(username) > } Symbol(__requestedKeys) => Set { Symbol(id), Symbol(username) } → track fi elds that have been requested cache can respond if all requested fi elds are cached
45. engine ambiguities interfaces aka how object-oriented programming still manages to make things awful
46. engine → ambiguities → interfaces ... on Transaction { __typename id amount { value currency } }
47. engine → ambiguities → interfaces . __typename id amount { value currency } } { "__typename": "CardTransaction", "id": "efea560c-1a26-4d31-9555-ac5714 "amount": { "value": "10", "currency": "EUR" } } Transaction "CardTransaction" → can't assume fragment name as cache key we need to provide the cache the interface → object map
48. 1. the API 2. the engine 3. the extras
49. extras relay pagination in fi nite scroll is contextual to the consumer
50. extras relay pagination const [data, { isLoading, setVariables }] = useQuery( AllFilmsQuery, { first: 3 }, ); if a variable changes, data goes back to loading
51. extras relay pagination const [data, { isLoading, setVariables }] = useQuery( AllFilmsQuery, { first: 3 }, ); if a variable changes, data remains Done, isLoading gets true
52. extras relay pagination const connection = useForwardPagination(connection); → keeps track of the queries it saw → aggregates the connection
53. engine cache structure Map { Symbol(Query) => { Symbol(user({"after":null})) => { ... }, Symbol(user({"after":"1az2zae ... "})) => { ... }, } }
54. extras connection updates useMutation(BlockUser, { connectionUpdates: [ ({ data, append }) => Option.fromNullable(data.blockUser).map(({ user }) => append(blockedUsers, [user]), ), ({ data, prepend }) => Option.fromNullable(data.blockUser).map(({ user }) => prepend(lastBlockedUsers, [user]), ), ], });
55. extras optional optimization const [data] = useQuery( MyQuery, {}, { optimize: true }, ); → creates an optimized query, only requests missing fi elds → doesn't query if everything in cache
56. → @swan-io/graphql-client → 12kb gzipped → used in production for 6 months wrapping up
57. conclusion
58. conclusion I didn't revolutionize anything there
59. conclusion but I learnt things by trying
60. conclusion but I learnt things by trying
61. conclusion I didn't revolutionize anything there
62. conclusion but I can make it evolve
63. conclusion I didn't revolutionize anything there
64. conclusion but it works
65. conclusion there's no such thing as an absolute best practice
66. conclusion
67. conclusion
68. conclusion
69. conclusion build things
70. thank you! Matthias Le Brun @bloodyowl