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