/Chester

Chester is a Swift GraphQL query builder.

Primary LanguageSwiftMIT LicenseMIT

Chester

CI codecov.io SwiftPM Compatible Carthage compatible Version License Platform

Sort of Experimental: @resultBuilder Support

@resultBuilder seems like a natural match for this kind of task. There's a separate GraphQLBuilderTests test suite that shows the supported cases. In its basic form you can construct a query like this:

import Chester

let query = GraphQLQuery {
  From("posts")
  Fields("id", "title")
}

Nested queries can be defined in their logical order now:

let query = GraphQLQuery {
  From("posts")
  Fields("id", "title")
  SubQuery {
    From("comments")
    Fields("body")
    SubQuery {
      From("author")
      Fields("firstname")
    }
  }
}

Known Issues

  • Queries with multiple root fields and arguments produce a compiler error (e.g. 'Int' is not convertible to 'Any')

Usage

Chester uses the builder pattern to construct GraphQL queries. In its basic form use it like this:

import Chester

let query = QueryBuilder()
  .from("posts")
  .with(arguments: Argument(key: "id", value: "20"), Argument(key: "author", value: "Chester"))
  .with(fields: "id", "title", "content")

// For cases with dynamic input, probably best to use a do-catch:

do {
  let queryString = try query.build
} catch {
  // Can specify which errors to catch
}

// Or if you're sure of your query

guard let queryString = try? query.build else { return }

You can add subqueries. Add as many as needed. You can nest them as well.

let commentsQuery = QueryBuilder()
  .from("comments")
  .with(fields: "id", content)
let postsQuery = QueryBuilder()
  .from("posts")
  .with(fields: "id", "title")
  .with(subQuery: commentsQuery)

You can search on multiple collections at once

let search = QueryBuilder()
  .from("search")
  .with(arguments: Argument(key: "text", value: "an"))
  .on("Human", "Droid")
  .with(fields: "name")
  .build()

Check the included unit tests for further examples.

Requirements

  • Swift 5
  • Xcode 12.5+
  • iOS 8

Installation

Chester is available through CocoaPods. To install it, simply add the following line to your Podfile:

pod "Chester"

Or Carthage. Add Chester to your Cartfile:

github "JanGorman/Chester"

Or Swift Package Manager. To install it, simply go to File > Swift Package > Add Swift Package Dependency and add "https://github.com/JanGorman/Chester.git" as Swift Package URL. Or add the following line to Package.swift:

dependencies: [
    .package(url: "https://github.com/JanGorman/Chester.git", from: "0.14.0")
]

Author

Jan Gorman

License

Chester is available under the MIT license. See the LICENSE file for more info.