GraphQL Modules

GraphQL Modules is a utility library designed to implement the Separation of Concerns design pattern in GraphQL. It allows you to split your GraphQL schema implementation into small, reusable, and easy-to-test pieces.

Each module contains its own GraphQL type definitions and resolver implementations. While you develop using these separated modules, GraphQL Modules merges them at runtime to serve a single, unified GraphQL schema.

A middleware is a function used to intercept individual resolve functions or a group of them. It can return a different result or throw an exception based on a condition.

Middlewares can be sync or async and accept two arguments:

1. An event object containing root, args, context, and info.
2. A next function that calls the next middleware in the chain or the actual resolver.

Every middleware must do one of three things:

• Throw an exception.
• Return the result of next().
• Return a specific value.

Warning: If a middleware returns undefined, it will be treated as the result of the field resolver.

function middleware({ root, args, context, info }, next) {
  // ...
  return next()
}

In v0, modules formed a hierarchy using imports. In v1, modules are flat, and you use createApplication to define the root of the injection container. This removes the need for strict module-to-module dependency trees.

// V1: Flat structure with Application
const moduleOne = createModule({ ... })
const moduleTwo = createModule({ ... })

const application = createApplication({
  modules: [moduleOne, moduleTwo]
})

// V0 (Deprecated): Hierarchical structure
const moduleOne = new GraphQLModule({ ... })
const moduleTwo = new GraphQLModule({ imports: [moduleOne], ... })

const rootModule = new GraphQLModule({
  imports: [moduleTwo]
})

GraphQL Modules uses a hierarchical Dependency Injection system where every Module has its own isolated injector space, which in turn reuses a global space defined by the Application.

• Module Injector: Responsible for managing its own Providers and InjectionTokens. Anything defined here is only accessible within that specific module and does not leak to other modules or the application.
• Application Injector: The parent injector. If a Provider or InjectionToken is not found in the Module Injector, the system will look up the hierarchy to the Application Injector.

This structure allows modules to consume application-level services while keeping module-specific logic encapsulated.

While a Singleton service can directly access an Operation scoped service, an Operation scoped service cannot directly access a Singleton.

To allow a Singleton service to indirectly access Operation scoped tokens or services, use the @ExecutionContext decorator.

The architecture of a GraphQL Modules application is flat. At the top level, there is an Application which manages the overall schema. Below the application, multiple Modules exist on the same level.

Each module is built using standard GraphQL components:

• Type definitions: The schema parts specific to that module.
• Resolver functions: The logic for those schema parts.

As applications scale, modules can utilize Dependency Injection to further separate resolver logic from core business logic.

In GraphQL, context is a shared object available to all resolvers during a specific execution. It is typically used to store authentication information, the current user, database connections, or data sources.

GraphQL Modules follows the standard GraphQL approach: the context is passed as the third argument to every resolver. Because the context is managed by the underlying GraphQL server implementation (which populates it with data like HTTP request information), GraphQL Modules does not provide a specific API for building the context itself.

const resolvers = {
  Query: {
    myQuery(root, args, context, info) {
      // context is available here
    }
  }
}

Middlewares follow a specific hierarchical execution order from the broadest scope (Application global) to the most specific (Module field). The order is:

1. Application *.* (Global application middleware)
2. Module *.* (Global module middleware)
3. Application Type.* (Type-specific application middleware)
4. Module Type.* (Type-specific module middleware)
5. Application Type.Field (Field-specific application middleware)
6. Module Type.Field (Field-specific module middleware)
7. The actual resolver

This means that a middleware registered on a specific field in a module will be the last one to run before the resolver itself.

The @ExecutionContext decorator relies on Node.js async_hooks to ensure that the correct context is associated with the correct asynchronous execution flow. This is critical to prevent race conditions during concurrent parallel requests.

Performance Note: Because async_hooks is used, there is a performance impact. However, graphql-modules is optimized to only enable async_hooks when the @ExecutionContext decorator is actually used in your code.

Dependency Injection (DI) in GraphQL Modules is built on two core concepts:

1. InjectionToken: A symbol or class that represents an object or value within the DI space. It acts as the unique identifier used to request a dependency.
2. Provider: A definition that maps a specific InjectionToken to a value or a way to create a value.

By using these, you can decouple your business logic (Services) from the specific implementations or values they require.