Macro juniper::graphql_interface

macro_rules! graphql_interface {
    ( @as_item, $i:item) => { ... };
    ( @as_expr, $e:expr) => { ... };
    (
        @gather_meta,
        $reg:expr, $acc:expr, $descr:expr,
        field $name:ident $args:tt -> $t:ty as $desc:tt $body:block $( $rest:tt )*
    ) => { ... };
    (
        @gather_meta,
        $reg:expr, $acc:expr, $descr:expr,
        field $name:ident $args:tt -> $t:ty $body:block $( $rest:tt )*
    ) => { ... };
    (
        @gather_meta,
        $reg:expr, $acc:expr, $descr:expr,
        description : $value:tt $( $rest:tt )*
    ) => { ... };
    (
        @gather_meta,
        $reg:expr, $acc:expr, $descr:expr,
        instance_resolvers: | $execvar:pat | $resolvers:tt $( $rest:tt )*
    ) => { ... };
    ( @gather_meta, $reg:expr, $acc:expr, $descr:expr, $(,)* ) => { ... };
    (
        @resolve_into_type,
        $buildargs:tt,
        field $name:ident $args:tt -> $t:ty as $descr:tt $body:block $( $rest:tt )*
    ) => { ... };
    (
        @resolve_into_type,
        $buildargs:tt,
        field $name:ident $args:tt -> $t:ty $body:block $( $rest:tt )*
    ) => { ... };
    (
        @resolve_into_type,
        $buildargs:tt, description : $value:tt $( $rest:tt )*
    ) => { ... };
    (
        @resolve_into_type,
        $buildargs:tt, interfaces : $value:tt $( $rest:tt )*
    ) => { ... };
    (
        @concrete_type_name,
        $buildargs:tt,
        field $name:ident $args:tt -> $t:ty as $descr:tt $body:block $( $rest:tt )*
    ) => { ... };
    (
        @concrete_type_name,
        $buildargs:tt,
        field $name:ident $args:tt -> $t:ty $body:block $( $rest:tt )*
    ) => { ... };
    (
        @concrete_type_name,
        $buildargs:tt, description : $value:tt $( $rest:tt )*
    ) => { ... };
    (
        @concrete_type_name,
        $buildargs:tt, interfaces : $value:tt $( $rest:tt )*
    ) => { ... };
    (
        @concrete_type_name,
        ($outname:tt, $ctxtarg:ident, $ctxttype:ty),
        instance_resolvers : | $ctxtvar:pat | [ $( $resolver:expr , )* ] $( $rest:tt )*
    ) => { ... };
    ( @concrete_type_name, $buildargs:tt, ) => { ... };
    (
        @resolve_into_type,
        ($outname:tt, $typenamearg:ident, $execarg:ident, $ctxttype:ty),
        instance_resolvers : | $ctxtvar:pat | [ $( $resolver:expr , )* ] $( $rest:tt )*
    ) => { ... };
    ( @resolve_into_type, $buildargs:tt, ) => { ... };
    (
        ( $($lifetime:tt),* ) $name:ty : $ctxt:ty as $outname:tt | &$mainself:ident | {
            $( $items:tt )*
        }
    ) => { ... };
    (
        <$($lifetime:tt),*> $name:ty : $ctxt:ty as $outname:tt | &$mainself:ident | {
            $( $items:tt )*
        }
    ) => { ... };
    (
        $name:ty : $ctxt:ty as $outname:tt | &$mainself:ident | {
            $( $items:tt )*
        }
    ) => { ... };
}

Expose GraphQL interfaces

Mapping interfaces to GraphQL can be tricky: there is no direct counterpart to GraphQL interfaces in Rust, and downcasting is not possible in the general case. Many other GraphQL implementations in other languages use instance checks and either dynamic typing or forced downcasts to support these features.

A GraphQL interface defines fields that the implementing types also need to implement. A GraphQL interface also needs to be able to determine the concrete type name as well as downcast the general type to the actual concrete type.

Syntax

See the documentation for graphql_object! on the general item and type syntax. graphql_interface! requires an additional instance_resolvers item, and does not support the interfaces item.

instance_resolvers is a list/lambda hybrid used to resolve the concrete instance type of the interface. It starts with a context argument and continues with an array of expressions, each resolving into an Option<T> of the possible instances:

instance_resolvers: |&context| [
    context.get_human(self.id()), // returns Option<Human>
    context.get_droid(self.id()), // returns Option<Droid>
],

Each item in the array will be executed in order when the concrete type is required.

Example

A simplified extract from the StarWars schema example shows how to use the shared context to implement downcasts.

struct Human { id: String }
struct Droid { id: String }
struct Database {
    humans: HashMap<String, Human>,
    droids: HashMap<String, Droid>,
}

trait Character {
    fn id(&self) -> &str;
}

impl Character for Human {
    fn id(&self) -> &str { &self.id }
}

impl Character for Droid {
    fn id(&self) -> &str { &self.id }
}

graphql_object!(Human: Database as "Human" |&self| {
    field id() -> FieldResult<&str> { Ok(&self.id) }
});

graphql_object!(Droid: Database as "Droid" |&self| {
    field id() -> FieldResult<&str> { Ok(&self.id) }
});

// You can introduce lifetimes or generic parameters by < > before the name.
graphql_interface!(<'a> &'a Character: Database as "Character" |&self| {
    field id() -> FieldResult<&str> { Ok(self.id()) }

    instance_resolvers: |&context| [
        context.humans.get(self.id()),
        context.droids.get(self.id()),
    ]
});