@envelop/core

Minor Changes

• #2607 3ebaa3b Thanks @EmrysMyrddin! - Added new withState plugin utility for easy data sharing between hooks.

  New plugin utility to ease data sharing between hooks

  Sometimes, plugins can grow in complexity and need to share data between its hooks.

  A way to solve this can be to mutate the graphql context, but this context is not always available in all hooks in Yoga or Hive Gateway plugins. Moreover, mutating the context gives access to your internal data to all other plugins and graphql resolvers, without mentioning performance impact on field access on this object.

  The recommended approach to this problem was to use a WeakMap with a stable key (often the context or request object). While it works, it's not very convenient for plugin developers, and is prone to error with the choice of key.

  The new withState utility solves this DX issue by providing an easy and straightforward API for data sharing between hooks.

  import { withState } from '@envelop/core'
  
  type State = { foo: string }
  
  const myPlugin = () =>
    withState<Plugin, State>(() => ({
      onParse({ state }) {
        state.forOperation.foo = 'foo'
      },
      onValidate({ state }) {
        const { foo } = state.forOperation
        console.log('foo', foo)
      }
    }))
  

  The state payload field will be available in all relevant hooks, making it easy to access shared data. It also forces the developer to choose the scope for the data:

  • forOperation for a data scoped to GraphQL operation (Envelop, Yoga and Hive Gateway)
  • forRequest for a data scoped to HTTP request (Yoga and Hive Gateway)
  • forSubgraphExecution for a data scoped to the subgraph execution (Hive Gateway)

  Not all scopes are available in all hooks, the type reflects which scopes are available

  Under the hood, those states are kept in memory using WeakMap, which avoid any memory leaks.

  It is also possible to manually retrieve the state with the getState function:

  const myPlugin = () =>
    withState(getState => ({
      onParse({ context }) {
        // You can provide a payload, which will dictate which scope you have access to.
        // The scope can contain `context`, `request` and `executionRequest` fields.
        const state = getState({ context })
        // Use the state elsewhere.
      }
    }))
  

Patch Changes

• #2486 914f9ed Thanks @EmrysMyrddin! - dependencies updates:

  • Added dependency @envelop/instrumentation@workspace:^ ↗︎ (to dependencies)
  • Removed dependency @envelop/instruments@workspace:^ ↗︎ (from dependencies)

• #2486 914f9ed Thanks @EmrysMyrddin! - Fix the name of the new envelop instrumentation API

• Updated dependencies [914f9ed]:

  • @envelop/types@5.2.1

Patch Changes

• #2484 26137e7 Thanks @renovate! - dependencies updates:

  • Updated dependency @whatwg-node/promise-helpers@^1.2.4 ↗︎ (from ^1.2.1, in dependencies)

• #2484 26137e7 Thanks @renovate! - dependencies updates:

  • Updated dependency @whatwg-node/promise-helpers@^1.2.4 ↗︎ (from ^1.2.1, in dependencies)

Patch Changes

• #2473 90dd1a6 Thanks @renovate! - dependencies updates:

  • Updated dependency @whatwg-node/promise-helpers@^1.2.1 ↗︎ (from ^1.0.0, in dependencies)

• #2473 90dd1a6 Thanks @renovate! - Use Promise helpers

Minor Changes

• #2430 a107c89 Thanks @EmrysMyrddin! - ## New Instruments API

  Introducation of a new API allowing to instrument the graphql pipeline.

  This new API differs from already existing Hooks by not having access to intup/output of phases. The goal of Instruments is to run allow running code before, after or araound the whole process of a phase, incuding plugins hooks executions.

  The main use case of this new API is observability (monitoring, tracing, etc...).

  Basic usage

  import { envelop } from '@envelop/core'
  import Sentry from '@sentry/node'
  
  const getEnveloped = envelop({
    plugins: [
      {
        instruments: {
          execute: ({ context }, wrapped) =>
            Sentry.startSpan({ name: 'Graphql Operation' }, async () => {
              try {
                await wrapped()
              } catch (err) {
                Sentry.captureException(err)
              }
            })
        }
      }
    ]
  })
  

  Mutliple instruments plugins

  It is possilbe to have multiple instruments plugins (Prometheus and Sentry for example), they will be automatically composed by envelop in the same order than the plugin array (first is outtermost, last is inner most).

  import { useOpentelemetry } from '@envelop/opentelemetry'
  import { useSentry } from '@envelop/sentry'
  
  const getEnveloped = envelop({
    plugins: [useSentry(), useOpentelemetry()]
  })
  

  Custom instruments ordering

  If the default composition ordering doesn't suite your need, you can mannually compose instruments. This allows to have a different execution order of hooks and instruments.

  import { useOpentelemetry } from '@envelop/opentelemetry'
  import { composeInstruments, useSentry } from '@envelop/sentry'
  
  const { instruments: sentryInstruments, ...sentryPlugin } = useSentry()
  const { instruments: otelInstruments, ...otelPlugin } = useOpentelemetry()
  const instruments = composeInstruments([otelInstruments, sentryInstruments])
  
  const getEnveloped = envelop({
    plugins: [{ instruments }, sentryPlugin, otelPlugin]
  })
  

Patch Changes

• #2430 a107c89 Thanks @EmrysMyrddin! - dependencies updates:
  • Added dependency @envelop/instruments@workspace:^ ↗︎ (to dependencies)
• Updated dependencies [a107c89]:
  • @envelop/types@5.2.0