graphql-server.node.txt

                                  ┏━━━━━━━━━━━━━━━━━━━━┓
                                  ┃   GRAPHQL-SERVER   ┃
                                  ┗━━━━━━━━━━━━━━━━━━━━┛

ALTERNATIVES ==>                  #Middleware that performs GraphQL query (using GraphQL.js) then sends the JSON result back
                                  #Can display GraphiQL
                                  #Can use:
                                  #  - express-graphql, koa-graphql: 
                                  #     - displays GraphiQL according to Accept [C], for a single route
                                  #     - Express|Koa only
                                  #     - does REQ.body|query parsing
                                  #     - allow several way of passing query (body, query variables)
                                  #  - graphql-server:
                                  #     - displays GraphiQL according to route
                                  #     - framework-agnostic, with built-in support for Express, AWS Lambda, Koa, Restify, Hapi
                                  #     - let consumer do their own REQ.body|query parsing
                                  #     - stricter way of passing query (body, query variables)
                                  #     - has logging utilities
                                  #Prefer graphql-server

VERSION ==>                       #0.5.1


runHttpQuery                      #Does graphql(...), using:
(ARG_ARR, OPTS[(ARG...)])         #  - OPTS.options: schema, context, rootValue
->PROMISE_'RESP_JSON'             #  - OPTS.query 'QUERY' or OBJ[_ARR]: query 'QUERY', variables, operationName 
                                  #ARG_ARR is used as argument to OPTS[(ARGS...)]
                                  #OPTS.method 'GET|POST':
                                  #  - request method.
                                  #  - if 'GET', forces operation to be 'query' not 'mutation'
                                  #OPTS.options:
                                  #  - validationRules OBJ_ARR: extra rules passed to GraphQL.js validate()
                                  #  - formatParams(OOPTS)->OOPTS: transform function
                                  #  - formatResponse(OBJ, OOPTS)->OBJ: transform function for query response
                                  #  - formatError(ERROR)->ERROR: transform function (def: only keeps message|locations|path)
                                  #  - logFunction(OBJ): for debugging with OBJ: 
                                  #     - action 'request|parse|validation|execute', step 'start|end|status'
                                  #     - ('request' + 'status' only) key 'query|variables|operationName', data OBJ
                                  #  - debug BOOL (def: false if NODE_ENV 'production|test'): console.error() each ERROR.stack
                                  #OOPTS: OPTS.options + query|variables|operationName
                                  #Errors can come either from:
                                  #  - graphql-server:
                                  #     - reject PROMISE with ERROR:
                                  #        - name 'HttpQueryError'
                                  #        - statusCode NUM
                                  #        - message STR
                                  #        - isGraphQLError true
                                  #     - not affected by formatError()
                                  #     - causes:
                                  #        - not GET|POST -> 405 with Allow: GET, POST [S]
                                  #        - GET but doing mutation|subscription -> 405 with Allow: POST [S]
                                  #        - wrong input -> 400
                                  #        - no return value data, but return value errors -> 400, 
                                  #          with OBJ.errors GRAPHQLERROR_ARR
                                  #        - validation error -> 400, with OBJ.errors GRAPHQLERROR_ARR as JSON in ERROR.message
                                  #        - others -> 500
                                  #  - underlying graphql.js throws: 
                                  #     - resolve PROMISE with { errors GRAPHQLERROR_ARR }
                                  #  - underlying graphql.js returns { errors GRAPHQLERROR_ARR }: like validation error above
                                  #I.e. can either:
                                  #  - reject PROMISE with ERROR, either
                                  #     - message STR
                                  #     - message 'JSON' (GRAPHQLERROR_ARR): validation error or resolver error
                                  #  - resolve PROMISE with { errors GRAPHQLERROR_ARR }: graphql.js error (apart from resolver)

graphqlExpress(OPTS)->MIDWR       #Express MIDWR that fires runHttpQuery([REQ, RES], OPTS):
                                  #  - using REQ.body (if 'POST') or REQ.query (if 'GET')
                                  #  - then RES.end() as JSON

renderGraphiQL(OPTS)->'HTML'      #Returns HTML document:
                                  #  - renders <GraphiQL> component in <body>
                                  #  - autofills props: fetcher (using fetch polyfill) (can add OPTS.passHeader 'HEADERS')
                                  #  - keep URL in sync with query|variables|operationName
                                  #  - autofills OPTS.query|variables|operationName|response
                                  #OPTS: endpointUrl 'URL'
graphiqlExpress(OPTS)->MIDWR      #Express MIDWR that returns renderGraphiQL(OPTS) with RES.end()
                                  #Can pass OPTS.query|variables|operationName with REQ.query as well


graphqlLambda(OPTS)->FUNC         #Same as for Express, but using a AWS Lambda FUNC(EVENT, LAMBDACONTEXT, FUNC2(ERROR, OBJ))
graphiqlLambda(OPTS)->FUNC        #Uses EVENT.body|queryStringParameters|httpMethod


OTHER MODULES ==>                 #For Koa, Restify, Hapi