document how to use persisted queries

Story

I want to be able to only send an id instead of a full GraphQL document to the server and then read the actual GraphQL document from a hash table (maybe even asynchronous).

---

Edit: https://github.com/enisdenjo/graphql-transport-ws/issues/36 showed that this is already possible. It just needs to be documented.

In my Socket.io GraphQL layer I choose to omit passing a context, schema, execute, subscribe etc parameters on a server factory level, but instead choose that a getParameter function must be passed to the server factory. That function is invoked for each GraphQL operation executed with the socket and the sent payload. The user can then decide to map the provided GraphQL Payload to anything else and providing a different context/schema/execute/subscribe based on that.

It has the following type signature

export type GetParameterFunctionParameter = {
  socket: SocketIO.Socket;
  graphQLPayload: {
    source: string;
    variableValues: { [key: string]: any } | null;
    operationName: string | null;
  };
};

export type GetParameterFunction = (
  parameter: GetParameterFunctionParameter
) => PromiseOrPlain<{
  graphQLExecutionParameter: {
    schema: GraphQLSchema;
    contextValue?: unknown;
    rootValue?: unknown;
    // These will overwrite the initials if provided; Useful for persisted queries etc.
    operationName?: string;
    source?: string;
    variableValues?: { [key: string]: any } | null;
  };
  execute?: typeof execute;
  subscribe?: typeof subscribe;
}>;

Which then allows doing stuff like this:

import socketIO from "socket.io";

const persistedOperations = {
    "1": "query { ping }"
    "2": "mutation { ping }"
}

const socketServer = socketIO();

const graphqlServer  = registerSocketIOGraphQLServer({
  socketServer,
  getParameter: ({ socket, graphQLPayload }) => ({
    /* The paramaters used for the operation execution. */
    graphQLExecutionParameter: {
      schema,
      rootValue:,
      contextValue: {
        socket,
      },
      // client source is just the id instead of a full document.
      // we map the id to the actual document.
      source: persistedOperations[graphQLPayload.source]
    },
  }),
});

(This design could also address https://github.com/enisdenjo/graphql-transport-ws/issues/36 as the getParameter function could throw an error or return a rejected Promise etc).

graphql-transport-ws might get some inspiration from this.

[enisdenjo]

Good idea! We should offer a handler like that.

However, onOperation is a better suited name for when an operation resolves, and onSubscribe for immediately when the user requests a subscription (operation execution).

The current onSubscribe has to change. Even if its a breaking change, its worthwhile! Check #40 out.

[enisdenjo]

Quick heads up, @n1ru4l, graphql-ws@v4.7.0 just landed, adding the extensions field in the subscribe message payload.

This means that you now can pass along the persistedQuery through that field on each subscribe as various other libraries/frameworks suggest. And of course, extend with your custom requirements. 😄