Swiftpack.co - Package - nerdsupremacist/GraphZahl

low effort logo

GraphZahl (Alpha)

Create the best GraphQL APIs ever using Swift. GraphZahl is a Swift Framework that let's you write your Server the simplest way possible! With a magic, Codable-like API.

Here are the main reasons, why you could like it:

  • 📝 Declarative
  • ðŸ“Ķ Compositable and extendable
  • 🔐 Type-Safety
  • 🕓 ZERO Boilerplate
  • 😍 Familiar and Intuitive Codable-like Feel
  • ðŸĪŠ Amazing for Quick Prototyping

TL;DR?

Let's cut the chase and write our Hello World!

// Create a GraphQLSchema
enum HelloWorld: GraphQLSchema {
    
    // Describe the Query Type 
    class Query: QueryType {
        func greeting(name: String) -> String {
            return "Hello, \(name)"
        }
    }

    typealias Mutation = None
}

// Run a query using .perform
let result = HelloWorld.perform(request: "...")

And you can even connect it to GraphiQL and test it:

graphiql left: a query for data | middle: the returned json from our API | right: our server API reference

Let's break that down!

Every GraphQL API begins with a root Schema where you define the Query Type and Mutation Type:

  • Query Type (Mandatory): Describes all the read operations that can be done
  • Mutation Type (Optional): Descripes all the write operations

For now we'll focus on the Query Type. GraphZahl will now look at any properties and functions that can be served in GraphQL, and will offer those as fields in your API.

In our example this means that it will find the function greeting and see that all the inputs and outputs are availanle as GraphQL Types and register it. Super easy 😍!

Installation

Swift Package Manager

You can install GraphZahl via Swift Package Manager by adding the following line to your Package.swift:

import PackageDescription

let package = Package(
    [...]
    dependencies: [
        .package(url: "https://github.com/nerdsupremacist/GraphZahl.git", from: "0.1.0-alpha.")
        
        // It is recommended to use GraphZahl alongside Vapor
        .package(url: "https://github.com/nerdsupremacist/graphzahl-vapor-support.git", from: "0.1.0-alpha.")
    ]
)

Usage

Most users of GraphZahl need to understand the four main provided protocols:

  • GraphQLObject: A type that is composed from multiple properties and functions
  • GraphQLSchema: The root of any API
  • GraphQLScalar: A singular value
  • GraphQLEnum: An simple enum that is RawRepresentable with String (so no associated values, sadly)

As well as the extensions that enable you to get the most of GraphZahl alongside other common server-side libraries like Vapor and Fluent.

GraphQLObject

You can provide any class you want by simply making it implement GraphQLObject.

And voila 😍 !!!! You don't have to implement anything. GraphZahl will do all the magic for you:

  • Every property that is either: a. a GraphQL Object, a. Scalar a. or Enum

will be available via GraphQL. Zero hassle. Crazy!!!

  • Every method where: a. every input is a Scalar or Enum a. the return type is either: a. a GraphQL Object, a. Scalar a. or Enum

is now also available! Just like that. Awesome!!!

Note: when it comes to GraphQL Types GraphZahl also supports Optionals, Arrays and Futures out of the box, thanks to Conditional Conformance.

Let's try it:

We define our class. With some properties and methods:

class MyObject: GraphQLObject {
    let greeting = "Hello World!"
    let favouriteNumber = 42

    func count(to number: Int) -> String {
        return (0..<number).map(String.init).joined(separator: ", ")
    }
}

And we can see it appear in our API:

left: a query for the data of MyObject | middle: the returned json from our API | right: the type definition of MyObject

Your object can also return nested objects:

class OtherObject: GraphQLObject {
    let number: Int
    
    init(number: Int) {
        self.number = number
    }
}

class MyObject: GraphQLObject {
    ...
    
    let other = OtherObject(number: 1337)
    let others = [OtherObject(number: 0), OtherObject(number: 1)] // Arrays also work
}

And you can see the results immediately:

GraphQLSchema

A Schema is basically the namespace where you define two objects: A Query and a Mutation Type. The query and mutation behave like regular GraphQLObjects. All the features mentioned above will be included out of the box.

The QueryType is mandatory and always has to be defined! If your API doesn't need Mutations, just set it to None like we did before.

What if you want to make data user dependent?

That's why Query and Mutation Types come with an extra constraint (for simplicity this was omitted in the snippets before). They have what we call an associated ViewerContext and need an initializer with that ViewerContext. Note: the ViewerContext of the Query and the Mutation have to Match.

For example a Todo App might look like this:

enum TodoApp: GraphQLSchema {
    typealias ViewerContext = LoggedInUser?

    class Query: QueryType {
        let user: LoggedInUser?
        
        func myTodos() -> [Todo]? {
            return user?.todosFromDB()
        }

        required init(viewerContext user: LoggedInUser?) {
            self.user = user
        }
    }

    typealias Mutation = None
}

If you don't need a Viewer Context just set it to Void:

enum HelloWorld: GraphQLSchema {
    typealias ViewerContext = Void

    class Query: QueryType {
        func greeting(name: String) -> String {
            return "Hello, \(name)"
        }

        required init(viewerContext: ViewerContext) { }
    }

    typealias Mutation = None
}

GraphQLScalar

If you have a value that can be represented as a standard Scalar Value, you can return that value as well, with the added Type Safety benefit, of not mixing it with the standard types.

To implement a GraphQLScalar you need to be able to encode and decode it as a ScalarValue (String, Number, Bool)

