Manipulate and query GraphQL Schemas with ease using Microfiber

A while back we introduced SpectaQL to the open source community and it's been a big success. It gets thousands of weekly downloads, has a healthy amount of user support and interest via github, and has had a number of articles written about it like this one and this one. Our goal for SpectaQL has always been to be the de-facto go-to library to use for auto-generating static HTML documentation for any GraphQL API. A very important feature of SpectaQL is its ability to "hide" any parts of your API that you don't want to expose in your documentation. This sounds like a simple task, but in practice it's actually a bit tricky. In order to make interacting and manipulating a GraphQL schema easy, we developed a tool designed specifically for this purpose. Eventually we realized that while this tool was super integral to SpectaQL, it would also be useful for other applications so we decided to break it out into its own library and open source it! In this post, I'll introduce Microfiber and give an overview of its most interesting features and capabilities.

The Problem

Unless you're an expert, GraphQL schemas can be a bit tricky to wrap your head around and understand their structure. For example, not everyone understands that your queries are actually defined as Fields on a type that you have specified as a special "Query" type (either by convention or by configuration, depending on the implementation you're using). Also, it can be tricky to understand what you need to know about the Type of certain Fields, Arguments or query/mutation results: are they nullable? Are they a single item or a list? If it's a list, can any of the items be null? Furthermore, if you want to "hide" a Type from your schema, how do you go about finding all the references to that Type in Fields, Arguments, or query/mutation results and remove those things as well? Enter Microfiber!

Why "Microfiber"?

Before we dive in further, you may be wondering: why is it called "microfiber"? You know that little fibrous thing that comes with your glasses and is used to clean the lenses? That's a microfiber. Since a microfiber is used for cleaning up things, and our microfiber is used for "cleaning up" your GraphQL schema, we thought the name made sense. Also, since a microfiber is often used to clean glasses, and our microfiber is used heavily by SpectaQL (a reference to glasses) we thought the name fit doubly as well.

Getting started

In order to keep Microfiber lightweight in terms of dependencies, it requires you to provide it your schema in the form of an Introspection Query result. This result is just a simple JSON object. You can set a number of interesting options when creating your Microfiber instance, however the defaults are all pretty "sane" for must use cases. You can see all the options that are supported in the documentation.

import { Microfiber } from 'microfiber'

const introspectionQueryResults = {...}

const microfiber = new Microfiber(introspectionQueryResults)

// ...do some things to your schema with `microfiber`

const cleanedIntrospectonQueryResults = microfiber.getResponse()

// ...do something with your cleaned Introspection Query Results.

Querying Your Schema

It's not always easy to traverse a schema to find what you're looking for, or to check if it exists. Microfiber provides a number of "get" functions that can do this for you with ease. Here are a few examples:

// Get a specific Query from your schema.
const query = microfiber.getQuery({ name: 'users' })

// Get a specific Mutation from your schema.
const mutation = microfiber.getMutation({ name: 'createUser' })

// Get a specific Field from your schema.
const field = microfiber.getField({ typeKind: 'OBJECT', typeName: 'User', fieldName: 'email' })

// Get a specific Arg from your schema.
const arg = microfiber.getArg({ typeKind: 'OBJECT', typeName: 'User', fieldName: 'addresses', argName: 'countryFilter' })

Modifying Your Schema

While querying with your schema is useful, the real power of Microfiber comes with the manipulations that it can perform. For example, you may want to hide a specific Field on a Type:

microfiber.removeField({
  typeKind: 'OBJECT',
  typeName: 'User',
  fieldName: 'email',
})

Or you may want to hide a mutation that you don't want anyone to know exists:

microfiber.removeMutation({
  name: 'deleteUser',
})

Or, perhaps the most useful feature of Microfiber, you may want to remove a Type completely from your schema. That is, not only remove the Type, but also remove any Fields, InputFields, Union Type options, Args, Queries, or Mutations of that Type. This can be tricky to do on your own but is easy with Microfiber:

microfiber.removeType({
  kind: 'OBJECT',
  name: 'SecretType',
})

Additionally, Microfiber can automatically clean things up by—for example—removing all Types from your schema that are not actually used anywhere. This can sometimes occur when you've hidden certain Fields, etc, that reference a Type, but did not explicitly remove that Type yourself.

microfiber.cleanSchema()

You can retrieve your modified schema with ease, and pass it along where you need it to go:

const cleanedResponse = microfiber.getResponse()

Summary

If you're looking for an easy way to query your GraphQL schema—especially in the form of an Introspection Query result—then Microfiber is a great option instead of trying to write your own helpers. However, if you are trying to clean up or modify your schema by hiding things, then Microfiber can really make your life easier. We'll continue to add more features as we identify them, and if you find microfiber helpful (or have questions) please reach out to us at developers@useanvil.com, or swing on by the repo and leave a message. Happy developing!