feat(dc): Add executeQuery and executeMutation APIs to Data Connect

[stephenarosaj]

API Changes

• Added executeQuery() and executeMutation() to src/data-connect/data-connect.ts. These allow users to call deployed operations with impersonated auth credentials.

Testing

• New unit tests added which match the coverage of existing executeGraphql* APIs
• New integration tests added which more than match the coverage of existing executeGraphql* APIs
• The tests pass locally, but a re-deploy of dataconnect to the CI/CD firebase project is required. Tagging @lahirumaramba

[stephenarosaj]

Note:

The integration tests have a huge diff because I moved the existing tests under a new parent describe(), and so their indentation level was increased. Existing tests were not changed in this PR.

[stephenarosaj]

Forgot a few changes! Didn't know that you could close and re-open :P thanks Yuchen!

[stephenarosaj]

wait - need to privatize the execute API, execution should come from operation refs (in a future PR)

[maneesht]

Note: These changes likely require a re-deploy on the CI project

[stephenarosaj]

Yes, they deff do - I'll leave this comment open to make sure it gets re-deployed! Tagging @lahirumaramba

[maneesht]

@lahirumaramba Any opinions on this? We only need this for the generated SDK, and we don't intend for developers to use this.

[lahirumaramba]

Good point, is there a way to not export this from the public API surface?

[lahirumaramba]

Does this handle the method overload correctly? If I call executeQuery('myQuery', { impersonate: ... }) would it take options as variables?

[lahirumaramba]

If that breaks the method overload we need to perform a runtime check to differentiate them.

public executeQuery<Data, Variables>(
  name: string,
  variablesOrOptions?: Variables | OperationOptions,
  options?: OperationOptions
): Promise<ExecuteOperationResponse<Data>> {

[stephenarosaj]

@lahirumaramba i added some unit tests in test/unit/data-connect/data-connect.spec.ts - your suspicion is correct, without type parameters (for required or fully optional variables), the second parameter is always treated as variables. however, i believe this is WAI, and i'd like to know how you feel about keeping this behavior?

there are no options in our Client SDK, so we don't run into this issue there, but we do have options in our React / Angular SDKs, and they do have this behavior (see our React SDK's README description). our solution was to clearly document this and to always use type parameters in our generated code, because we didn't want to try and identify "these fields mean this must be an options object, and this one must be a variables object", since users can use any name for variable fields in their GQL files

also, while the IDE won't pick up on the error, the backend / emulators will reject requests which omit required variables or provide unrecognized variables for that specific operation. here's what shows up when testing out this scenario:

{
  errorInfo: {
    code: 'data-connect/query-error',
    message: '$id (String) is missing $impersonate is not expected (did you mean id?)'
  },
  codePrefix: 'data-connect'
}

lmk your thoughts :P

[lahirumaramba]

If that breaks the method overload we need to perform a runtime check to differentiate them.

public executeQuery<Data, Variables>(
  name: string,
  variablesOrOptions?: Variables | OperationOptions,
  options?: OperationOptions
): Promise<ExecuteOperationResponse<Data>> {

[lahirumaramba]

If this function is only for internal usage let's not export it to the public API surface here

[lahirumaramba]

Is this interface identical to ExecuteGraphqlResponse? If that is the case and if we don't see it changing in the future, it might be better to create a type alias.

export type ExecuteOperationResponse<T> = ExecuteGraphqlResponse<T>;