Blog
/
Education

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

cover
Jens Neuse

Jens Neuse

min read

We're hiring!

We're looking for Golang (Go) Developers, DevOps Engineers and Solution Architects who want to help us shape the future of Microservices, distributed systems, and APIs.

By working at WunderGraph, you'll have the opportunity to build the next generation of API and Microservices infrastructure. Our customer base ranges from small startups to well-known enterprises, allowing you to not just have an impact at scale, but also to build a network of industry professionals.

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:

1
2
3
4
5
6
7
8
9
10
11
12

Getting started with GraphQL Subgraph Composition in TypeScript and NodeJS

Install the library:

1

Compose your Subgraphs:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30

Getting started with GraphQL Subgraph Composition in Golang

Install the library:

1

Compose your Subgraphs:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59

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.