ne-schemata

GraphQL IDL/Schemata String class to make working with GraphQL easier

NOTE!!

Henceforth, this library will be called @nyteshade/ne-schemata. Please this npm library will not be maintained on this name after this release.

Overview

Working with Schemata (Schema Definition Language), sometimes called IDL (Interface Definition Language) can occasionally be difficult. A schema definition is the most concise way to specify a schema in GraphQL.

Classes in programming languages are data structures that associated properties and functions designed to work with them. The provided Schemata class extends String and should be able to be used in most places in JavaScript where strings are used with no changes. This, however, is where things change.

Some of the most often applied tasks with SDL are building a schema object, building an executable schema object, parsing it into ASTNode objects. Occasionally a given bit of SDL is checked for validity.

The Schemata class does all this and more.

Features

Biggest selling points of working with the Schemata class

Creation of bound or non-bound GraphQLSchema and ASTNode object
Storage of an associated resolvers map
Storage of an associated schema object for iteration and modification
Checking of the validity of SDL as a ASTNode as well as a GraphQLSchema
Merge SDL together via AST parsing
Merge multple GraphQLSchemas via AST parsing
Pare down one SDL/Schema using another as a guide

Recent Breaking Changes

4.0.0

The package has been renamed to @nejs/schemata in coordination with several projects. Reliance on flow-type has been removed in favor of using pure JavaScript with types documeted in jsdoc comment blocks.

2.4.0, 2.4.1 -> 3.0.1

2.4.0 and 2.4.1 are both actually breaking changes. Tests have been updated and version updated appropriately for 3.0.0. The breaking changes are as follows:

// Previously
let schemata = gql`type Query { name: String }` // -> Schemata instance

// Currently
let ast = gql`type Query { name: String }` // -> Proxy(ASTNode) with access to Schemata

The gql template string function no returns an AST node as is inline with with Apollo GraphQL's implementation of a template string with the same name. This allows compatibility to be increased.

The returned AST object is wrapped in a Proxy instance allowing access to schemata instance properties, a string and schemata property accessor that provide access to a String representation of the SDL and the instance of Schemata that represents the templated string

The Proxy instance allows direct access to any Schemata instance property that does not directly conflict with a AST node property of the same name. If the AST node property conflicts, access will be limited to ast.schemata.property where ast is the result of calling gql and property is the desired conflicting property.

New Changes

You can now require files with .graphql, .gql, and .sdl extensions. If found, the contents of the file will be used as parameters for a call to new Schemata(). Various obvious aspects of the file can be imported specifically as follows

  astNode   - an ASTNode document object representing the SDL contents
              of the .graphql file contents. Null if the text is invalid
  resovlers - if there is an adjacent file with the same name, ending in
              .js and it exports either a `resolvers` key or an object by
              default, this value will be set on the sdl object as its set
              resolvers/rootObj
  schema    - a GraphQLSchema instance object if the contents of the .graphql
              file represent both valid SDL and contain at least one root
              type such as Query, Mutation or Subscription
  sdl       - the string of SDL wrapped in an instance of Schemata
  typeDefs  - the raw string used that `sdl` wraps
  default   - the sdl string wrapped in an instance of Schemata is the
              default export

Notably, in 3.x and onward, if one of these extensions is require'd, and adjacent to the file is a .js file with the same name, its contents (or .resolvers if present) will be used as the resolvers for the generated Schemata instance.

Installation

Simply npm or yarn install the package

/Volumes/harddrive/path/to/your/project
$ npm install --save ne-schemata

Usage

Using `new`

Creating instances of Schemata can of course be done with typical JavaScript via the new keyword.

let schemata = new Schemata(
  'type Person { name: String } type Query { peep: Person }'
)

Using `Schemata.from`

Creating instances of Schemata can also be done with a constant on the class itself called .from().

let schemata = Schemata.from(
  'type Person { name: String } type Query { peep: Person }'
)

From an existing instance of Schemata

Creating instances of Schemata from other instances of Schemata is also supported. In these cases, all the set values of note will be moved over. This includes schema and resolvers set on the original instance.

let sdlA = Schemata.from(
  'type Person { name: String } type Query { peep: Person }',
  {
    Query: {
      peep() {
        return { name: 'Brielle' }
      },
    },
  }
)
let sdlB = Schemata.from(sdlA)

console.log(sdlB.resolvers) // { Query: { peep: [function peep()] } }

From an instance of GraphQLSchema

You can also create a Schemata instance from an existing instance of GraphQLSchema. The typeDefs or SDL string will be generated using printSchema() from the base graphql module. The .schema value will be set explicitly to the value supplied in the case it is executable or has had other modifications performed on it.

import { makeRemoteExecutableSchema, introspectSchema } from 'graphql-tools';
import { HttpLink } from 'apollo-link-http';
import fetch from 'node-fetch';

let link = new HttpLink({ uri: 'some uri', fetch })
let schema = makeRemoteExecutableSchema(await introspectSchema(link), link)
let schemata = new Schemata(schema) // or Schemata.from(schema)

console.log(schemata) // the SDL from the remote schema

Using the `gql` template function

Alternatively, creating a Schemata string instance can be done using the gql template function. The function was named as many popular editors have a syntax highlighting theme that highlights GraphQL SDL. It seemed to make a lot of sense to add the resulting string from this as an instance of Schemata

import { gql } from 'ne-schemata'

let schemata = gql`
  type Person {
    name: String
  }

  type Query {
    peep: Person
  }
`

let schema = schemata.schema

SDL or typeDefs with `extend type`

SDL or typeDefs with extend type in them will honored and types will be extended as directed by the SDL. Calling .sdl or .typeDefs will contain the extend type SDL. .schema will return a GraphQLSchema object with the types properly extended however. To modify and update the internal SDL, call .flattenSDL(). This will regenerate the SDL on the instance. If, instead, you simply wish to see what the flattened SDL string looks like without modifying the instance, this can be found by accessing the .flatSDL property.

// Create instance with extend type in SDL
let schemata = gql`type User { name: String } extend type User { age: Int }`

console.log(schemata)
// Prints
// type User { name: String } extend type User { age: Int }

console.log(schemata.flatSDL)
// Prints
// type User {
//   name: String
//   age: Int
// }

schemata.flattenSDL()
console.log(schemata)
// Prints
// type User {
//   name: String
//   age: Int
// }

Using require('file.graphql') with require extensions

The final way to create new instances of Schemata in a helpful and unobtrusive manner is to use the '.graphql' extension handler. This handler registers the '.graphql' extension with the require() function in your local nodeJS environment.

Once registered, require() and import {} from will now do several interesting things with '.graphql' imported text. First the resulting exported object has 5 different keys, with the default being a Schemata string wrapping the contents of the file itself.

The five exports of imported '.graphql' files are:

astNode an ASTNode object representing the parsed contents of the file
resolvers if there is an adjacent .js file of the same name, and if that file exports 'resolvers' or if the exported results are an object and not a function, then that object is considered to be a resolvers map for the associated .graphql file.
schema generated from the contents of the Schemata string. If the resolvers object was successfully generated and imported, this will be an executableSchema instead.
sdl the Schemata string instance, also the default export
typeDefs keeping in line and adding compatibility with Apollo Server, the typeDefs export is simply a synonym for sdl.

How do you use the extension? Somewhere, typically early on in the project entry script, make a call to register() and then subsequently import/require your '.graphql' files.

require('ne-schemata/register')

import { sdl, schema, resolvers } from './graphql/Person.graphql'

// or alternatively
require('ne-schemata').register('graphql') // or simply register() as .graphql is the default

import { sdl, schema, resolvers } from './graphql/Person.graphql'

Schemata Merging (both strings and GraphQLSchema objects)

AST merging of multiple SDL files and resolver maps. This will allow you to do something like the following. Merging schemas is just as easy. A new instance of GraphQLSchema will be created and stored on the instance but the pre-existing resolvers will be deeply merged with the supplied resolvers on the schema to be merged and all will be applied and bound to the newly generated schema.

import graphqlHTTP from 'express-graphql'
import Express from 'express'
import { gql } from 'ne-schemata'

const app = Express()
const sdlA = gql`
  type Person {
    name: String
  }

  type Query {
    peep: Person
  }
`
const sdlB = gql`
  type Person {
    age: Int
  }

  type Query {
    peeps: [Person]
  }
`
const sdlC = sdlA.mergeSDL(sdlB)

/*
sdlC.schema would evaluate to something like the following:

type Person {
  name: String
  age: Int
}

type Query {
  peep: Person
  peeps: [Person]
}
*/

app.use(
  '/graphql',
  graphqlHTTP({
    schema: sdlC.schema,
    graphiql: true,
  })
)

app.listen(4000)

Merging Concerns

TLDR; Schemata has your back and you don't really need to read this

Still here? Cool, let's learn what happens during merging. When merging multiple schemas, one of the problems that can occur, especially if one of the schemas being merged is a remote executable schema, is that the resolvers might be bound to an older version of a schema that is only a subset of the new merge.

Schemata helps to alleviate this problem by introducing a few interfaces of note. The immediate solution to this problem is to wrap the resolvers and have those resolvers point to a newly merged GraphQLSchema object rather than the one it was originally bound to.

The problem comes in when you try to merge more than once. Wrapping a previously wrapped version of a resolver will allow you to set it at the top, but the previous attempt to do will execute and override the changes you just made.

Schemata solves this problem by storing the older unbound methods with each bind. A reference to the schema, sdl and resolvers at the time of the merge are kept. When each subsequent merge occurs, these older unwrapped/unbound resolvers are used to apply the new schema rather than layering things like Russian nesting dolls.

Furthermore, when making a call to .mergeSchema() you may add your own resolver injectors which are simply objects containing a property called '.resolverInjectors' which are an array of ResolverArgsTransformer functions. These give you full acceess to the source, args, context and info parameters to modify to your hearts content before the original unwrapped resolver receives those parameters.

import { Schemata } from 'ne-schemata'

let a = Schemata.from('type Query { me: String }', {
  me(s, a, c, i) {
    return 'Brielle'
  },
})

let b = Schemata.from('type Query { her: String }', {
  her(s, a, c, i) {
    return 'Stacy'
  },
})

let ab = a.mergeSchema(b)

console.log(ab.prevMergeResolvers)
// [{schema:..., sdl:..., resolvers:...}, ...] <-- unwrapped
console.log(ab.resolvers)
// { me(), her() }     <-- wrapped to new schema

let c = Schemata.from('type Polygon { sides: Int }', {
  Polygon: {
    sides(s, a, c, i) {
      return 6
    },
  },
})

let abc = ab.mergeSchema(c)
console.log(abc.prevMergeResolvers)
// [{schema:..., sdl:..., resolvers:...}, ...] <-- unwrapped
console.log(abc.resolvers)
// { me(), her(), Polygon: { sides() } } <-- wrapped to new schema

Even this example has difficulty explaining properly what is happening and why it's important, but as each merge happens the previous unwrapped resolvers are passed along and newly introduced schemas' resolvers are added to this list.

Schemata Class Properties and Methods

Constructor
Instance properties
- .ast: ?ASTNode
- .executableSchema: ?GraphQLSchema
- .flatSDL: string
- .graphiql: boolean
- .hasAnExecutableSchema: boolean
- .hasFlattenedResolvers: boolean
- .prevResolverMaps: Array<ExtendedResolverMap>
- .resolvers: ?ResolverMap
- .rootValue: ?ResolverMap
- .schema: ?GraphQLSchema
- .schemaDirectives: Object
- .schemaDirectives: Object
- .sdl: string
- .typeDefs: string
- .types: Object
- .valid: boolean
- .validSchema: boolean
- .validSDL: boolean
Instance methods
Static properties
- .ALL:Number
- .ENUMS:Number
- .gql:Module
- .HIDDEN:Number
- .INPUT_TYPES:Number
- .INTERFACES:Number
- .ROOT_TYPES:Number
- .SCALARS:Number
- .TYPES:Number
- .UNIONS:Number
Symbols
Static methods
Exported types
External Functions
Default Functions
Additional Goodies
- asyncWalkResolverMap
- at
- atNicely
- gql
- register
- walkResolverMap

Constructor ✯

constructor(
  typeDefs: SchemaSource,
  resolvers: ResolverMap = null,
  buildResolvers: boolean | string = false,
  flattenResolvers: boolean = false
): Schemata

Schemata instances are versatile and can be created through a variety of sources. Typically anything that can be converted to a string of SDL can be used to create a new Schemata instance. Everything from a GraphQL Source instance, previously instantiated Schemata instance, a GraphQLSchema object or even an ASTNode. Of course, basic strings of SDL can also be used.

An object with resolver functions can be supplied as the second parameter allowing executable schemas to be generated from the source SDL.

The final two parameters are for the case where the Schemata instance is initialized with a GraphQLSchema instance or with an older instance of Schemata.

The first causes a programmatic attempt to generate and set an object containing resolvers from the executable schema represented by either eligible object. If the string 'all' is supplied than a resolver for each field not defined will receive GraphQL's defaultFieldResolver as its resolver.
The second causes the generated resolver map to be in the flattened style with root fields exposed at the root of the resolver map. By default the Apollo style resolver map with fields under their respective type names is the default

Instance properties ✯

.ast ✯

generates ASTNodes that the internal string would generate when passed to require('graphql').parse()

.schema ✯

retrieves any internally stored GraphQLSchema instance generated thus far; if one does not exist, one will be generated sets the value of the internal GraphQLSchema storage variable

.executableSchema ✯

retrieves the internally stored executable schema, if one exists, or it creates one if the .resolvers value has been set and if there is valid .sdl. This getter is now deprecated. All functionality has been integrated in the single .schema property without any loss of functionality. Please use that instead.

.flatSDL ✯

working from the built in .schema GraphQLSchema instance, SDL is regenerated and printed. Any extend type declarations applied to the schema instance will be merged and only the single type will be shown. This will return a string of SDL but the instance will not be modified in the process.

.graphiql ✯

retrieves the .graphiql flag which defaults to true. This might be used by express-graphql. Schemata does not use this flag internally, but rather stores it as a convenience property.
sets the internal graphiql flag to a value other than true. Remember that this field is not used internally by Schemata other than storage and retrieval.

.hasAnExecutableSchema ✯

A getter to determine if an executable schema is attached to this Schemata instance. It does so by walking the schema fields via buildResolvers() and reporting whether there is anything inside the results or not.

.hasFlattenedResolvers ✯

Determines if the internal resolver map has at least one defined root type resolver (Query, Mutation, Subscription) or not. If not, including if there are no root resolvers (yet), this property will evaluate to false

.prevResolverMaps ✯

When a Schemata instance is merged with another GraphQLSchema, its resolvers get stored before they are wrapped in a function that updates the schema object it receives. This allows them to be wrapped safely at a later date should this instance be merged with another.

retrieves any internally stored resolver maps sets the internally stored resolver maps

.schemaDirectives ✯

Schemata is designed to be used with various GraphQL JavaScript engines. In many cases, it is simply used as a variable to store configuration for more specific calls to things like makeExecutableSchema from graphql-tools or GraphQLServer and the like. For more information on Apollo's usage of this property, see this page: https://www.apollographql.com/docs/graphql-tools/schema-directives.html

An object containing the name to function mapping for schema directive classes when used with apollo-server or graphql-yoga.

Internally sets the instance variable for the schemaDirectives object used with apollo-server or graphql-yoga

.sdl ✯

the same value as the string this instance represents

.types ✯

calculates a JavaScript object based on the schema where type names are sub-objects, and their keys are field names with values containing objects with two keys. Those keys are type and args. The type field will evaluate to the SDL type of the field in question and the args field will evaluate to an order specific set of objects with an argument name key and SDL argument type value.

