execute: integrate subscriptions and refactor pipeline #3644

yaacovCR · 2022-06-14T10:08:23Z

execute no longer runs the query algorithm for subscription operations. Rather, subscription operations are performed, as per the spec. subscribe and createSourceEventStream are removed.

See additional comments below.

netlify · 2022-06-14T10:08:40Z

✅ Deploy Preview for compassionate-pike-271cb3 ready!

Name	Link
🔨 Latest commit	`3f69fb3`
🔍 Latest deploy log	https://app.netlify.com/sites/compassionate-pike-271cb3/deploys/62bb53b590545b0008a5aa4b
😎 Deploy Preview	https://deploy-preview-3644--compassionate-pike-271cb3.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site settings.

github-actions · 2022-06-14T10:09:04Z

Hi @yaacovCR, I'm @github-actions bot happy to help you with this PR 👋

Supported commands

Please post this commands in separate comments and only one per comment:

@github-actions run-benchmark - Run benchmark comparing base and merge commits for this PR
@github-actions publish-pr-on-npm - Build package from this PR and publish it on NPM

@IvanGoncharov

The `execute`/`executeImpl` and `createSourceEventStream`/`createSourceEventStreamImpl` functions follow the same basic pattern of building the contet and using it to run a function. This PR extracts that pattern into a separate function. For good measure, the same pattern in applied to the soon-to-be-deprecated `subscribe` function. Hheavier refactoring is on the way from @IvanGoncharov (see graphql#3639 (review)), but in the meantime, this consolidates the common pattern without any breaking changes.

...to executeSubscriptionRootField => because that's what it does!

...because that's what it does! The execution of an operation returns a map of data/errors, not just the data.

`execute` no longer runs the query algorithm for subscription operations. Rather, subscription operations are performed, as per the spec. `subscribe` is deprecated.

to replace the old exported functionality from execute

separates internal errors array from the remainder of the Execution data. obviates the need for the buildPerEventExecutionContext function => as described by the spec, all execution info is the same for execution of subscription events except for the root value, which is set as the payload the separate executionContext variable introduced is similar to the payloadContext that will be necessary to support defer/stream

Advanced clients setting up services that only process subscriptions should be encouraged to create a custom ExecutionInfo object and use the corresponding internal functions that take ExecutionInfo objects rather than raw arguments. These functions are currently createSourceEventStreamImpl and executeQuery but when createSourceEventStream is removed, reateSourceEventStreamImpl will be renamed to createSourceEventStream

in favor of the corresponding functions that take ExecutionInfo arguments, i.e. createSourceEventStreamImpl and executeQuery. Note that since createSourceEventStream has been removed, createSourceEventStreamImpl can be renamed to createSourceEventStream, so that the recommended function name has not in fact changed, buf the function now takes an ExecutionInfo argument

…he default

yaacovCR · 2022-06-29T05:44:13Z

Now that #3658 suggests that we may be awaiting a serious refactor, this PR has been reworked to represent a least change approach to the existing API. Rather than list the individual steps to the granularity of every renamed function, I will just list broadly what the PR accomplishes, after which I will list what the PR does not do.

updates execute to run the full ExecuteSubscription algorithm rather than just ExecuteSubscriptionEvent, updating the return types of execute and graphql
removes subscribe/createSourceEventStream (these would have to be deprecated in a 16.x release).
introduces DocumentInfo and ExecutionInfo interfaces that advanced clients can use to analyze a document and set up execution parameters. Internal errors variable -- the only necessarily private information required during execution -- is left within ExecutionContext. This is generally similar to the setup within defer/stream with payload context objects, so the separate variable is not much of an issue (in my opinion).
export helpers buildDocumentInfo, coerceVariableValues, as well as buildExecutionInfo so that advanced clients can have some help creating parts or all of the DocumentInfo/ExecutionInfo.
expose helpers executeQuery, executeMutation, executeSubscription, and createSourceEventStream which take ExecutionInfo rather than ExecutionContext objects. These functions return appropriately typed versions, i.e. executeQuery/executeMutation do not ever return streams (until defer/stream) merged.
no need anymore for the newly introduced *Impl functions within execute

What this PR does not do:

compile schemas/documents/field collections/variables/arguments
provide runtime or type checks for the arguments to executeQuery, etc. I.e. executeQuery can only take an ExecutionInfo object with an operation that is of type QUERY (for ExecuteQuery) or SUBSCRIPTION (for ExecuteSubscriptionEvent). executeMutation should only work for info objects containing a MUTATION, and executeSubscription and createSourceEventStream should only work for info objects containing a SUBSCRIPTION. That is because that TS does not (yet?) support discriminated unions via nested properties and so it's not as easy to do without introducing repetitive type guards that drill down into the ExecutionInfo object or an additional somewhat unnecessary property on ExecutionInfo itself. Considering the type safety comes at a runtime expense, I am forgoing this for now.

yaacovCR · 2022-06-29T05:45:46Z

The new exported helpers have not yet been exported from main, and are only available via deep imports. That can/should change once the API is finalized.

yaacovCR · 2022-06-29T05:51:55Z

Ah => I forgot to mention that I have also snuck in here a new argument to allow total customization of the executor used by EXECUTE_SUBSCRIPTION_EVENT.

As well as a default executor:

export const defaultSubscriptionEventExecutor = (
  exeInfo: ExecutionInfo,
  payload: unknown,
): PromiseOrValue<ExecutionResult> =>
  executeQuery({
    ...exeInfo,
    rootValue: payload,
  });

This workflow allows the buildPerEventExecutionContext function to be removed.

yaacovCR · 2024-10-01T11:14:43Z

Closing this for now in favor of plan in #4210

to safely export buildExecutionContext() as validateExecutionArgs() motivation: this will allow us to: 1. export `executeOperation()` and `executeSubscription()` for those who would like to use directly. 2. add a `perEventExecutor` option to `ExecutionArgs` that allows one to pass a custom context for execution of each execution event, with the opportunity to clean up the context on return, a la #2485 and #3071, addressing #894, which would not require re-coercion of variables. The signature of the `perEventExecutor` option would be: ```ts type SubscriptionEventExecutor = ( validatedExecutionArgs: ValidatedExecutionArgs): PromiseOrValue<ExecutionResult> ``` rather than: ```ts type SubscriptionEventExecutor = ( executionArgs: ExecutionArgs): PromiseOrValue<ExecutionResult> ``` This might be a first step to integrating `subscribe()` completely into `execute()` (see: #3644) but is also a reasonable stopping place.

to safely export buildExecutionContext() as validateExecutionArgs() motivation: this will allow us to: 1. export `executeOperation()` and `executeSubscription()` for those who would like to use directly. 2. add a `perEventExecutor` option to `ExecutionArgs` that allows one to pass a custom context for execution of each execution event, with the opportunity to clean up the context on return, a la #2485 and #3071, addressing #894, which would not require re-coercion of variables. The signature of the `perEventExecutor` option would be: ```ts type SubscriptionEventExecutor = ( validatedExecutionArgs: ValidatedExecutionArgs): PromiseOrValue<ExecutionResult> ``` rather than: ```ts type SubscriptionEventExecutor = ( executionArgs: ExecutionArgs): PromiseOrValue<ExecutionResult> ``` This might be a first step to integrating `subscribe()` completely into `execute()` (see: graphql/graphql-js#3644) but is also a reasonable stopping place.

n1ru4l approved these changes Jun 14, 2022

View reviewed changes

yaacovCR force-pushed the make-execute-happen branch 4 times, most recently from ce28d68 to dc3b18d Compare June 14, 2022 10:50

yaacovCR requested a review from a team June 14, 2022 10:51

yaacovCR added the PR: breaking change 💥 implementation requires increase of "major" version number label Jun 14, 2022

yaacovCR mentioned this pull request Jun 19, 2022

refactor: use exeContext strategically #3654

Merged

yaacovCR force-pushed the make-execute-happen branch 8 times, most recently from 393bdfc to eaf786d Compare June 21, 2022 20:36

yaacovCR mentioned this pull request Jun 22, 2022

introduce executeSubscriptionEvent #3657

Closed

yaacovCR force-pushed the make-execute-happen branch 4 times, most recently from cbd99b5 to 6946681 Compare June 22, 2022 19:31

yaacovCR mentioned this pull request Jun 23, 2022

refactor: DRY with context building and *Impl functions #3656

Closed

yaacovCR force-pushed the make-execute-happen branch from a198622 to f18583f Compare June 24, 2022 08:25

yaacovCR added 5 commits June 24, 2022 12:09

refactor: rename executeSubscription to executeSubscriptionRootField

0d297d9

...to executeSubscriptionRootField => because that's what it does!

refactor: rename executeOperation to executeQueryOrMutationRootFields

3e65a54

...because that's what it does! The execution of an operation returns a map of data/errors, not just the data.

execute: integrate subscriptions

a9a078c

`execute` no longer runs the query algorithm for subscription operations. Rather, subscription operations are performed, as per the spec. `subscribe` is deprecated.

introduce executeSubscriptionEvent

9fc1d93

to replace the old exported functionality from execute

yaacovCR force-pushed the make-execute-happen branch from f18583f to 9fc1d93 Compare June 24, 2022 09:14

yaacovCR mentioned this pull request Jun 24, 2022

alternative refactor #3660

Closed

yaacovCR added 8 commits June 28, 2022 21:38

export buildDocumentInfo and coerceVariableValues helpers

60684ee

remove deprecated subscribe function

0753246

remove unnecessary function prepareContextAndRunFn

6b5bddb

export additional helpers

2bbae47

allow customization of execution for subscription events and export t…

3f69fb3

…he default

yaacovCR requested review from a team and removed request for a team June 29, 2022 08:16

yaacovCR changed the title ~~execute: integrate subscriptions~~ execute: integrate subscriptions and refactor pipeline Jul 21, 2022

yaacovCR mentioned this pull request Jul 21, 2022

Allow separation of variable value coercion from the rest of execution #3679

Closed

yaacovCR mentioned this pull request Oct 1, 2024

introduce ValidatedExecutionArgs #4210

Merged

yaacovCR closed this Oct 1, 2024

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

execute: integrate subscriptions and refactor pipeline #3644

execute: integrate subscriptions and refactor pipeline #3644

yaacovCR commented Jun 14, 2022 •

edited

Loading

netlify bot commented Jun 14, 2022 •

edited

Loading

github-actions bot commented Jun 14, 2022

yaacovCR commented Jun 29, 2022 •

edited

Loading

yaacovCR commented Jun 29, 2022

yaacovCR commented Jun 29, 2022 •

edited

Loading

yaacovCR commented Oct 1, 2024

execute: integrate subscriptions and refactor pipeline #3644

execute: integrate subscriptions and refactor pipeline #3644

Conversation

yaacovCR commented Jun 14, 2022 • edited Loading

netlify bot commented Jun 14, 2022 • edited Loading

✅ Deploy Preview for compassionate-pike-271cb3 ready!

github-actions bot commented Jun 14, 2022

yaacovCR commented Jun 29, 2022 • edited Loading

yaacovCR commented Jun 29, 2022

yaacovCR commented Jun 29, 2022 • edited Loading

yaacovCR commented Oct 1, 2024

yaacovCR commented Jun 14, 2022 •

edited

Loading

netlify bot commented Jun 14, 2022 •

edited

Loading

yaacovCR commented Jun 29, 2022 •

edited

Loading

yaacovCR commented Jun 29, 2022 •

edited

Loading