Graphql-birdseye-core NPM

Description

Birdseye is an interactive tool that dynamically displays GraphQL schemas. It helps teams visualize and understand the nodes and connections within their schema. Birdseye was built using jointJS and makes for a lightweight addition to any web project.

Features

Graphical view of any GraphQL schema
Ability to click on a field or type to view its connections
Dynamic zooming to focus on small portions of the schema at a time
Add to any web project
Customizable styling and theming

Javascript Library Documentation

This is the documentation to use Birdseye as a Javascript library. To learn how to use Birdseye as a React package, please refer to the React repository README.

Installation

Install using NPM or yarn

NPM

npm install --save graphql-birdseye-core

Yarn

yarn add graphql-birdseye-core

Usage

Here’s an example of how to use the Birdseye Javascript library in a React project. See the API Reference for how to pass your schema to the component.

import {
  GraphqlBirdseye,
  IntrospectionDataStructure,
} from "graphql-birdseye-core";
import $ from "jquery";
// Instantiate the library
const birdseye = new GraphqlBirdseye();

// define the data structure
const introspectionQuery = getSchemaIntrospection(); // get the introspection response from the schema
const dataStructure = new IntrospectionDataStructure(
  introspectionQuery.__schema
);

// Initialize the library
birdseye.init(
  $("#graphql-birdseye"), // the html div element to mount the library to.
  { width: 500, height: 500 }, // object to define the size of the container
  dataStructure
);

API

`const birdseye = new GraphqlBirdseye({ theme })`

Creates a Birdseye object.

Name	Type	Description
theme (optional)	object	An object defining the theme of the components. Theme objects should follow the type defined here. Here's a full example.

`init(el, bounds, dataStructure)`

Initializes the Birdseye diagram with the GraphQL schema to display, the DOM element to attach it to, and its size.

Name	Type	Description
`el`	HTML DOM Element	The HTML element on which to mount the Birdseye diagram.
`bounds`	object	The height and width of the diagram.`width`: Int`height`: Int
`dataStructure`	BirdseyeDataStructure	The GraphQL schema to display, expressed as a Birdseye Data Structure. Read more about Birdseye Data Structures below.

`setDataStructure(newDataStructure)`

Updates the GraphQL schema displayed in the Birdseye diagram.

Name	Type	Description
`newDataStructure`	BirdseyeDataStructure	The GraphQL schema to display, expressed as a Birdseye Data Structure. Read more about Birdseye Data Structure below.

`setActiveType(activeType)`

Changes the active type selected on the diagram. This function fires whenever a type is clicked, but it can also be used to change the active type manually.

Name	Type	Description
`activeType`	String	The `name` value of the `Type` object from the Birdseye Data Structure.

`setSize(width, height)`

Updates the width and height of the Birdseye diagram.

Name	Type	Description
`width`	int	The width of the diagram.
`height`	int	The height of the diagram.

`on(event, callback)`

Invokes a function when a type is clicked and the diagram is loading. It can invoke a function when the loading begins or when the loading ends.

Name	Type	Description
`event`	String	Use either:`"loading:start""loading:stop"`
`callback`	() => any	The function that will be invoked when the event triggers.

BirdseyeDataStructure

Birdseye accepts GraphQL schemas defined in the Birdseye Data Structure. We chose to specify our own data structure because GraphQL schemas can be represented in various formats (i.e. introspection response, GraphQL Schema Object, etc.). Birdseye ships with two translators to create Birdseye Data Structures.

introspectionConverter: Converts the response of an introspection query into a Birdseye Data Structure. Use the response from this introspection query with this converter.
schemaConverter: Converts a GraphQL Schema Object into a Birdseye Data Structure. You can use the ExecutableSchema from GraphQL tools to create a GrapahQL Schema Object.

Roadmap

We have plans to keep improving Birdseye. Here's what is next: 1. Improve performance for larger schemas 2. Option to toggle zoom navigation style 3. Smoother UI transitions and interactions