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

[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]

Thanks for the additional context. I think it could create a confusion to the users if we break the method overload here. Does it make sense to try an approach similar to what we did in Firestore?

firebase-admin-node/src/firestore/index.ts

Line 154 in 8c9895e

export function getFirestore(

[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]

Thanks for the additional context. I think it could create a confusion to the users if we break the method overload here. Does it make sense to try an approach similar to what we did in Firestore?

firebase-admin-node/src/firestore/index.ts

Line 154 in 8c9895e

export function getFirestore(