GraphQL

The Swift implementation for GraphQL, a query language for APIs created by Facebook.

This repo is a Swift port of the JavaScript reference implementation. To create GraphQL schemas more easily, use graphql-generator or Graphiti, and to expose your schema through HTTP, check out graphql-vapor or graphql-hummingbird

Looking for help? Find resources from the GraphQL community.

Usage

Schema Definition

The GraphQLSchema object can be used to define GraphQL Schemas and Types. These schemas are made up of types, fields, arguments, and resolver functions. Below is an example:

letschema=tryGraphQLSchema(
query:GraphQLObjectType( // Defines the special "query" type
name:"Query",
fields:["hello":GraphQLField( // Users may query 'hello'
type: GraphQLString, // The result is a string type
resolve:{ _, _, _, _ in"world" // The result of querying 'hello' is "world"
})]))

For more complex schema examples see the test files.

Execution

Once a schema has been defined queries may be executed against it using the global graphql function:

letresult=tryawaitgraphql(
schema: schema,
request:"{ hello }")

The result of this query is a GraphQLResult that encodes to the following JSON:

{ "hello": "world" }

Subscription

This package supports GraphQL subscription. To create a subscription field in a GraphQL schema, use the subscribe resolver that returns any type that conforms to AsyncSequence, with a Sendable element type. You must also provide a resolver, which defines how to process each event as it occurs and must return the field result type. Here is an example:

letschema=tryGraphQLSchema(
subscribe:GraphQLObjectType(
name:"Subscribe",
fields:["hello":GraphQLField(
type: GraphQLString,
resolve:{ eventResult, _, _, _ in // Defines how to transform each event when it occurs
return eventResult
},
subscribe:{ _, _, _, _ in // Defines how to construct the event stream
returnAsyncThrowingStream<String,Error>{ continuation inlettimer=Timer.scheduledTimer(
withTimeInterval:3,
repeats:true,){
continuation.yield("world") // Emits "world" every 3 seconds
}}})]))

To execute a subscription use the graphqlSubscribe function:

letsubscriptionResult=tryawaitgraphqlSubscribe(
schema: schema,)letstream= subscriptionResult.get()fortryawaitresultin stream {print(result)}

The code above will print the following JSON every 3 seconds:

{ "hello": "world" }

Encoding Results

If you encode a GraphQLResult with an ordinary JSONEncoder, there are no guarantees that the field order will match the query, violating the GraphQL spec. To preserve this order, GraphQLResult should be encoded using the GraphQLJSONEncoder provided by this package.

Support

This package aims to support the previous three Swift versions.

For details on upgrading to new major versions, see MIGRATION.

Contributing

If you think you have found a security vulnerability, please follow the Security guidelines.

Those contributing to this package are expected to follow the Swift Code of Conduct, the Swift API Design Guidelines, and the SSWG Technical Best Practices.

This repo uses the standard swift format, and includes lint checks to enforce these formatting standards. To format your code, run:

swift format --parallel --in-place --recursive ./

Most of this repo mirrors the structure of the canonical GraphQL implementation written in Javascript/Typescript. If there is any feature missing, looking at the original code and "translating" it to Swift works, most of the time. For example:

Swift

/Sources/GraphQL/Language/AST.swift

Javascript/Typescript

/src/language/ast.js

License

This project is released under the MIT license. See LICENSE for details.