type_resolver.md

GraphQL::Stitching::TypeResolver

A TypeResolver contains all information about a root query used by stitching to fetch location-specific variants of a merged type. Specifically, resolvers manage parsed keys and argument structures.

Arguments

Type resolvers configure arguments through a template string of GraphQL argument literal syntax. This allows sending multiple arguments that intermix stitching keys with complex object shapes and other static values.

Key insertions

Key values fetched from previous locations may be inserted into arguments. Key insertions are prefixed by $ and specify a dot-notation path to any selections made by the resolver key, or __typename.

type Query {
  entity(id: ID!, type: String!): [Entity]!
    @stitch(key: "owner { id }", arguments: "id: $.owner.id, type: $.__typename")
}

Key insertions are not quoted to differentiate them from other literal values.

Lists

List arguments may specify input just like non-list arguments, and GraphQL list input coercion will assume the shape represents a list item:

type Query {
  product(ids: [ID!]!, source: DataSource!): [Product]!
    @stitch(key: "id", arguments: "ids: $.id, source: CACHE")
}

List resolvers (that return list types) may only insert keys into repeatable list arguments, while non-list arguments may only contain static values. Nested list inputs are neither common nor practical, so are not supported.

Built-in scalars

Built-in scalars are written as normal literal values. For convenience, string literals may be enclosed in single quotes rather than escaped double-quotes:

type Query {
  product(id: ID!, source: String!): Product
    @stitch(key: "id", arguments: "id: $.id, source: 'cache'")

  variant(id: ID!, limit: Int!): Variant
    @stitch(key: "id", arguments: "id: $.id, limit: 100")
}

All scalar usage must be legal to the resolver field's arguments schema.

Enums

Enum literals may be provided anywhere in the input structure. They are not quoted:

enum DataSource {
  CACHE
}
type Query {
  product(id: ID!, source: DataSource!): [Product]!
    @stitch(key: "id", arguments: "id: $.id, source: CACHE")
}

All enum usage must be legal to the resolver field's arguments schema.

Input Objects

Input objects may be provided anywhere in the input, even as nested structures. The stitching resolver will build the specified object shape:

input ComplexKey {
  id: ID
  nested: ComplexKey
}
type Query {
  product(key: ComplexKey!): [Product]!
    @stitch(key: "id", arguments: "key: { nested: { id: $.id } }")
}

Input object shapes must conform to their respective schema definitions based on their placement within resolver arguments.

Custom scalars

Custom scalar keys allow any input shape to be submitted, from primitive scalars to complex object structures. These values will be sent and recieved as untyped JSON input:

type Product {
  id: ID!
}
union Entity = Product
scalar Key

type Query {
  entities(representations: [Key!]!): [Entity]!
    @stitch(key: "id", arguments: "representations: { id: $.id, __typename: $.__typename }")
}

Custom scalar arguments have no structured schema definition to validate against. This makes them flexible but quite lax, for better or worse.