1 of 28

Introducing

sograph

Robert Balicki ◆ Pinterest, ex-Relay

@StatisticsFTW ◆ robert.balicki@gmail.com

@isographlabs

github.com/isographlabs/isograph

#isograph on GraphQL discord

2 of 28

Why am I excited?

Developer experience
Power tools
Precise control over data

Okay, so why am I so pumped? Because I think that 💎 Isograph has the potential to provide the absolute best developer experience for building data-driven apps. I'm not exaggerating here, I honestly believe that.

Isograph has you structure your apps in a fundamentally different way than other frameworks, and in doing so, eliminates a lot of boilerplate involved in writing GraphQL

Now, I could also tell you that 💎 Isograph provides high-level tools for implementing the kinds of interactions that are present in every app, but whose details are hard to get exactly right.

And I could tell you that the Isograph query language will 💎 give you precise control over the data that you show to your users, meaning that certain apps where GraphQL is a poor fit will be great fits for Isograph.

But those are added benefits. The most important thing about Isograph is how it has you structure your app, and the possibilities that that opens up, including for performance.

Now, if someone told you that adopting some new framework would solve all of your problems and unlock vast new opportunities, you might look at them and say - yeah, I've heard that before and politely ask them to leave.

And you'd be justified! This is quite the claim. And extraordinary claims require extraordinary evidence.

After all, the only way that that could be true is if we're building apps in a horribly inefficient and developer hostile way.

So let me be make abundantly clear what my position is:

3 of 28

Building robust and performant data-driven apps is too damn frustrating

4 of 28

5 of 28

How to extract a child component

name child fragment
select fields
select prop name
import type for fragment reference
include type for fragment reference in prop types
read fragment reference

extract into its own file
pick a file name
pick a component name

spread child fragment
remove unused fields
pass fragment reference as prop

import child JavaScript
render child

Okay, well in that case, let's clinically dissect a very common task: splitting a data-driven React component into a parent component and a child component.

Bear with me while I thoroughly document every little thing we have to do.

Okay, so let's start with the React side.

- 💎 We need to extract the child component into its own function and file,

- 💎 we need to pick a name for the file,

- 💎 and pick a name for the exported component,

Look, I told you I was going to be very thorough

- 💎 from the parent component, we need to import the child component using the file name and component name,

- 💎 and we need to render the child component

If we didn't use GraphQL, that's all we would need to do. Honestly, not bad! But, alas, our component is data-driven, so we have some additional work to do. In the child component,

- 💎 we choose a globally unique name for the new fragment,

- 💎 we select the fields that the component will read in that fragment,

- 💎 we choose a prop name for the fragment reference,

- 💎 we import the type for that fragment reference,

- 💎 we include that fragment reference in the PropTypes under that prop name, and

- 💎 we actually read that fragment reference

That's six more items. And in the parent:

- 💎 we spread that child fragment in the parent fragment,

- 💎 we remove the now-unused fields, and

- 💎 we pass that fragment reference using the agreed-upon prop name

Huh... that's ... kind of a lot! Nine additional steps.

I mean, after you've done GraphQL a bunch each step makes sense — but put yourself in the shoes of someone who is new to GraphQL or introducing GraphQL to a new codebase. It's a lot!

Now, obviously, these steps wouldn't be best practices if they weren't, overall, a net positive.

And indeed, they give us something very important:

6 of 28

Data masking

7 of 28

Developer inefficiency

Fragment name
Fragment reference prop name
Reading the fragment reference
Spread child fragment + import JavaScript
Pass fragment reference

Okay, so let's put our consultant hats on and identify some redundancies in these fourteen steps:

- 💎 The globally unique fragment name can be anything and has no effect on the app's behavior. Why do we have to pick one? Why do we give ourselves three opportunities to make a typo?

- 💎 Likewise, the name of the fragment reference prop could be anything and has no effect on the final behavior! That's another unneeded step and three more places we can make a typo.

- 💎 In the child component, there is nothing we can do with the fragment reference _except_ read it. Why is that a separate step? Why isn't it done for us?

- 💎 In the parent component, why do we have to spread the child fragment and import the child component? If we're doing one but not the other, our app is necessarily broken. Can these be combined into a single step?

