# 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

#### Search results