graphql_tools.graphqljs.txt

                 
   GRAPHQL_TOOLS  
                 



VERSION ==>                       #0.10.1

GOAL ==>                          #Three different tools:
                                  #  - makeExecutableSchema(): enhancement of GraphQL.js buildSchema() where:
                                  #     - can specify resolvers, resolveType(), isTypeOf(), serialize|parseValue|parseLiteral()
                                  #     - can validate all resolvers are specified, and do not return undefined
                                  #     - can log errors with custom function (instead of just being output in return value)
                                  #     - understands "extend type ..."
                                  #  - mocking resolvers, for unit tests
                                  #  - automatically calling PUBSUB.publish(), with graphql-subscriptions (documented in that doc instead)


                                             /=+===============================+=\
                                            /  :                               :  \
                                            )==:          DEFINITIONS          :==(
                                            \  :_______________________________:  /
                                             \=+===============================+=/


makeExecutableSchema(OPTS)->SCHEMA#OPTS:
                                  #  - typeDefs 'DEFINITIONS'[()][_ARR]: passed to buildSchemaFromTypeDefinitions()
                                  #  - resolvers RESOLVERS:
                                  #     - passed to addResolveFunctionToSchema()
                                  #     - if RESOLVERS.__schema(...), passed as RESOLVER to addSchemaLevelResolveFunction()
                                  #  - resolverValidationOptions OBJ: passed to assertResolveFunctionsPresent()
                                  #  - allowUndefinedInResolve BOOL (def: true): if false, uses addCatchUndefinedToSchema()
                                  #  - logger LOGGER: if defined, uses addErrorLoggingToSchema()

buildSchemaFromTypeDefinitions    #Like GraphQL.js buildSchema() except:
('DEFINITIONS'[()][_ARR])->SCHEMA #  - understands "extend type ..."
                                  #  - 'DEFINITIONS' can be function and|or ARR

addResolveFunctionToSchema        #RESOLVERS.TYPE:
(SCHEMA, RESOLVERS)               #  - ATTR[.resolve](...): updates TYPE resolve(...)
                                  #  - __resolveType(...), __isTypeOf(...): updates TYPE
                                  #  - SCALARTYPE: creates SCALARTYPE
                                  #  - serialize|parseValue|parseLiteral(...): updates SCALARTYPE

addSchemaLevelResolveFunction     #Wraps top-level operation resolver with another resolver
(SCHEMA, RESOLVER(...))           #Only called once per request, except if OPTYPE is "subcription"
                                  #Useful for general middleware like authentication

assertResolveFunctionsPresent     #Validate that resolver functions are present.
(SCHEMA[, OPTS])                  #Throws SchemaError otherwise.
                                  #OPTS:
                                  #  (either)
                                  #  - requireResolversForAllFields BOOL (def: false)
                                  #  (or)
                                  #  - requireResolversForArgs BOOL (def: false)
                                  #  - requireResolversForNonScalar BOOL (def: false)

addCatchUndefinedToSchema(SCHEMA) #Wraps each resolve function, so that an exception is throw if it returns undefined

addErrorLoggingToSchema           #Wraps each resolve function, so that thrown exceptions or failed PROMISE call LOGGER.log()
(SCHEMA, LOGGER)                  #LOGGER is OBJ with log(STR|ERROR)
                                  #ERROR is augmented with ERROR.stack


chainResolvers(RESOLVER_ARR)
 ->RESOLVER                       #Returns a RESOLVER that chain each RESOLVER in turn (similar to _.compose)

RESINFO                           #Warning: RESINFO not passed as argument to default resolver, if using chainResolvers() or wraping resolve function


                                             /=+===============================+=\
                                            /  :                               :  \
                                            )==:            MOCKING            :==(
                                            \  :_______________________________:  /
                                             \=+===============================+=/


mockServer                        #Calls addMockFunctionsToSchema(), then returns OBJ:
(SCHEMA,MOCKS[,PRESERVERESOLVERS])#  - query('QUERY', VARIABLES): fires graphql(SCHEMA, 'QUERY', {}, {}, VARIABLES)
mockServer('DEFINITION'[()][_ARR])#Same but calls buildSchemaFromTypeDefinitions()

addMockFunctionsToSchema(OPTS)    #Mock resolvers, according to their return TYPE, so that it returns:
                                  #  1) (similar to default resolver) RPARENT.ATTR[(...)], if defined (potentially merged with 2))
                                  #      - RPARENT can be new MockList(NUM[_ARR]) if meant to be OBJ_ARR
                                  #         - NUM is length, NUM_ARR is min|max length (pick random one)
                                  #  2) (TYPE custom resolver) mocks.TYPE RESOLVER return value, if defined
                                  #  3) (TYPE default resolver) dummy value according to return TYPE:
                                  #      - OBJTYPE -> {}
                                  #      - UNIONTYPE|INTERFACETYPE -> random OBJTYPE from possible ones
                                  #      - ENUMTYPE -> random ENUM_VAL
                                  #      - INT|FLOAT -> random between [-100,100]
                                  #      - STR -> "Hello world"
                                  #      - BOOL -> random
                                  #      - ID -> UUIDv4
                                  #OPTS:
                                  #  - schema SCHEMA
                                  #  - mocks.TYPE RESOLVER
                                  #  - preserveResolvers BOOL (def: false): keep original resolver, and merge mock values to it