One of the most important parts about mocking a GraphQL API is being able to quickly and effectively target specific parts of the GraphQL Schema. Highlight is a declarative, extensible, system for describing Named Types, and their fields, of the GraphQL Schema. With this type of control it becomes quick to mock specific types and fields and use Highlights in Resolver Map Middlewares and other utilities.
Here is an brief example of using Highlight:
In this example,
field is a Highlighter and it targets fields on the schema. The Highlighter being used with the Highlight system will capture all the fields (denoted by the
*) on the
Query type of the schema. Highlighters are what are used to declaratively identify the different parts of a GraphQL schema. There are more highlighters to check out, also learn how to create your own.
hi or the
Highlight constructor can be imported from
@graphql-mocks/highlight and both will produce a
Highlight instance. An instance has three available methods:
include- Add additional highlights/references to be included
exclude- Remove specified highlights/references from being included
filter- Filter the existing selection to include the specified highlights/references
Note: All three of these take the same arguments, as many Higlighters or
References to include/exclude/filter, and return a new
Highlight instance. That is each instance is immutable and any modification through its public APIs produces a new instance.
Highlight all Query and Mutation fields while excluding the Query.users field
The underlying primitive for Highlight and many of the utilities in graphql-mocks are References. References can define:
- GraphQL types by a single string as a Type Reference,
- GraphQL fields by a tuple Field Reference
["Query", "allUsers"]of the type name and field name.
Any functions using the
Reference type accept either a Type Reference or a Field Reference.
Pulling Highlighted References from a
Highlight instance stores the References that have been highlighted. These can be pulled and used for many of the underlying utilities that use
References for arguments.
Would log a list of highlighted references, for example:
highlight Middleware Option
Much of the highlighting will happen in Resolver Map Middlewares or as arguments for Resolver Map Middlewares, like with
embed. It is useful to support a
highlight argument that conforms to the
CoercibleHighlight interface and provides a flexible argument for users of the Middleware. More on this design pattern is covered in Creating Middlewares, but it's usually easiest to supply a callback where the highlight instance is already provided:
CoercibleHighlight type includes raw References.