feat: export execution algorithm implementation as Executor class

[yaacovCR]

Depends on #3196.

[yaacovCR]

#3185 has now been split into the following PR stack: #3192, #3195, #3196, and this PR: #3193

---

Summary:

#3192 introduces the GraphQLAggregateError that forms an independent feature for reporting multiple errors from a resolver, but also allows the buildExecutionContext method to always return a valid ExecutionContext, throwing when impossible, which allows the method to be used in the eventual Executor class constructor. The handleRawError method is introduced, which recognizes that errors may be aggregated.

#3195 moves the subscription code into the execution module -- at long last! -- bringing the reference implementation in line with the spec. Subscriptions within the spec are put on equal footing as queries and mutations, all three being operations that are targets for "execution," with the different execution algorithms further elaborated on within the "Execution" section of the spec. Code reuse is employed to good effect; for example, error handling for subscriptions is streamlined using the
same handleRawError method.

#3196 streamlines the buildExecutionContext function and related execution setup code to prepare for integration into the eventual Executor class constructor.

#3193 moves all of the "execution algorithm" functions to the Executor class. execute and subscribe are left as thin wrappers around the Executor class that construct an executor object and call executor.executeQueryOrMutation or executor.executeSubscription, respectively.

---

The subscribe function has been retained because of its different method signature/return type. We could consider introducing query and mutate functions to eventually replace execute so as to properly keep the operations on equal footing.

Thoughts?

[yaacovCR]

Of important note -- the Executor class is exported, which was the whole reason for this refactoring (!!!). The class is marked as internal, with a comment/warning similar to the Parser class as suggested by @IvanGoncharov (see #3163 (comment)).

[yaacovCR]

A final (?) thought -- the createSourceEventStream function used to be exported separately, which is no longer necessary, as it is included within the Executor class. This export would not seem to have to be covered by the warning attached to the class, but I am not quite sure how to indicate that and/or how to manage that within the code base. I think the code as is may be just as fine?

Suggestions, thoughts, ideas, conversation....all welcome.

[maraisr]

Wow this is so nice @yaacovCR 🙏🏻

Just dropping my 2 cents here; feel this is a really strong move for graphql. It'll allow consumers of this library to iterate much further in isolation with new and exciting features, that eventuate in upstream work. It'll enable defer/stream to become first-class in those areas, where the consumers understand the risk and accept it — without graphql committing to an api.

Completely opening up the internal Executor allows consumers to extend this and overload with their own functionality, which could lead to some exciting experiments and help accelerate adoption in communities who require a niche.

@IvanGoncharov please turn this into a reality for me <3

[yaacovCR]

Closed this in favor of PR stack 3293 => 3302.

[yaacovCR]

@maraisr

This is now available for experimentation at:
https://www.npmjs.com/package/graphql-executor
https://github.com/yaacovCR/graphql-executor