GraphQLInputObject

A GraphQL Input Object is a Struct that can be used as an input for a method.

Example

If want to provide an API for sorting search results. We can create a struct for those options.

enum Order: String, CaseIterable, GraphQLEnum {
   case ascending
   case descending
}

struct SortOptions: GraphQLInputType {
   let field: KeyPath<SearchResult, Int>
   let order: Order
}

class Query: QueryType {
   func search(term: String, sortOptions: SortOptions?) -> [SearchResult] {
       ...
   }
}

Note

Input types can be useful to group arguments. We can also use them to group arguments that should always be provided together. Like in our search example, we don’t need the user to specify how to sort. But when the user wants the Results sorted by a field, we need to know if they should be sorted in an ascending or descending order. That’s why the Input Object makes sense in this scenario.

Details

• A GraphQL Input Object is Input Resolvable and can be used in any method that should be available in GraphQL
• An Input Object has to be a struct. If it’s not a struct, an error will be thrown.
• All the properties in the struct have to be Input Resolvable as well. Otherwise an error will be thrown.

InputResolvable

Input Resolvable describes an Object that can be used as an Argument to a GraphQL Field.

It means that for a method to be available in GraphQL, all the arguments have to conform to InputResolvable

Input Resolvable Types are:

• Scalars
• Enums
• Input Objects
• Optionals and Arrays through Conditional Conformance

Undocumented

ConnectionProtocol

Describes an Object used for Cursor-Based Pagination. This API is modeled after standards set by Relay and GraphQL.

It relies on the usage of the arguments: first, after, last and before.

• first: Number of items that will be fetched at the start of the list
• after: Cursor of the last element in the page that comes before. Signals that all items in the requested page should be strictly after the element with that cursor. The element with the cursor should be excluded
• last: Number of items that will be fetched at the end of the list
• before: Cursor of the first element in the page that comes after. Signals that all items in the requested page should be strictly before the element with that cursor. The element with the cursor should be excluded

Note

This is a bare bones implementation of Paging, and is not particularly efficient.

If you notice that your methods are all sharing a lot of logic together, perhaps you should take a look at ContextBasedConnection insttead.

ContextBasedConnection

Describes an Object used for Cursor-Based Pagination. This API is modeled after standards set by Relay and GraphQL.

It relies on the usage of the arguments: first, after, last and before.

• first: Number of items that will be fetched at the start of the list
• after: Cursor of the last element in the page that comes before. Signals that all items in the requested page should be strictly after the element with that cursor. The element with the cursor should be excluded
• last: Number of items that will be fetched at the end of the list
• before: Cursor of the first element in the page that comes after. Signals that all items in the requested page should be strictly before the element with that cursor. The element with the cursor should be excluded

Note

This is very similar to ConnectionProtocol.

ContextBasedConnection describes the same functionality of ConnectionProtocolbut attemps to compute certain context information about a page only once.

A type implementing this protocol will first compute a context object that the other methods can use, instead of the raw arguments first, after, last and before. It is intended for scenarios where totalCount, pageInfo and edges all rely on very similar information.

EdgeProtocol

Describes an Edge during Paging. An Edge contains the Node that is the value, the cursor of that value, and any additional information.

Note

An Edge is OutputResolvable. Any implementations of it, should be including the node and the cursor in the output. It is best if you delegate the implementation of OutputResolvable to GraphQLObject instead.

Undocumented

Undocumented

Undocumented

GraphQLObject

A GraphQL Object is a Class that can be used as an output in GraphQL.

It behaves as follows:

• All properties of types that are OutputResolvable (can be outputs in GraphQL) will be added to the Schema.
• All methods where all arguments are of types that are InputResolvable (can be inputs in GraphQL) and the return type is OutputResolvable (can be outputs in GraphQL) will be added to the Schema.

Example

If we are implementing a Todo App, a Todo and User in our API would be two classes:

class Author: GraphQLObject {
   var name: String

   func store() { ... }

   func todos() -> [Todo] { ... }
}

class Todo: GraphQLObject {
   var title: String
   var completed: Bool

   func store() { ... }

   func author() -> User { ... }
}

The previous code would then be exported to GraphQL like so:

type User {
   name: String!
   todos: [Todo!]!
}

type Todo {
   title: String!
   completed: Boolean!
   author: User!
}

As can be seen in the example:

• All the properties are scalar values that can be outputs in GraphQL.
• All the properties are included.
• And all the functions that return GraphQL Values are also included
• The store functions return Void, which is not a GraphQL Output. These methods are therefore not included.

Undocumented

OutputResolvable

Output Resolvable describes an Object that can be used as an Output in GraphQL.

It means that for a method or property to be available in GraphQL, all the output has to conform to OutputResolvable

Output Resolvable Types are:

• Scalars
• Enums
• Objects
• Root Types
• Optionals, Futures and Arrays through Conditional Conformance

Concrete Resolvable

A Resolvable that is required to have a type name

Key Path Listable

A type whose Key Paths can be used in GraphQL

Resolvable

A Type with a possible type name that will be used in GraphQL

Value Resolvable

A type that can be turned into a GraphQL Value. Generally used to convert default values into something that can be added to the Schema

GraphQL Root Type

An GraphQL Object that is at the Root of a Schema. Can either be a Query Type or a Mutation Type

The only additional requirement for a GraphQLType is that it can be initialized with a ViewerContext. The ViewerContext in this scenario refers to a Context Object, that tells the Query/Mutation Type what it needs to know about the User who is requesting the data.

Example

If we are building a Todo App and want allow users to request their Todos. We can use the User as a ViewerContext

class Query: GraphQLRootType {
   let user: User

   func myTodos() -> [Todo] { ... }

   init(viewerContext user: User) {
       self.user = user
   }
}

This is then translated into:

type Query {
   myTodos: [Todo!]!
}

GraphQL Schema

A GraphQL Schema describes the entire API that is available. It’s basically only a name space for your Query and Mutation Types.

Your Query and Mutation Types have to be Root Types with the same Viewer Context.

• A Query Type is mandatory.
• A Mutation Type is optional.

Examples

If you only want to offer a Query Type, you only need to implement that class:

enum MySchema {

   class Query: QueryType {
       func greeting(name: String = "World") -> String {
           return "Hello, \(name)!"
       }

       init(viewerContext: ()) { ... }
   }

}

that gets translated to the following schema:

type Query {
   greeting(name: String! = "World"): String!
}

Alternatively you can also specify a Mutation Type:

enum MySchema {
   class Query: QueryType {
       func greeting(name: String = "World") -> String {
           return "Hello, \(name)!"
       }

       init(viewerContext: ()) { ... }
   }

   class Mutation: MutationType {
       func store(status: String) -> String { ... }

       init(viewerContext: ()) { ... }
   }
}

Which would generate this Schema:

type Query {
   greeting(name: String! = "World"): String!
}

type Mutation {
   store(status: String!): String!
}

If your types need to have a context for the current user, they need to use the exact same ViewerContext:

enum MySchema {
   typealias ViewerContext = User

   class Query: QueryType {
       let user: User

       var greeting: String {
           return "Hello, \(user.name)!"
       }

       init(viewerContext: User) { ... }
   }

   class Mutation: MutationType {
       let user: User

       func store(status: String) -> String { ... }

       init(viewerContext: User) { ... }
   }
}

Mandatory Root Type

An GraphQL Root Type that has the additional requirement of being mandatory. For example for Query Types.

Undocumented

Undocumented

Undocumented