|
1 | 1 | # @envelop/core |
2 | 2 |
|
| 3 | +## 5.3.0 |
| 4 | + |
| 5 | +### Minor Changes |
| 6 | + |
| 7 | +- [#2607](https://github.com/graphql-hive/envelop/pull/2607) |
| 8 | + [`3ebaa3b`](https://github.com/graphql-hive/envelop/commit/3ebaa3b75b34f9a61aa517166f538796b383bfad) |
| 9 | + Thanks [@EmrysMyrddin](https://github.com/EmrysMyrddin)! - Added new `withState` plugin utility |
| 10 | + for easy data sharing between hooks. |
| 11 | + |
| 12 | + ## New plugin utility to ease data sharing between hooks |
| 13 | + |
| 14 | + Sometimes, plugins can grow in complexity and need to share data between its hooks. |
| 15 | + |
| 16 | + A way to solve this can be to mutate the graphql context, but this context is not always available |
| 17 | + in all hooks in Yoga or Hive Gateway plugins. Moreover, mutating the context gives access to your |
| 18 | + internal data to all other plugins and graphql resolvers, without mentioning performance impact on |
| 19 | + field access on this object. |
| 20 | + |
| 21 | + The recommended approach to this problem was to use a `WeakMap` with a stable key (often the |
| 22 | + `context` or `request` object). While it works, it's not very convenient for plugin developers, |
| 23 | + and is prone to error with the choice of key. |
| 24 | + |
| 25 | + The new `withState` utility solves this DX issue by providing an easy and straightforward API for |
| 26 | + data sharing between hooks. |
| 27 | + |
| 28 | + ```ts |
| 29 | + import { withState } from '@envelop/core' |
| 30 | + |
| 31 | + type State = { foo: string } |
| 32 | + |
| 33 | + const myPlugin = () => |
| 34 | + withState<Plugin, State>(() => ({ |
| 35 | + onParse({ state }) { |
| 36 | + state.forOperation.foo = 'foo' |
| 37 | + }, |
| 38 | + onValidate({ state }) { |
| 39 | + const { foo } = state.forOperation |
| 40 | + console.log('foo', foo) |
| 41 | + } |
| 42 | + })) |
| 43 | + ``` |
| 44 | + |
| 45 | + The `state` payload field will be available in all relevant hooks, making it easy to access shared |
| 46 | + data. It also forces the developer to choose the scope for the data: |
| 47 | + |
| 48 | + - `forOperation` for a data scoped to GraphQL operation (Envelop, Yoga and Hive Gateway) |
| 49 | + - `forRequest` for a data scoped to HTTP request (Yoga and Hive Gateway) |
| 50 | + - `forSubgraphExecution` for a data scoped to the subgraph execution (Hive Gateway) |
| 51 | + |
| 52 | + Not all scopes are available in all hooks, the type reflects which scopes are available |
| 53 | + |
| 54 | + Under the hood, those states are kept in memory using `WeakMap`, which avoid any memory leaks. |
| 55 | + |
| 56 | + It is also possible to manually retrieve the state with the `getState` function: |
| 57 | + |
| 58 | + ```ts |
| 59 | + const myPlugin = () => |
| 60 | + withState(getState => ({ |
| 61 | + onParse({ context }) { |
| 62 | + // You can provide a payload, which will dictate which scope you have access to. |
| 63 | + // The scope can contain `context`, `request` and `executionRequest` fields. |
| 64 | + const state = getState({ context }) |
| 65 | + // Use the state elsewhere. |
| 66 | + } |
| 67 | + })) |
| 68 | + ``` |
| 69 | + |
3 | 70 | ## 5.2.3 |
4 | 71 |
|
5 | 72 | ### Patch Changes |
|
0 commit comments