The Isograph compiler
This page is intended to serve as a guide to learning about the Isograph compiler. However, it is likely to be out-of-date and inaccurate, so please consult the source code and use your best judgment.
Big picture
After installing the compiler with yarn install --dev @isograph/compiler
, yarn run iso
will run the compiler. It has two modes: batch mode and watch mode.
Batch mode
Calling yarn iso --config ./isograph.config.json
runs the Isograph compiler in batch mode. This means it will do a complete run-through (i.e. completely compile the project). Once it completes (or encounters errors), the process will end.
At a very high level, the Isograph compiler does the following:
- It will parse the Isograph config file.
- It will parse and validate the GraphQL schema.
- It will parse and validate
iso
invocations. - It will generate artifacts.
If during any of these steps, one or more validation errors are generated, the compiler will print those errors and not continue compiling.
You can find this in the handle_compile_command
.
watch
mode
If you run yarn iso --config ./isograph.config/json --watch
, the compiler will run in watch mode.
In this mode, the compiler creates a watcher for the various files/folders (e.g. schema, schema extensions, folder containing the components), and repeatedly runs the compiler in batch mode.
No state is preserved across runs, e.g. if you modify a component, we still re-parse and re-validate the schema. Re-using state from previous batch compilation runs remains to be implemented.
Since watch mode is a simple wrapper around batch mode, the rest of this document will only discuss batch mode.
Crates
The Isograph compiler contains the following crates. The most important ones are marked with a 🟢:
common_lang_types
graphql_lang_types
: GraphQL types that are also used by Isograph. (This is a smell. These types should only be used bygraphql_schema_parser
.)- 🟢
graphql_schema_parser
: An LL(1) parser for GraphQL schema documents and GraphQL schema extension documents, not for fragments or operations. - 🟢
isograph_cli
: The package which exposes the CLI for the Isograph compiler. It also includes the artifact generation code. - 🟢
isograph_lang_parser
: An LL(1) parser for Isograph literals isograph_lang_types
: Some common types.- 🟢
isograph_schema
: The in-memory representation of the Isograph schema. This includes server fields and fields generated fromiso
invocations. It should probably not include representations ofiso
entrypoints, but currently does. string_key_newtype
: A library for generating typesafe newtype wrappers aroundStringKey
types.u32_newtypes
: A library for generating typesafe newtype wrappers aroundu32
types.
The Isograph schema
Representation
The Isograph schema (struct Schema
) is represented by an object that contains:
- a vector of available server fields
- a vector of available resolvers
- a vector of available objects
- a vector of available scalar types
- a map going from names to object or scalar types. This ensures that every type name is unique.
Each object contains:
- a vector of available server field ids
- a vector of available resolver field ids
- an optional id field
- a map of field names to a generic type (in the fully validated schema, this is a map from field names to an enum containing a scalar ID or an object ID.)