Allow asynchronous for all plugin hooks

[cometkim]

onEnveloped, onSchemaChange, onPluginInit and onParse hooks don't seem to support async function in their definition.

I see async situations in most use cases for integrating with external systems. So I think the whole lifecycle should allow for asynchronous functions. A good example is the plugin interface of GatsbyJS. All their interfaces allow either synchronous or asynchronous.

https://github.com/dotansimha/envelop/blob/b8cc21b/packages/plugins/persisted-operations/src/index.ts#L18

when user want to connect this plugin to an external store, mostly it should be via async IO. But onParse hook doesn't seem allow async function.

[dotansimha]

Hi @cometkim ! I'm happy to see you here ❤️

I was thinking a lot about this, and we have 2 conflicting points here:

1. envelop aims to keep the original signature of the graphql the same, and parse (and validate) are defined as sync.
2. When dealing with persisted operations, you might need an async data source.

At the moment, we don't want to change the signature of the original functions, because not all servers or consumers of the wrapped envelop function might doing await on these places.

To address this, I recommend considering implementing a persisted operations store that loads the data in an async way and then provides it to envelop as an instance that might update behind the scenes.

Here's a small example of that:

class MyRemoteJsonStore implements PersistedOperationsStore {
  private data: Record<string, string> = {};
  constructor(private url) {}
  canHandle() { return true };
   
  get(id: string) {
     return this.data[id];
  }
  
  public async load(): Promise<void> {
    return fetch(this.url).then(r => r.json()).then(r => this.data = r);
  }
}

// Create the store
const store = new MyRemoteJsonStore(URL);
// Create the envelop instance
const getEnveloped = envelop({ plugins: [ usePersistedOperations({ store ]);
// make sure to load and wait the initial data
await store.load();
// start your server / mark it as ready
server.listen();

// If you want, you can also refresh it using polling 
setTimeout(() => {
  store.load();
}, 1000 * 60 * 10);

[santino]

I think it really depends on what we want to achieve in terms of specific functionalities.

Sticking with the persisted operations plugin, in an exploratory PR for a new implementation of the plugin, #324, I have designed the store implementation in a way that can support async behaviors.
Store is a class that exposes load and a get methods.
At any point during runtime, developers can use load to update the list of queries supported by the server.
Under the hood, all the queries are stored in a Map that will be updated when required.
Then on each operation, the persisted operation plugin invokes the get method, which does nothing but returning the Map object, which of course is cached and available in memory.

You can take a look at the basic implementation of the Store that I did to take into account static json files.

I have now raised #498 where I plan to add the functionalities explored in that PR onto the existing persisted operations plugin, so hopefully, this is something that will make it in.

Anyway, that's just an example to say that depending on functionalities that we want to achieve, plugins can still be implemented in a way that takes into account async behaviors.
Hence why I'm very interested to hear about some specific use cases to try and find solutions with the existing API.

[cometkim]

I'm most interested in the right now is building a first-class GraphQL framework that works on the Web Workers interface.

Service Workers, Deno Deploy, Cloudflare Workers and Miniflare

Most of them are deployed and run in the edge, and with async storage (Cloudflare Workers KV, Indexed DB) that you can use together.

As you know, these are not treated as a long-running job, so they do not have the same semantics and tradeoffs for the in-memory caching. Async storage API is the solution here to have low IO delays and memory pressures.

Forcing the alternative cache strategy without getting this advantage is felt as a limitation of the platform, not a reasonable alternative.

I agreed to the incompatibility of async, but I don't think that this is the direction of meta frameworks & plugin systems to go.

[cometkim]

graphql-helix supports async parse function and that's all we need actually, but other servers might not have that.

I don't know the case that is locked to the sync interface while it is expected to be used as it is by users. What is the example of an existing server or framework you consider?

[n1ru4l]

The meta framework could pre-fill the cache on-demand by calling a function for loading a specific operation (based on the request parameters) before calling validate.

---

I dont think we will convince graphql-js maintainers to change the type aignature vor validate and parse to async - but it might be worth a try..

[n1ru4l]

@cometkim I finally started a issue on this :) graphql/graphql-js#3421

[cometkim]

An example is the plugin system of the mercurius-js (also Node graphql framework built on top of fastify)

https://mercurius.dev/#/docs/hooks