OSS Composition library for GraphQL Federation v1 & v2 in TypeScript, NodeJS and Golang

Are you looking for an Open Source Graph Manager? Cosmo is the most complete solution including Schema Registry, Router, Studio, Metrics, Analytics, Distributed Tracing, Breaking Change detection and more.

We're back from the GraphQL Conf 2023 in San Francisco and we're excited to announce our Composition library for Federation v1 and v2. Compose Subgraphs in TypeScript, NodeJS and Golang and get Composition validation errors.

While we were slacking off at the conference, our team was working hard to build an open source Composition library. Implementing Subgraph composition is very complex, there are a lot of edge cases, and the rules are not entirely clear as there's no official specification yet. We're already working on Open Federation to fix that. As we're taking a huge bet on GraphQL Federation, we believe that an open source Composition library is the best way to build the best and most reliable Composition library.

As complex as implementing Subgraph composition is, using it is very simple. As the tooling for GraphQL is more mature in TypeScript and NodeJS, we've implemented the Composition library in TypeScript and NodeJS. However, as we're using Golang a lot, we've also decided to build a wrapper for Golang, allowing you to use the Composition Library in Go as well.

The code is Apache 2.0 licensed and available on GitHub. It's part of our Cosmo monorepo, which is a whole OSS platform to build and manage Federated GraphQL APIs.

What is Subgraph Composition?

Subgraph Composition is the process of combining multiple Subgraphs into a federated Graph. The composition library takes a list of Subgraphs and returns a federated Graph, or a list of errors if the Subgraphs are not compatible.

The second part is the most important one. Subgraph composition is a very complex topic and it's easy to make mistakes when designing your Subgraphs. The composition library doesn't just tell you that there's an error. It tells you exactly what the error, gives you detailed information about the error, and advice on how to fix it.

Here's an example error message:

Error: The path "Query.user.name" cannot be resolved because:
    The root type field "Query.user" is defined in the following subgraph: "subgraph-b".
    However, "User.name" is only defined in the following subgraph: "subgraph-c".
    Consequently, "User.name" cannot be resolved through the root type field "Query.user".
Potential solutions:
    Convert "User" into an entity using a "@key" directive.
    Add the shareable root type field "Query.user" to the following subgraphs: "subgraph-c".
        For example (note that V1 fields are shareable by default and do not require a directive):
            type Query {
                ...
                user: User @shareable
            }

Getting started with GraphQL Subgraph Composition in TypeScript and NodeJS

Install the library:

npm install @wundergraph/composition

Compose your Subgraphs:

import { federateSubgraphs, Subgraph } from '@wundergraph/composition';
import { parse } from 'graphql';

const { errors, federationResult }: FederationResult = federateSubgraphs([subgraphA, subgraphB]);

const subgraphA: Subgraph = {
  name: 'subgraph-a',
  url: 'http://localhost:4001',
  definitions: parse(`
    type User @key(fields: "id") {
      id: ID!
      name: String!
    }
  `),
};

const subgraphB: Subgraph = {
  name: 'subgraph-b',
  url: 'http://localhost:4002',
  definitions: parse(`
    type Query {
      users: [User!]!
    }

    type User @key(fields: "id") {
      id: ID!
      interests: [String!]!
    }
  `),
};

Getting started with GraphQL Subgraph Composition in Golang

Install the library:

go get github.com/wundergraph/cosmo/composition-go

Compose your Subgraphs:

package main

import (
    "fmt"
    "log"

    "github.com/wundergraph/cosmo/composition-go"
)

func main() {
    federated, err := composition.Federate(&composition.Subgraph{
        Name: "A",
        Schema: `type Query {
            query: Nested @shareable
          }

          type Nested @shareable {
            nest: Nested2
          }

          type Nested2 @shareable {
            nest: Nested3
          }

          type Nested3 @shareable {
            nest: Nested4
          }

          type Nested4 {
            name: String
          }`,
    }, &composition.Subgraph{
        Name: "B",
        Schema: `type Query {
            query: Nested @shareable
          }

          type Nested @shareable {
            nest: Nested2
          }

          type Nested2 @shareable {
            nest: Nested3
          }

          type Nested3 @shareable {
            nest: Nested4
          }

          type Nested4 {
            age: Int
          }`,
    })
    if err != nil {
        log.Fatal(err)
    }
    fmt.Println(federated.SDL)
}

Performance considerations for Golang:

By default, this package uses the goja runtime to run the composition algorithm. This has no dependencies and supports all platforms, but depending on your inputs it can be too slow.

For better performance, a V8 backend is also available using the wg_composition_v8 build tag, which is ~50x times faster. This uses the V8 JS engine to run the algorithm, but it increases the binary size and doesn't work on Windows, so it's not enabled by default. To enable it, use go build -tags wg_composition_v8` when compiling.

Behind the scenes, we're using tsup to bundle the TypeScript code into a single JavaScript file which is compatible with goja and the v8 runtime. We're then adding a small wrapper around both runtimes to communicate with the JavaScript code and expose the composition function with a Go API.

Conclusion

We're very excited to announce our Composition library and hope for a lot of feedback and collaboration to make it the best Composition library out there. Go check it out on GitHub and star the repository if you like it.