- 💎 Why do we even have the possibility of passing the fragment reference to any other component? Only this specific component is even capable of reading the fragment.

So, that leads me to ask - why? I mean, the answer is obvious: that's how GraphQL was designed in the early days, before we had discovered all of the best practices, and change is slow.

But there's actually another reason:

8 of 28

Query servers

or

isolate components

9 of 28

Each fragment is associated with exactly one function

10 of 28

How to extract a child component

extract into its own file
pick a name
select fields

select child component
remove unused fields
render child component

11 of 28

In other words, I want you to be able to write a web page like this. There is some query, in which we select the header, body and footer components, and then we just go ahead and render them. Whatever fields these components selected, somehow behind the scenes we look those up and pass them to the subcomponent, without the developer doing any work.

Now, I can see this in your faces. This is obviously an extremely impractical pipe dream and will clearly never work. The header component isn't a field! That query makes no sense

So let's just take that vision for front-end GraphQL, put it in a drawer, close the drawer, lock the drawer, throw away the key and never talk about it again.

Cause it ain't happening. It's too radical.

But... I can't help but think... it is kind of compelling, right? Let's compare.

- We don't need to import any child components

- fragment references don't exist

- We don't need to read any fragment

- the generated types are nowhere to be found. All types are inferred.

A lot of concepts are just... gone.

This is what we get by taking seriously the fact that each fragment is associated with only one function.

In fact, I'm going to go out on a limb and say,

12 of 28

Resolvers are

GraphQL's missing primitive

13 of 28

Everything is

a resolver

14 of 28

This is actual Isograph code.

What we're doing here is defining a new field named 💎 `full_name` on all 💎 user objects.

In order to calculate full name, we know we need the 💎 first and last name fields. 💎 These data are then passed to that anonymous function.

Whoever is reading the full_name field receives the result of that function call.

So, since a resolver defines a field, and itself selects many fields, this also means that a resolver can reference other resolvers!

So, if `first_name` was actually a resolver that returned a string, the `full_name` resolver would work just fine!

We can have many layers of resolvers before we eventually bottom out at server fields.

Okay, so... the value returned by a resolver is completely arbitrary. Well, what if that returned value was a React component? Can we make that work?

15 of 28

🚫

The answer is yes, but React's reconciliation algorithm complicates the picture. If a resolver returned a higher order component that was bound to the data it read from the local cache, every time the data in the cache changed, we would be rendering a different function instance.

From React's perspective, this is a completely new component, so what was previously rendered there would be unmounted, and we would lose all state and hooks. That's a bit of a deal breaker. 💎

However, all is not lost. The function we read out using the fragment has an unstable identity, but the component that it returns does not! 💎 So, let's instead, call the component as if it was a regular function and interpolate the result.

Now, instead of seeing a component with an unstable identity, React sees 💎 this element, which does have a stable identity.

Now, importantly for the developer, `MyGreeting` is indistinguishable from a "standard" functional React component. In particular, `MyGreeting` can support hooks, and is actually rendered as its own component.

Now, making this all work does require some boilerplate, but Isograph has a compiler, and it can write it for us. 💎 All the developer has to do is annotate the resolver with `@component`:

This component is accessible as a field on `user`, and automatically receives the fields selected in the fragment, with no additional plumbing work on the developer's part.

That! That's the amazing developer experience that I want Isograph to give you.

Now, this comes with a pretty big caveat, which is that TypeScript has no idea what the type of the `iso` literal is, so we have to annotate the iso literal with type parameters 💎. Which I will admit is a bummer! But with custom AST transformers or with a wrapper around typescript, this is certainly fixable.

Okay, so, we've covered how resolvers can reference other resolvers and ultimately bottom out at server fields, but what about the very outermost resolver? How do we connect our regular ol' React application to Isograph, and fetch the data for the first resolver?

16 of 28

In order to do that, we define a fetchable resolver. For each fetchable resolver, the Isograph compiler will generate a GraphQL query. This query will contain all of the server fields that are reachable from the resolver, including recursively, but of course, will not contain any resolvers, which the server does not know about.

So to do this, 💎 the resolver is annotated with `@fetchable`.

