docs: add TSDocs to plugin hooks

packages/graphql-yoga/src/plugins/types.ts

@@ -37,33 +37,46 @@ export type Plugin<
      */
     onSubscribe?: OnSubscribeHook<YogaInitialContext & PluginContext & TUserContext>;
     /**
-     * Invoked when a plugin is initialized.
+     * Invoked when a plugin is initialized. You can use this hook to add other plugin you may depend on.
      */
     onPluginInit?: OnPluginInitHook<YogaInitialContext & PluginContext & TUserContext>;
   } & {
     /**
-     * Use this hook with your own risk. It is still experimental and may change in the future.
-     * @internal
+     * This hook is invoked at Yoga Server initialization, before it starts.
+     * Here you can setup long running resources (like monitoring or caching clients)
+     * or customize the Yoga instance.
      */
     onYogaInit?: OnYogaInitHook<TServerContext>;
     /**
-     * Use this hook with your own risk. It is still experimental and may change in the future.
-     * @internal
+     * This hook is invoked for any incoming GraphQL HTTP request and is invoked before attempting
+     * to parse the GraphQL parameters. Here you can manipulate the request, set a custom request
+     * parser or apply security measures such as checking for access tokens etc.
      */
     onRequestParse?: OnRequestParseHook<TServerContext>;
     /**
-     * Use this hook with your own risk. It is still experimental and may change in the future.
-     * @internal
+     * This hook is invoked for an incoming GraphQL request after the GraphQL parameters
+     * (query, variables, extensions and operationName) have been ATTEMPTED to be parsed.
+     *
+     * Within this hook you can manipulate and customize the parameters or even implement a whole
+     * new way of parsing the parameters.
+     *
+     * In addition to that you could also short-circuit and skip the GraphQL execution.
      */
     onParams?: OnParamsHook<TServerContext>;
     /**
-     * Use this hook with your own risk. It is still experimental and may change in the future.
-     * @internal
+     * This hook is invoked for each result produced for GraphQL operation, before it is processed
+     * to be sent to client.
+     *
+     * In particular, if a request contains batched operations, this hook is called once of each
+     * operation.
+     *
+     * Here, you can modify the result, to add monitoring or instrumentation extensions for example.
      */
     onExecutionResult?: OnExecutionResultHook<TServerContext>;
     /**
-     * Use this hook with your own risk. It is still experimental and may change in the future.
-     * @internal
+     * This hook is invoked after a GraphQL request has been processed and before the response is
+     * forwarded to the client. Here you can customize what transport/response processor format
+     * should be used for sending the result over the wire.
      */
     onResultProcess?: OnResultProcess<TServerContext>;
   };

website/src/pages/docs/features/envelop-plugins.mdx

@@ -130,8 +130,10 @@ stateDiagram-v2
       onContextBuilding --> onExecute
       onContextBuilding --> onSubscribe
 
-      onExecute --> onResultProcess
-      onSubscribe --> onResultProcess
+      onExecute --> onExecutionResult
+      onSubscribe --> onExecutionResult
+
+      onExecutionResult --> onResultProcess
 
       onResultProcess --> [*]
     }
@@ -143,15 +145,24 @@ stateDiagram-v2
 
 ### `onRequest`
 
-This hook is invoked for ANY incoming HTTP request. Here you can manipulate the request, create a
-short circuit before Yoga handles the request or apply security measures such as checking for access
-tokens etc.
+This hook is invoked for ANY incoming HTTP request. Here you can manipulate the request or create a
+short circuit before Yoga handles the request.
+
+<Callout type="warning">
+
+Exceptions thrown by this hook are not caught. This means they will buble up to the HTTP server
+underlying implementation.
+
+For example, the `node:http` server crashes the entire process on uncaught exceptions.
+
+Prefer `onRequestParse` when possible, or wrap the hook code in a `try` block.
+
+</Callout>
 
 **Example actions in this hook:**
 
 - Manipulate the request
 - Short circuit before Yoga handles the request
-- Apply security measures
 
 #### API
 
@@ -271,6 +282,22 @@ You can hook into before and after the GraphQL subscription is executed.
 - Collect metrics about execution time
 - Error logging/reporting
 
+### `onExecutionResult`
+
+This hook is invoked for each result produced for GraphQL operation, before it is processed to be
+sent to client.
+
+In particular, it is useful to handle batched operations. If a request contains batched operations,
+this hook is called once of each operation, while `onResultProcess` will be only called once for the
+entire request.
+
+Here, you can modify the result, to add monitoring or instrumentation extensions for example.
+
+**Example actions in this hook:**
+
+- Add metadata to results
+- Collect errors
+
 ### `onResultProcess`
 
 This hook is invoked after a GraphQL request has been processed and before the response is forwarded
@@ -288,6 +315,17 @@ This hook is invoked after a HTTP request (both GraphQL and NON GraphQL) has bee
 after the response has been forwarded to the client. Here you can perform any cleanup or logging
 operations, or you can manipulate the outgoing response object.
 
+<Callout type="warning">
+
+Exceptions thrown by this hook are not caught. This means they will buble up to the HTTP server
+underlying implementation.
+
+For example, the `node:http` server crashes the entire process on uncaught exceptions.
+
+Prefer `onRequestParse` when possible, or wrap the hook code in a `try` block.
+
+</Callout>
+
 **Example actions in this hook:**
 
 - Specify custom response format