Package @occupop/lib-graphql

This package is intended to be used with @occupop/lib-container being a wrapper for Apollo Server, providing factory for server and some helpers.

This implementation refers to https://www.apollographql.com/docs/apollo-server! Check their docs for detailed/advanced usage.

NPM registry token required!

Install

# Yarn
yarn add @occupop/lib-graphql

# NPM
npm install @occupop/lib-graphql

# Bun
bun add @occupop/lib-graphql

Env Setup

ENV variables suggested

APP_ENV=dev
APP_NAME=nice-service
APP_DEBUG=1
APP_PORT=4000

Register

import {
    makeGraphqlServer, graphqlMiddleware, graphqlStandalone
} from '@occupop/lib-graphql'
import { resolvers } from './app/resolvers'
//... all other imports omited... 

export const container = createTypedContainer({
    // ...
    graphqlServer: { asFunction: makeGraphqlServer, singleton: true },
    graphqlSchema: { asFunction: () => readFileSync(path.resolve(__dirname, 'src/schema.graphql')), singleton: true },
    graphqlResolvers: { asValue: resolvers },  
    graphqlStandalone: { asValue: graphqlStandalone }, // if startStandaloneServer needed 
    graphqlMiddleware: { asValue: graphqlMiddleware }, // if expressMiddleware needed 
    // ...
})

About the helpers

The helpers startStandaloneServer and expressMiddleware can be used as graphqlStandalone and graphqlMiddleware (alias is just for naming convenience).

Usage (starting server)

Standalone server

// server.ts
import { container } from '.container'

const { graphqlServer, graphqlStandalone } = container.cradle

const httpPort = process.env.APP_PORT || 4000
await await graphqlStandalone(graphqlServer, {
    context: async ({ req }) => ({ userToken: req.headers.token }),
    listen: { port: httpPort },
})
console.log(`Server listening on http://localhost:${httpPort}`)

Over Express

// server.ts
import { container } from '.container'

const { httpServer, graphqlServer, graphqlMiddleware } = container.cradle

await graphqlServer.start() // server require start() call...

const httpPort = process.env.APP_PORT || 4000
await await httpServer.use('/graphql', graphqlMiddleware(graphqlServer, {
    context: async ({ req }) => ({ token: req.headers.token }),
}))

await new Promise(resolve => httpServer.listen({ port: httpPort }, resolve))
console.log(`Server listening on http://localhost:${httpPort}`)

Usage (schema & resolver)

# app/schema.graphql

type Query {
    jobs: [Job]
}

type Job {
    uuid: String
    title: String
}

// app/resolvers.ts
type AppContext = { userToken: string }

export const resolvers: GraphQLResolverMap<AppContext> = {
    Query: {
        jobs: (source, args, { userToken }, info) => {
            authCheck(userToken)
            return jobs
        },
    },
}

Context function & value

Context function passed to the start server helpers are essential to keep user navigation scope under control. the ideal/recommended way of implementing context function with @occupop/lib-container is to create a scoped container and extract the user data from request (token, headers, User, etc) to be passed to context. This way, graphql-resolvers and container-resolvers will receive those injected values to be treated as necessary.

Some usage notes about context signature:

• Treat graphql-resolvers as routers, they should know how to call an useCase/controller.
• Treat useCases and Controllers as orchestrators they should treat/validate input, user/auth and call appropriate services.
• Treat Services as business rules dealer, they know how to deal with its own minimum responsibilities but not aware of who called. Remember:
  • Services can always be called from queues/commands/events).
  • Clean code: if a service is doing too much, maybe he is bad designed.

Sample (real life) context function

import { container } from '.container'

export type AppContext = { 
  container: typeof container // for router scoped resolve only...
}
export async function contextFunction(req, res): AppContext {
  const scoped = container.createScope()
  const { authService } = container.cradle 
  const token = req.headers?.Authorization
  scoped.register({ authUser: asValue(await authService.getUser(token)) })
  return { container: scoped }
}

Schema helper

The schema below will be generated by the server to support federated schamas. If you with your IDE to understand directives and know about the base structure just copy and paste the schema helper below anywhere inside your project structure.

Reference: https://www.apollographql.com/docs/graphos/reference/federation/subgraph-spec

# schema-helpers.graphql

"""
This schema is mocks for IDEs to recognize the federation directives and base structure.
Reference: https://www.apollographql.com/docs/graphos/reference/federation/subgraph-spec
"""

type ZXC1 {thoseTypesAreJustAPlaceholderToAllowUnionToBeMocked:String}
type ZXC2 {thoseTypesAreJustAPlaceholderToAllowUnionToBeMocked:String}

union _Entity = ZXC1 | ZXC2

scalar _Any
scalar FieldSet
scalar link__Import
scalar federation__ContextFieldValue
scalar federation__Scope
scalar federation__Policy

enum link__Purpose {
    """
    `SECURITY` features provide metadata necessary to securely resolve fields.
    """
    SECURITY

    """
    `EXECUTION` features provide metadata necessary for operation execution.
    """
    EXECUTION
}

type _Service {
    sdl: String!
}

extend type Query {
    _entities(representations: [_Any!]!): [_Entity]!
    _service: _Service!
}

directive @external on FIELD_DEFINITION | OBJECT
directive @requires(fields: FieldSet!) on FIELD_DEFINITION
directive @provides(fields: FieldSet!) on FIELD_DEFINITION
directive @key(fields: FieldSet!, resolvable: Boolean = true) repeatable on OBJECT | INTERFACE
directive @link(url: String!, as: String, for: link__Purpose, import: [link__Import]) repeatable on SCHEMA
directive @shareable repeatable on OBJECT | FIELD_DEFINITION
directive @inaccessible on FIELD_DEFINITION | OBJECT | INTERFACE | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
directive @tag(name: String!) repeatable on FIELD_DEFINITION | INTERFACE | OBJECT | UNION | ARGUMENT_DEFINITION | SCALAR | ENUM | ENUM_VALUE | INPUT_OBJECT | INPUT_FIELD_DEFINITION
directive @override(from: String!) on FIELD_DEFINITION
directive @composeDirective(name: String!) repeatable on SCHEMA
directive @interfaceObject on OBJECT
directive @authenticated on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM
directive @requiresScopes(scopes: [[federation__Scope!]!]!) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM
directive @policy(policies: [[federation__Policy!]!]!) on FIELD_DEFINITION | OBJECT | INTERFACE | SCALAR | ENUM
directive @context(name: String!) repeatable on INTERFACE | OBJECT | UNION
#directive @fromContext(field: ContextFieldValue) on ARGUMENT_DEFINITION

# This definition is required only for libraries that don't support
# GraphQL's built-in `extend` keyword
directive @extends on OBJECT | INTERFACE