💎 Next, the way we fetch the data is using `useLazyReference` and the way we read the data is calling 💎 `read`, which, if you're familiar with Relay is essentially `useLazyLoadQuery`.

So, when this component component is rendered, we trigger a network request and - if the data is missing, as it will be if this was the initial page load - we suspend when attempting to read the data. When that data is present, we'll re-render and show the content.

Honestly, this slide is not particularly groundbreaking. Isograph will one day support all the good patterns like entrypoints, but this is good enough for now.

Okay, so let's review. You connect your React app to Isograph at the root, and from then on, it's all resolvers all the way down, until you reach server fields. All of those server fields get turned into a big ol' GraphQL query that gets sent to the server.

Resolvers annotated with `@component` become components, except instead of using the JSX component syntax, you call them as functions and interpolate them.

I think that's a nice developer experience!

17 of 28

Data masking

18 of 28

@defer data and

code together

19 of 28

Is this data

onscreen? 🤔

20 of 28

Choose when to

load resolvers

21 of 28

Server execution

22 of 28

Conditionally load resolvers

But we can get even more clever. If we select a nullable field, such as a best friend, and a resolver on the best friend, we can do one of two things:

- optimistically download the JavaScript for the best friend resolver, assuming we might need it, or

- only download the JavaScript if we need it, for example if we encounter a user that actually has a best friend. (And a sufficiently smart server can stream that resolver down for us, if it sees a non-null best friend.)

And if we're selecting an interface field, and want to render different resolvers based on the concrete type of that interface, resolvers make sense for this as well. Did somebody say 3D?

So, a theme here is that resolvers give us flexibility about when we will download the JavaScript, and when we will execute the JavaScript.

But a further point is that nothing is ever new. I didn't invent resolvers, and owe a tremendous debt to every other smart person who tackled this problem before me. And I owe a huge debt to the ideas that are in Relay, and in particular, to Jordan Eldredge, who is in the audience and who spearheaded the work on resolvers in Relay, along with Andrey Lunyov.

And it's not guaranteed that Isograph will be the best way to tackle this problem, either!

23 of 28

DevTools

24 of 28

Robert's

Pet List 3000™

25 of 28

FEATURE

COMPLETE

🎉

26 of 28

27 of 28

Roadmap (in no particular order)

Docs
VSCode extension
Compiler watch mode
Fetch policies
Garbage collection
Preloaded queries
Fetch/cache policies
Granular re-renders
Traditional refetch fields
Defer/stream

Subscriptions
Interfaces/unions
Entrypoints
Field unwrapping syntax
Pagination
Refetch on missing data
Compile to non-GraphQL
Actually validate variables
Error reporting (compiler)
Persisted queries
Suspense for mutations
Suspense for refetch
Strongly typed ID fields
Custom normalizers
Lazy normalization ASTs
Fetching off of typed IDs
Magic mutation/refetch field customizability
Stateful resolvers

Compiler executable for Mac/�Windows/Linux
Unit tests
E2E tests
Network request errors
Proper missing field handlers
Missing field handlers from�schema definitions
Store held in context
Imperative store APIs
Typesafe updaters
Sample router integration
Emit new field definitions�for GraphiQL and other tools
Field groups
Lint rules to enforce e.g. export
Guide for testing Isograph�components
Support non-globally unique IDs
Iso lang code mods
Iso lang syntax highlighting
Iso lang auto-format
Separate artifacts for fetching�and reading fetchable resolvers
Incremental compilation
Saved state
Support strict mode?
Load resolvers iff needed
Object literals as variables

Server support for�JSResource
Injectable code for�@component
Isograph dev tools
Experiment with�context and JSX�for @component
Vue/Svelte/etc.�integration
Compile compiler�to Wasm
IR explorer
Code sandbox example
Non-fetchable�fragments
Topological sort in�compiler
Validate no infinite�recursion
Statically prune�inaccessible branches
Bug fix: Not all files in�one folder
TypeScript errors in�emitted artifacts
Better repr. of nullable�types in compiler
Babel integration for�iso literal values
Typescript integration�for type inference of iso�literals
Parallelize artifact gen�etc.

28 of 28