GraphQL
The Swift implementation for GraphQL, a query language for APIs created by Facebook.
Looking for help? Find resources from the 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:
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.
This repo only contains the core GraphQL implementation and does not focus on the ease of schema creation. For a better experience when creating your GraphQL schema use Graphiti.
Execution
Once a schema has been defined queries may be executed against it using the global graphql
function:
let result = try graphql(
schema: schema,
request: "{ hello }",
eventLoopGroup: eventLoopGroup
).wait()
The result of this query is a GraphQLResult
that encodes to the following JSON:
{ "hello": "world" }
Subscription
This package supports GraphQL subscription, but until the integration of AsyncSequence
in Swift 5.5 the standard Swift library did not
provide an event-stream construct. For historical reasons and backwards compatibility, this library implements subscriptions using an
EventStream
protocol that nearly every asynchronous stream implementation can conform to.
To create a subscription field in a GraphQL schema, use the subscribe
resolver that returns an EventStream
. 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:
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
let asyncStream = AsyncThrowingStream<String, Error> { continuation in
let timer = Timer.scheduledTimer(
withTimeInterval: 3,
repeats: true,
) {
continuation.yield("world") // Emits "world" every 3 seconds
}
}
return ConcurrentEventStream<String>(asyncStream)
}
)
]
)
)
To execute a subscription use the graphqlSubscribe
function:
let subscriptionResult = try graphqlSubscribe(
schema: schema,
).wait()
// Must downcast from EventStream to concrete type to use in 'for await' loop below
let concurrentStream = subscriptionResult.stream! as! ConcurrentEventStream
for try await result in concurrentStream.stream {
print(result)
}
The code above will print the following JSON every 3 seconds:
{ "hello": "world" }
The example above assumes that your environment has access to Swift Concurrency. If that is not the case, try using GraphQLRxSwift
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.
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 SwiftFormat, and includes lint checks to enforce these formatting standards.
To format your code, install swiftformat
and run:
swiftformat .
Most of this repo mirrors the structure of (the canonical GraphQL implementation written in Javascript/Typescript)[https://github.com/graphql/graphql-js]. 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
License
This project is released under the MIT license. See LICENSE for details.