feat(core): New plugin utils withState

[EmrysMyrddin]

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.
    }
  }))

[github-actions]

🚀 Snapshot Release (alpha)

The latest changes of this PR are available as alpha on npm (based on the declared changesets):

Package	Version	Info
@envelop/core	5.3.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/apollo-datasources	6.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/apollo-federation	7.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/apollo-server-errors	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/apollo-tracing	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/auth0	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/dataloader	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/depth-limit	6.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/disable-introspection	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/execute-subscription-event	7.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/extended-validation	6.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/filter-operation-type	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/fragment-arguments	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/generic-auth	10.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/graphql-jit	10.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/graphql-middleware	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/graphql-modules	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/immediate-introspection	6.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/live-query	9.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/newrelic	9.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/on-resolve	6.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/opentelemetry	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/operation-field-permissions	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/parser-cache	9.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/persisted-operations	9.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/preload-assets	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/prometheus	13.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/rate-limiter	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/resource-limitations	7.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/response-cache	8.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/response-cache-cloudflare-kv	4.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/response-cache-redis	4.2.4-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/sentry	14.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/statsd	7.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/validation-cache	9.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎
@envelop/testing	9.0.0-alpha-20250619123936-34350ff4ef8e7fc3f05ccdfff4465668f5002b76	npm ↗︎ unpkg ↗︎

[github-actions]

💻 Website Preview

The latest changes are available as preview in: