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:

swift
let schema = try GraphQLSchema(
    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:

swift
let result = try await graphql(
    schema: schema,
    request: "{ hello }"
)

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

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:

swift
let schema = try GraphQLSchema(
    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
                    return AsyncThrowingStream<String, Error> { continuation in
                        let timer = Timer.scheduledTimer(
                            withTimeInterval: 3,
                            repeats: true,
                        ) {
                            continuation.yield("world")  // Emits "world" every 3 seconds
                        }
                    }
                }
            )
        ]
    )
)

To execute a subscription use the graphqlSubscribe function:

swift
let subscriptionResult = try await graphqlSubscribe(
    schema: schema,
)
let stream = subscriptionResult.get()
for try await result in stream {
    print(result)
}

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

json
{ "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:

bash
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: