Documentation

Global

Members

Deferred

Deferred is modeled after jQuery's deferred object. It inverts a promise such that its resolve and reject methods can be invoked without wrapping all of the related code within a Promise's function.

GQLBase

All GraphQL Type objects used in this system are assumed to have extended from this class. An instance of this class can be used to wrap an existing structure if you have one.

GQLExpressMiddleware

A handler that exposes an express middleware function that mounts a GraphQL I/O endpoint. Typical usage follows:

const app = express(); app.use(/.../, new GQLExpressMiddleware([...classes]).middleware);

IDLFileHandler

The handler, an instance of which is created for every instance of GQLBase. The handler manages the fetching and decoding of files bearing the IDL schema associated with the class represented by this instance of GQLBase.

REQ_DATA_KEY

REQ_DATA_KEY a key used for storing requestData

Methods

appendDefinitions(schemaOrASTOrST)

Appends all definitions from another AST to this one. The method will actually create a copy using SyntaxTree.from() so the input types can be any one of a valid GraphQL IDL schema string, a GraphQL IDL AST or another SyntaxTree object instance.

Definitions of the same name but different kinds will be replaced by the new copy. Those of the same kind and name will be merged (TODO handle more than ObjectTypeDefinition kinds when merging; currently other types are overwritten).

Parameters:
Name Type Description
schemaOrASTOrST string | Object | SyntaxTree

an instance of one of the valid types for SyntaxTree.from() that can be used to create or duplicate the source from which to copy definitions.
Returns:

this for inlining

Type
SyntaxTree

constructor(schemaOrASTOrST)

Constructs a new SyntaxTree object. If a string schema is supplied or an already parsed AST object, either of which is valid GraphQL IDL, then its parsed AST will be the internals of this object.

Parameters:
Name Type Description
schemaOrASTOrST string | Object | SyntaxTree

if supplied the tree will be constructed with the contents of the data. If a string of IDL is given, it will be parsed. If an AST is given, it will be verified. If a SyntaxTree is supplied, it will be copied.

constructor(requestData)

Request data is passed to this object when constructed. Typically these objects, and their children, are instantiated by its own static MUTATORS and RESOLVERS. They should contain request specific state if any is to be shared.

These can be considered request specific controllers for the object in question. The base class takes a single object which should contain all the HTTP/S request data and the graphQLParams is provided as the object { query, variables, operationName, raw }.

When used with express-graphql, the requestData object has the format { req, res, gql } where • req is an Express 4.x request object • res is an Express 4.x response object • gql is the graphQLParams object in the format of { query, variables, operationName, raw } See https://github.com/graphql/express-graphql for more info

Parameters:
Name Type Description
requestData Object

see description above

constructor(resolveWith, rejectWith)

Creates an object with four properties of note; promise, resolve, reject and a flag complete that will be set once either resolve or reject have been called. A Deferred is considered to be pending while complete is set to false.

Once constructed, resolve and reject can be called later, at which point, the promise is completed. The promise property is the promise resolved or rejected by the associated properties and can be used with other async/await or Promise based code.

Parameters:
Name Type Description
resolveWith any

a deferred resolved as Promise.resolve() might do
rejectWith any

a deferred rejected as Promise.reject() might do

constructor(instance)

The IDLFileHandler checks the SCHEMA value returned by the class type of the supplied instance. If the resulting value is a Symbol, then the handler's responsibility is to find the file, load it from disk and provide various means of using its contents; i.e. as a Buffer, a String or wrapped in a SyntaxTree instance.

Parameters:
Name Type Description
instance GQLBase

an extended instance or child class of GQLBase

consumeDefinition(astOrSyntaxTree, definitionType)

This method finds the Query type definitions in the supplied AST or SyntaxTree objects, takes its defined fields and adds it to the current instances. If this instance does not have a Query type defined but the supplied object does, then the supplied one is moved over. If neither has a query handler, then nothing happens.

NOTE this removes the Query type definition from the supplied AST or SyntaxTree object.

Parameters:
Name Type Description
astOrSyntaxTree Object | SyntaxTree

a valid GraphQL IDL AST or an instance of SyntaxTree that represents one.
definitionType string | RegExp

a valid search input as would be accepted for the #find() method of this object.
Returns:

returns this for inlining

Type
SyntaxTree

EmptyDocument(schemaOrASTOrST)

The starting point for a SyntaxTree that will be built up programmatically.

Parameters:
Name Type Description
schemaOrASTOrST string | Object | SyntaxTree

any valid type taken by SyntaxTree.from() used to further populate the new empty document
Returns:

an instance of SyntaxTree with no definitions and a kind set to 'Document'

Type
SyntaxTree

EmptyMutation()

Mutation types in GraphQL are an ObjectTypeDefinition of importance for placement on the root object. There is utility in creating an empty one that can be injected with the fields of other GraphQL object mutation entries.

Returns:

an instance of SyntaxTree with a base AST generated by parsing the graph query, "type Mutation {}"

Type
SyntaxTree

EmptyQuery()

Query types in GraphQL are an ObjectTypeDefinition of importance for placement on the root object. There is utility in creating an empty one that can be injected with the fields of other GraphQL object query entries.

Returns:

an instance of SyntaxTree with a base AST generated by parsing the graph query, "type Query {}"

Type
SyntaxTree

find(definitionName)

Iterate through the definitions of the AST if there are any. For each definition the name property's value field is compared to the supplied definitionName. The definitionName can be a string or a regular expression if finer granularity is desired.

Parameters:
Name Type Description
definitionName string | RegExp

a string or regular expression used to match against the definition name field in a given AST.
Returns:

a reference to the internal definition field or null if one with a matching name could not be found.

Type
Object | null

from(mixed)

Given one of, a valid GraphQL IDL schema string, a valid GraphQL AST or an instance of SyntaxTree, the static from() method will create a new instance of the SyntaxTree with the values you provide.

Parameters:
Name Type Description
mixed String | Object | SyntaxTree

an instance of one of the valid types specified above. Everything else will result in a null value.
Returns:

a newly created and populated instance of SyntaxTree or null if an invalid type was supplied for mixed.

Type
SyntaxTree

fromAST(ast)

Generates a new instance of SyntaxTree from the supplied, valid, GraphQL schema. This method does not perform try/catch validation and if an invalid GraphQL schema is supplied an error will be thrown.

Parameters:
Name Type Description
ast object

a valid GraphQL AST object.
Returns:

a new instance of SyntaxTree initialized with a supplied abstract syntax tree generated by require('graphql').parse() or other compatible method.

Type
SyntaxTree

fromSchema(schema)

Generates a new instance of SyntaxTree from the supplied, valid, GraphQL schema. This method does not perform try/catch validation and if an invalid GraphQL schema is supplied an error will be thrown.

Parameters:
Name Type Description
schema string

a valid GraphQL IDL schema string.
Returns:

a new instance of SyntaxTree initialized with a parsed response from require('graphql').parse().

Type
SyntaxTree

IDLFilePath(path [, extension])

Creates an appropriate Symbol crafted with the right data for use by the IDLFileHandler class below.

Parameters:
Name Type Argument Default Description
path string

a path to the IDL containing file
extension String <optional>
 '.graphql'

an extension, including the prefixed period, that will be added to the supplied path should it not already exist.
See:
  • get SCHEMA()
Returns:

Symbol

makeRoot(req, res, gql)

An asynchronous function used to parse the supplied classes for each ones resolvers and mutators. These are all combined into a single root object passed to express-graphql.

Parameters:
Name Type Description
req Request

an Express 4.x request object
res Response

an Express 4.x response object
gql Object

an object containing information about the graphql request. It has the format of { query, variables, operationName, raw } as described here: https://github.com/graphql/express-graphql
Returns:

a Promise resolving to an Object containing all the functions described in both Query and Mutation types.

Type
Promise.<Object>

makeSchema()

A function that combines the IDL schemas of all the supplied classes and returns that value to the middleware getter.

Returns:

a dynamically generated GraphQL IDL schema string

Type
string

middleware()

Using the express-graphql module, it returns an Express 4.x middleware function.

Returns:

a function that expects request, response and next parameters as all Express middleware functions.

Type
function

MUTATORS(requestData)

This method should return a promise that resolves to an object of functions matching the names of the mutation operations. These are to be injected into the root object when used by GQLExpressMiddleware.

Parameters:
Name Type Description
requestData Object

typically an object containing three properties; {req, res, gql}
Returns:

a promise that resolves to an object; see above for more information.

Type
Promise

pending()

Shorthand getter that denotes true if the deferred is not yet complete.

Returns:

true if the promise is not yet complete; false otherwise

Type
boolean

RESOLVERS(requestData)

This method should return a promise that resolves to an object of functions matching the names of the query operations. These are to be injected into the root object when used by GQLExpressMiddleware.

Parameters:
Name Type Description
requestData Object

typically an object containing three properties; {req, res, gql}
Returns:

a promise that resolves to an object; see above for more information.

Type
Promise

setAST(schemaOrAST)

Sets the underlying AST object with either schema which will be parsed into a valid AST or an existing AST. Previous ast values will be erased.

Parameters:
Name Type Description
schemaOrAST string | Object

a valid GraphQL IDL schema or a previosuly parsed or compatible GraphQL IDL AST object.
Returns:

this for inlining.

Type
SyntaxTree

toString()

SyntaxTree instances that are toString()'ed will have the graphql method print() called on them to convert their internal structures back to a GraphQL IDL schema syntax. If the object is in an invalid state, it WILL throw an error.

Returns:

the AST for the tree parsed back into a string

Type
string

typeOf(object)

One common way to determine the type of class that you are working with, in a fairly compatible manner, is to use .call or .apply on the function toString of the Object.prototype.

Calling Object.prototype.toString.call('hello') will yield "[object String]" as an answer. This technique is fairly sound but is also fairly verbose to use often. This function extracts the detected value name from the above string; so "String" from "[object String]" and so forth.

The added advantage of using this method is that it works well with direct name comparisons, such as typeOf("asdfas") === String.name. The new Symbol.toStringTag allows you to define custom values that are reflected in this manner.

Parameters:
Name Type Description
object any

any value is acceptable here, including null and undefined
Returns:

for objects of type [object String] the value "String" will be returned.

Type
string

updateAST(ast)

As passthru update method that works on the internal AST object. If an error occurs, the update is skipped. An error can occur if adding the changes would make the AST invalid. In such a case, the error is logged to the error console.

Parameters:
Name Type Description
ast Object

an existing GraphQL IDL AST object that will be merged on top of the existing tree using Object.assign()
Returns:

this for inlining.

Type
SyntaxTree