dotansimha / envelop

Envelop

envelop is a lightweight JavaScript (/TypeScript) library for wrapping GraphQL execution layer and flow, allowing developers to develop, share and collaborate on GraphQL-related plugins while filling the missing pieces in GraphQL implementations.

envelop aims to extend the GraphQL execution flow by adding plugins that enrichs the feature set of your application.

@envelop/core:

Envelop is created and maintained by The Guild, and used in production by our clients.

Envelop Key Concepts

• Lightweight
• Wraps the entire GraphQL pipeline, based on plugins
• Low-level API for extending the execution layer
• Agnostic to GraphQL Engine
• Agnostic to the HTTP layer
• Agnostic to the schema tools
• Plugins-based usage
• No vendor lock-in
• Amazing TypeScript support

You can read more about the key concepts or Envelop here

Getting Started

Start by adding the core of Envelop to your codebase:

yarn add graphql @envelop/core

Then, create a simple Envelop based on your GraphQL schema:

import * as GraphQLJS from 'graphql'
import { envelop, useEngine, useSchema } from '@envelop/core'

const mySchema = buildSchema(/* ... */) // GraphQLSchema

const getEnveloped = envelop({
  plugins: [useEngine(GraphQLJS), useSchema(mySchema)]
})

The result of envelop is a function that allows you to get everything you need for the GraphQL execution: parse, validate, contextBuilder and execute. Use that to run the client's GraphQL queries. Here's a pseudo-code example of how it should look like:

const httpServer = createServer()

httpServer.on('request', async (req, res) => {
  // Here you get the alternative methods that are bundled with your plugins
  // You can also pass the "req" to make it available for your plugins or GraphQL context.
  const { parse, validate, contextFactory, execute, schema } = getEnveloped({ req })

  // Parse the initial request and validate it
  const { query, variables } = JSON.parse(req.payload)
  const document = parse(query)
  const validationErrors = validate(schema, document)

  if (validationErrors.length > 0) {
    return res.end(JSON.stringify({ errors: validationErrors }))
  }

  // Build the context and execute
  const context = await contextFactory(req)
  const result = await execute({
    document,
    schema,
    variableValues: variables,
    contextValue: context
  })

  // Send the response
  res.end(JSON.stringify(result))
})

httpServer.listen(3000)

Behind the scenes, this simple workflow allows you to use Envelop plugins and hook into the entire request handling flow.

Here's a simple example for collecting metrics and log all incoming requests, using the built-in plugins:

const getEnveloped = envelop({
  plugins: [useEngine(GraphQLJS), useSchema(schema), useLogger(), useTiming()]
})

You can read more about here

Integrations / Examples

You can find the integrations and compatibility list, and code-based examples here

Available Plugins

You can explore all plugins in our Plugins Hub. If you wish your plugin to be listed here and under PluginsHub, feel free to add your plugin information in this file and create a Pull Request!

We provide a few built-in plugins within the @envelop/core, and many more plugins as standalone packages.

Envelop's Plugin Hub

Sharing / Composing envelops

After an envelop has been created, you can share it with others as a complete layer of plugins. This is useful if you wish to create a predefined layer of plugins, and share it with others. You can use it as a shell and as a base for writing shareable pieces of servers.

You can read more about Sharing and Composing Envelops here.

Write your own plugin!

Envelop plugins are just objects with functions, that provide contextual implementation for before/after of each phase, with a flexible API.

Here's a simple example that allows you to print the execution params:

const myPlugin = {
  onExecute({ args }) {
    console.log('Execution started!', { args })

    return {
      onExecuteDone({ result }) {
        console.log('Execution done!', { result })
      }
    }
  }
}

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

For a complete guide and API docs for custom plugins, please refer to Envelop website

Contributing

If this is your first time contributing to this project, please do read our Contributor Workflow Guide before you get started off.

Feel free to open issues and pull requests. We're always welcome support from the community.

Code of Conduct

Help us keep Envelop open and inclusive. Please read and follow our of Conduct as adopted from Contributor Covenant

License

MIT