Graphiti

Graphiti is a Swift library for building GraphQL schemas fast, safely and easily in Swift code.

To expose your schema through HTTP, check out graphql-vapor or graphql-hummingbird, and to generate Swift code from GraphQL SDL files, use graphql-generator instead.

Getting Started

An overview of GraphQL in general is available in the
README for the
Specification for GraphQL. That overview
describes a simple set of GraphQL examples that exist as tests
in this repository. A good way to get started with this repository is to walk
through that README and the corresponding tests in parallel.

Using Graphiti

Add Graphiti to your Package.swift

swiftCopy
import PackageDescription

let package = Package(
    dependencies: [
        .package(url: "https://github.com/GraphQLSwift/Graphiti.git", .upToNextMinor(from: "0.20.1")),
    ]
)

Graphiti provides two important capabilities: building a type schema, and
serving queries against that type schema.

Defining entities

First, we declare our regular Swift entities.

swiftCopy
struct Message : Codable {
    let content: String
}

⭐️ One of the main design decisions behind Graphiti is not to polute your entities declarations. This way you can bring your entities to any other solution with ease.

Defining the context

Second step is to create your application's context. The context will be passed to all of your field resolver functions. This allows you to apply dependency injection to your API. This is the place where you can put code that talks to a database or another service.

swiftCopy
struct Context {
    func message() -> Message {
        Message(content: "Hello, world!")
    }
}

⭐️ Notice again that this step doesn't require Graphiti. It's purely business logic.

Defining the GraphQL API resolver

Now that we have our entities and context we can create the GraphQL API resolver.

swiftCopy
import Graphiti

struct Resolver {
    func message(context: Context, arguments: NoArguments) -> Message {
        context.message()
    }
}

Defining the GraphQL API schema

Now we can finally define the GraphQL API with its schema.

swiftCopy
struct MessageAPI : API {
    let resolver: Resolver
    let schema: Schema<Resolver, Context>
}

let api = MessageAPI(
    resolver: Resolver()
    schema: try! Schema<Resolver, Context> {
        Type(Message.self) {
            Field("content", at: \.content)
        }

        Query {
            Field("message", at: Resolver.message)
        }
    }
)

Schemas may also be created in a modular way using SchemaBuilder:

<blockquote> <details open="true"> <summary>SchemaBuilder API</summary>

swiftCopy
let builder = SchemaBuilder(Resolver.self, Context.self)
builder.add(
    Type(Message.self) {
        Field("content", at: \.content)
    }
)
builder.query.add(
    Field("message", at: Resolver.message)
)
let schema = try builder.build()

let api = MessageAPI(
    resolver: Resolver()
    schema: schema
)

</details> <details> <summary>PartialSchema implementation</summary>

swiftCopy
final class ChatSchema: PartialSchema<Resolver, Context> {
    @TypeDefinitions
    public override var types: Types {
        Type(Message.self) {
            Field("content", at: \.content)
        }
    }

    @FieldDefinitions
    public override var query: Fields {
        Field("message", at: Resolver.message)
    }
}
let schema = try SchemaBuilder(Resolver.self, Context.self)
    .use(partials: [ChatSchema(), ...])
    .build()

let api = MessageAPI(
    resolver: Resolver()
    schema: schema
)

</details> <details> <summary>PartialSchema instance</summary>

swiftCopy
let chatSchema = PartialSchema<Resolver, Context>(
    types:  {
        Type(Message.self) {
            Field("content", at: \.content)
        }
    },
    query: {
        Field("message", at: Resolver.message)
    }
)
let schema = try SchemaBuilder(Resolver.self, Context.self)
    .use(partials: [chatSchema, ...])
    .build()

let api = MessageAPI(
    resolver: Resolver()
    schema: schema
)

</details>

---

</blockquote>

⭐️ Notice that API allows dependency injection. You could pass mocks of resolver and context when testing, for example.

Querying

swiftCopy
let result = try await api.execute(
    request: "{ message { content } }",
    context: Context()
)
print(result)

The output will be:

jsonCopy
{"data":{"message":{"content":"Hello, world!"}}}

API.execute returns a GraphQLResult which adopts Encodable. You can use it with a JSONEncoder to send the response back to the client using JSON.

Async resolvers

Resolver functions can also be async:

swiftCopy
struct Resolver {
    func message(context: Context, arguments: NoArguments) async -> Message {
        await someAsyncMethodToGetMessage()
    }
}

Subscription

This library supports GraphQL subscriptions, and supports them through the Swift Concurrency AsyncThrowingStream type. See the Usage Guide for details.

If you are unable to use Swift Concurrency, you must create a concrete subclass of the EventStream class that implements event streaming
functionality. If you don't feel like creating a subclass yourself, you can use the GraphQLRxSwift repository
to integrate RxSwift observables out-of-the-box. Or you can use that repository as a reference to connect a different
stream library like ReactiveSwift, OpenCombine, or
one that you've created yourself.

Additional Examples

For a progressive walkthrough, see the Usage Guide. The Star Wars API provides a fairly complete example.

Support

This package supports Swift versions in alignment with Swift NIO.

Contributing

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

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

License

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