For clarity, given a schema such as the following:

type A {
  a: String
  b: [String]
  c: [String]!
}
type Query {
  As(name: String): [A]
}

One can expect a return type like this:

{
  Query: {
    As: { type: '[A]', args: [ { name: 'String' } ] }
  },
  A: {
    a: { type: 'String', args: [] },
    b: { type: '[String]', args: [] },
    c: { type: '[String]!', args: [] }
  }
}

.typeDefs ✯

a synonym for .schemata, ideal for use with Apollo and other librariees that expect this nomenclature

.rootValue ✯

a synonym for .resolvers, ideal for use with express-graphql or other libraries that expect this nomenclature. Note: that the format of this object is slightly different for Apollo than the Facebook reference implementation

.resolvers ✯

retrieves any internally store resolvers map sets the internally stored resolvers map

.validSDL ✯

if the SDL this string represents can be parsed without error, true will be returned; false otherwise

.validSchema ✯

if the SDL this string represents can be used to build a schema without error, true will be returned; false otherwise

.valid ✯

returns true if both .validSDL and .validSchema are both true

Instance methods ✯

astFieldByName ✯

astFieldByName(type: string, field: string): FieldNode

For SDL that doesn't properly build into a GraphQLSchema, it can still be searched for a type and field.

astTypeByName ✯

astTypeByName(type: string): ASTNode

For SDL that doesn't properly build into a GraphQLSchema, it can still be parsed and searched for a type by name.

buildResolvers ✯

buildResolvers(
  flattenRootResolversOrFirstParam: boolean | ResolverMap,
  ...extendWith: Array<ResolverMap>
): ResolverMap

In the case where Schemata instance was created with a GraphQLSchema, especially one that is an executableSchema or somehow has resolvers in it already, buildResolvers() will walk the schema fields and build up a resolvers object of those resolve() functions on each field. If true is supplied as the first parameter, the resolver functions from Query, Mutation and Subscription will appear in the root of the returned object rather than under their aforementioned parent types.

buildResolverForEachField ✯

buildResolverForEachField(
  flattenRootResolversOrFirstParam: boolean | ResolverMap,
  ...extendWith: Array<ResolverMap>
): ResolverMap

From time to time it makes more sense to wrap every possible resolver mapping in given schema. Getting a handle to each fields resolver and or substituting missing ones with GraphQL's defaultFieldResolver can be a tiresome affair. This method walks the schema for you and returns any previously defined resolvers alongside defaultFieldResolvers for each possible field of every type in the schema.

If a schema cannot be generated from the SDL represented by the instance of Schemata, then an error is thrown.

clearResolvers ✯

clearResolvers()

Removes any existing .resolvers map that might have been assigned to the object instance. This is identical to calling .resolvers = null, and only exists here as a semantic method that may have future functionality added to it.

clearResolvers ✯

clearSchema()

Removes any existing .schema GraphQLSchema instance that might have been assigned to the object instance. This is identical to calling .schema = null, and only exists here as a semantic method that may have future functionality added to it.

flattenSDL ✯

flattenSDL()

Working from the built in .schema GraphQLSchema instance, SDL is regenerated and printed. Any extend type declarations applied to the schema instance will be merged and only the single type will be shown. The internal typeDefs will be modified after this call and subsequent calls to .ast, .schema, .sdl, or .typeDefs will no longer have the extend type directives listed.

forEachOf ✯

forEachOf(
  fn: ForEachOfResolver,
  context: unknown,
  types: number = Schemata.TYPES,
  suppliedSchema: ?GraphQLSchema = null
): GraphQLSchema

Iterates over the type map of either the internal schema or one created from the SDL string this instance represents and then stored for later use. See above for the definition of the ForEachOfResolver callback signature. types is a bitmask made up of at least one of the constant properties on Schemata such as Schemata.ALL or Schemata.TYPES and optionally augmented with Schemata.HIDDEN