For example if you want to return URLs you can implement it in an extension:

extension URL: GraphQLScalar {
    public init(scalar: ScalarValue) throws {
        // attempt to read a string and read a url from it
        guard let url = URL(string: try scalar.string()) else {
            throw ...
        }
        self = url
    }

    public func encodeScalar() throws -> ScalarValue {
        // delegate encoding to absolute string
        return try absoluteString.encodeScalar()
    }
}

And presto! Every time a URL comes up in an Object, it will be made available:

enum HelloWorld: GraphQLSchema {
    class Query: QueryType {
        let url = URL(string: "https://github.com/nerdsupremacist/GraphZahl")
    }

    typealias Mutation = None
}

You can do this with virtually all kinds of types: Dates in the format of your choice, Percentages, HTML Text, whatever you want.

GraphQLEnum

The last one is the simplest case. If you want to support an enum in your API, it has to be RawRepresentable with String and implement GraphQLEnum.

enum Envirornment: String, GraphQLEnum {
    case production
    case development
    case testing
}

That's it!

Union Types

GraphZahl supports Union Types via the UnionN types of up to 20 generic arguments. They're basically enums with N cases. One for each Type

class Query: QueryType {
    func search(term: String) -> [Union3<User, Page, Group>] {
        return [
            .a(user),
            .b(page),
            .c(group),
        ]
    }
}

Subclassing Support

GraphZahl supports subclassing, but due to Subclassing not being available in GraphQL, it is abstracted as an extra Interface.

For example:

class A: GraphQLObject {
    ...
}

class B: A {
    ...
}

will be represented as the interface A and the concrete types __A and B:

// Interface that displays the output of any A
interface A {
    ...
}

// An instance of the superclass A
type __A implements A {
    ...
}

// An instance of the subclass B
type B implements A {
    ...
}

Extensions and Plugins

There's also some extensions on top of GraphZahl to add support for different scenarios that are not necessarily the norm:

Vapor Support (Recommended)

To serve your API via Vapor, you can use graphzahl-vapor-support:

enum HelloWorld: GraphQLSchema {
    class Query: QueryType {
        func greeting(name: String) -> String {
            return "Hello, \(name)"
        }
    }

    typealias Mutation = None
}

// Add the API to the Routes of your Vapor App
app.routes.graphql(path: "api", "graphql", use: HelloWorld.self)

And you can even add GraphiQL:

app.routes.graphql(path: "api", "graphql", use: HelloWorld.self, includeGraphiQL: true)

Fluent Support

To use Fluent Types and Models in your API, you can use graphzahl-fluent-support:

enum API: GraphQLSchema {
    typealias ViewerContext = Database

    class Query: QueryType {
        let database: Database

        // QueryBuilders are supported with additional paging API
        func todos() -> QueryBuilder<Todo> {
            return Todo.query(on: database)
        }

        required init(viewerContext database: Database) {
            self.database = database
        }
    }
    
    ...
}

It adds support for:

  • QueryBuilder
  • @Parent
  • @Children
  • @Siblings
  • @Field
  • @ID

Deploy

Heroku

If you're deploying to Heroku, it's super simple. You'll need 2 things:

1. Add the build pack

Add the build pack to heroku:

heroku buildpacks:set nerdsupremacist/graph-zahl

2. Add a Procfile

In our Repo we will add a Procfile that will tell Heroku the starting point of our app:

For example, where the Target of our API is called MyServer and is using Vapor:

web: MyServer serve --env production --hostname 0.0.0.0 --port $PORT

You can also take some inspiration from the Deployment documentation for Vapor.

Building for Linux

If you're building a GraphZahl app for Linux, you'll need to add -E linker flag. For example:

swift build -Xlinker -E {OTHER_FLAGS} -c debug

Known Issues

  • Due to issues with combinatorics the amount of arguments for a method has been limited
  • Calling methods hasn't been tested against every argument and return type combination possible. If you encounter any crashes or failures, please open an issue

Contributions

Contributions are welcome and encouraged!

Related Work

GraphZahl works best when coupled with Graphaello on the Client Side. Graphaello enables you to use GraphQL directly from your SwiftUI Views.

Learn

GraphZahl is named after Count von Count from Sesame Street but in German "Graf Zahl".

GraphZahl uses GraphQLSwift, Runtime and Swift NIO under the Hood. If you are looking for an alternative check out Graphiti, which is more verbose and complex to use, but offers you more control and better performance.

This is currenlty a research project. More details about how it works, will be published later. This was very difficult to build, so trust me, I really want to talk in detail about it... ;)

License

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

This project is being done under the supervision of the Chair for Applied Software Enginnering at the Technical University of Munich. The chair has everlasting rights to use and maintain this tool.

Github

link
Stars: 48

Used By

Total: 0

Releases

- 2020-04-05 17:00:40

- 2020-04-01 11:13:58

- 2020-04-01 11:07:11

- 2020-04-01 09:41:49

- 2020-04-01 09:07:35

- 2020-03-30 17:10:04

- 2020-03-30 17:00:21

- 2020-03-30 00:25:25

- 2020-03-29 23:39:37

  • Fixed runtime issues with loading the vtable for types with extra metadata init data
  • Added support for Union Types
  • Added support for Subclassing

- 2020-03-26 18:33:07

- 2020-03-23 18:55:51

- 2020-03-23 09:54:54

- 2020-03-22 18:02:20

- 2020-03-22 16:35:16

- 2020-03-22 16:08:03

- 2020-03-21 14:18:50