@envelop/core

What is @envelop/core?

@envelop/core is a powerful library for building GraphQL servers with a focus on extensibility and modularity. It provides a plugin system that allows developers to easily add, remove, or customize functionalities in their GraphQL server setup.

What are @envelop/core's main functionalities?

Plugin System

The plugin system allows you to add various plugins to your GraphQL server. In this example, we use the `useSchema` plugin to set up a basic schema.

const { envelop, useSchema } = require('@envelop/core');
const { makeExecutableSchema } = require('@graphql-tools/schema');

const schema = makeExecutableSchema({
  typeDefs: `
    type Query {
      hello: String
    }
  `,
  resolvers: {
    Query: {
      hello: () => 'Hello world!',
    },
  },
});

const getEnveloped = envelop({
  plugins: [useSchema(schema)],
});

const { parse, validate, contextFactory, execute, schema: finalSchema } = getEnveloped();

Custom Plugins

You can create custom plugins to extend the functionality of your GraphQL server. This example shows a custom plugin that logs the operation name whenever an operation is executed.

const { envelop, useLogger } = require('@envelop/core');

const customPlugin = {
  onExecute({ args }) {
    console.log('Executing operation:', args.operationName);
  },
};

const getEnveloped = envelop({
  plugins: [useLogger(), customPlugin],
});

const { execute } = getEnveloped();

Error Handling

The error handling feature allows you to manage and log errors that occur during GraphQL operations. This example demonstrates how to use the `useErrorHandler` plugin to log errors.

const { envelop, useErrorHandler } = require('@envelop/core');

const errorHandlerPlugin = useErrorHandler((errors) => {
  console.error('GraphQL Errors:', errors);
});

const getEnveloped = envelop({
  plugins: [errorHandlerPlugin],
});

const { execute } = getEnveloped();

Other packages similar to @envelop/core

apollo-server

Apollo Server is a popular GraphQL server library that provides an easy-to-use setup and a rich ecosystem of tools and integrations. Compared to @envelop/core, Apollo Server is more opinionated and comes with built-in features like caching, tracing, and schema stitching.

graphql-yoga

GraphQL Yoga is a fully-featured GraphQL server with a focus on simplicity and ease of use. It is built on top of GraphQL.js and provides a lot of out-of-the-box features. While @envelop/core focuses on modularity and extensibility through plugins, GraphQL Yoga aims to provide a more straightforward setup.

express-graphql

Express-GraphQL is a minimalistic GraphQL server middleware for Express.js. It is simple to set up and use, making it a good choice for small to medium-sized applications. Unlike @envelop/core, express-graphql does not have a plugin system and is less extensible.

README

@envelop/core

This is the core package for Envelop. You can find a complete documentation here: https://github.com/dotansimha/envelop

Built-in plugins

useSchema

This plugin is the simplest plugin for specifying your GraphQL schema. You can specify a schema created from any tool that emits GraphQLSchema object.

import { envelop, useSchema } from '@envelop/core';
import { buildSchema } from 'graphql';

const mySchema = buildSchema(...);

const getEnveloped = envelop({
  plugins: [
    useSchema(mySchema),
    // ... other plugins ...
  ],
});

useErrorHandler

This plugin triggers a custom function every time execution encounter an error.

import { envelop, useErrorHandler } from '@envelop/core';
import { buildSchema } from 'graphql';

const getEnveloped = envelop({
  plugins: [
    useErrorHandler(error => {
      // This callback is called per each GraphQLError emitted during execution phase
    }),
    // ... other plugins ...
  ],
});

Note: every error is being triggered on it's own. So an execution results will multiple error will yield multiple calls.

useExtendContext

Easily extends the context with custom fields.

import { envelop, useExtendContext } from '@envelop/core';
import { buildSchema } from 'graphql';

const getEnveloped = envelop({
  plugins: [
    useExtendContext(async (contextSoFar) => {
      return {
        myCustomField: { ... }
      }
    }),
    // ... other plugins ...
  ],
});

useLogger

Logs paramaters and information about the execution phases. You can easily plug your custom logger.

import { envelop, useLogger } from '@envelop/core';
import { buildSchema } from 'graphql';

const getEnveloped = envelop({
  plugins: [
    useLogger({
      logFn: (eventName, args) => {
        // Event could be `execute-start` / `execute-end` / `subscribe-start` / `subscribe-end`
        // `args` will include the arguments passed to execute/subscribe (in case of "start" event) and additional result in case of "end" event.
      },
    }),
    // ... other plugins ...
  ],
});

usePayloadFormatter

Allow you to format/modify execution result payload before returning it to your consumer.

import { envelop, usePayloadFormatter } from '@envelop/core';
import { buildSchema } from 'graphql';

const getEnveloped = envelop({
  plugins: [
    usePayloadFormatter(result => {
      // Return a modified result here,
      // Or `false`y value to keep it as-is.
    }),
    // ... other plugins ...
  ],
});

useTiming

Simple time metric collection, for every phase in your execution. You can easily customize the behaviour of each timing measurement. By default, the timing is printed to the log, using console.log.

import { envelop, useTiming } from '@envelop/core';
import { buildSchema } from 'graphql';

const getEnveloped = envelop({
  plugins: [
    useTiming({
      // All options are optional. By default it just print it to the log.
      // ResultTiming is an object built with { ms, ns } (milliseconds and nanoseconds)
      onContextBuildingMeasurement: (timing: ResultTiming) => {},
      onExecutionMeasurement: (args: ExecutionArgs, timing: ResultTiming) => {},
      onSubscriptionMeasurement: (args: SubscriptionArgs, timing: ResultTiming) => {},
      onParsingMeasurement: (source: Source | string, timing: ResultTiming) => {},
      onValidationMeasurement: (document: DocumentNode, timing: ResultTiming) => {},
      onResolverMeasurement: (info: GraphQLResolveInfo, timing: ResultTiming) => {},
    }),
    // ... other plugins ...
  ],
});

useMaskedErrors

Prevent unexpected error messages from leaking to the GraphQL clients.

import { envelop, useSchema, useMaskedErrors, EnvelopError } from '@envelop/core';
import { makeExecutableSchema } from 'graphql';

const schema = makeExecutableSchema({
  typeDefs: /* GraphQL */ `
    type Query {
      something: String!
      somethingElse: String!
      somethingSpecial: String!
    }
  `,
  resolvers: {
    Query: {
      something: () => {
        throw new EnvelopError('Error that is propagated to the clients.');
      },
      somethingElse: () => {
        throw new Error("Unsafe error that will be masked as 'Unexpected Error.'.");
      },
      somethingSpecial: () => {
        throw new EnvelopError('The error will have an extensions field.', {
          code: 'ERR_CODE',
          randomNumber: 123,
        });
      },
    },
  },
});

const getEnveloped = envelop({
  plugins: [useSchema(schema), useMaskedErrors()],
});