Skip to main content

Client

Beta

The following feature isn't yet stable.

The typegraph client provides a code-first alternative for querying typegraphs. It contains types generated from typegraph definitions to ensure type safety. The metagen suite provides the client code-generators under the following names:

  • client_ts: client code-generator for Typescript for use in browsers and other Javascript runtimes
  • client_py: client code-generator for Python
  • client_rs: client code-generator for Rust.

Refer to the metagen documentation on how to access the generators.

Guide​

Even though there are minor differences across language implementations, the generated clients adhere to a common design that contains the following elements.

QueryGraph​

The root type generated for the client, it includes:

  • Query builders for all the root functions
  • Transport constructors for all the transports exposed by the typegraph
Loading...

Transports​

Different transport implementations are used to send the requests to the typegate for different use cases. The QueryGraph will sport methods to construct transports supported by the typegraph (see examples below). Not all transports have the same feature sets.

GraphQLTransport​

This transport converts to equivalent GraphQL query strings that get sent over http. It includes the following features for all implementations:

  • Sync or async queries and mutations
  • Multiple queries or mutations in one request

HostcallTransport​

This transport uses host functions exposed by the typegate for use with custom functions.

  • Sync queries and mutations
  • Multiple queries or mutations in one request

Requests​

Requests consist of two parts:

  • Describe the operations using methods on QueryGraph.
    • Methods are typesafe according to each typegraph root functions.
  • Transport methods that take the query description and perform request to the typegate.
    • Mutations and queries use separate methods and types.
    • Some transports like the GraphQLTransport support multiple operations in one request
Loading...

Nested arguments​

Some fields are themselves composite types that have fields that also require selection. And functions are used to resolve certain fields which require arguments.

Loading...

Selecting fields​

Booleans indicate interest when selecting fields on an object. By default a field isn't included if it's null, or unspecified. Selections can include selection flags to flip the default so that all unspecified fields get included. This won't apply if the field requires an argument explicitly requiring them for inclusion.

Note that these patterns are different in the client_rs implementations as demonstrated below:

Loading...

Note that this only applies to scalar fields and those that require arguments or are structs must still be explicitly included.

Preparing requests​

Some transports like the GraphQLTransport allows one to prepare requests before hand and reuse them. This isn't immediately useful but will be critical when persisted queries are available in Metatype.

Loading...
Caution

Note that in all three implementations, the closures are only invoked once and it's critical that there are no branching logic present in them.

Aliases​

Aliasing allows the querying of a node multiple times under different names. This is very similar to the GraphQL aliases and uses them under the hood when using the GraphQLTransport. Note that not all Runtimes support aliasing so make sure your target does before using this feature.

Loading...

Unions​

Union and either types that have composite variants require special forms when querying them. The generated selection types will have fields for selecting composite variants. If the value from the API wasn't of a selected variant, an empty object will be returned. Scalar variants are always selected.

Loading...