[Feedback] `API.graphql` return signature is hard to use in TypeScript

Is your feature request related to a problem? Please describe.

When I try to await an API.graphql call in TS, I get this:

This is because you have defined the graphql method to also return an Observable in case of a subscription:

https://github.com/aws-amplify/amplify-js/blob/b5d14124dfd5f1000f102ac8c84aa964c9d916c5/packages/api/src/API.ts#L173-L178

This is understandable but makes it very annoying to use, particularly because if i need to assert types, the GraphQLResult type is not also exported for me to use.

Describe the solution you’d like

use overloading and/or a different function for subscriptions to make this experience easier.

ultimately i want to be able to write this:

const query = await API.graphql<TodoType[]>({query: listTodos})

and it should not complain. (a REALLY good experience, ofc, would give me that return type for free based on listTodos, but that would involve a much deeper redesign)

[sw-yx]

for those finding this… heres how to write a vaguely ergonomic wrapper around this.

import { GraphQLOptions} from '@aws-amplify/api-graphql'
async function gql<T extends object>(options: GraphQLOptions, additionalHeaders?: {
  [key: string]: string;
}): Promise<GraphQLResult<T>> {
  const query = API.graphql(options, additionalHeaders) as Promise<GraphQLResult<T>>
  return query
}

usage:

  const [todos, setTodos] = React.useState<TodoType[]>([])
  React.useEffect(() => {
    const query = gql<TodoType[]>({query: listTodos})
    query.then(({data}) => setTodos(data || []))
  })

[sw-yx]

Secondly, specifying the return signature like this:

https://github.com/aws-amplify/amplify-js/blob/b5d14124dfd5f1000f102ac8c84aa964c9d916c5/packages/api/src/API.ts#L173-L178

always assigns the generic type T to be object because that is how the GraphQLResult interface is designed. This causes nasty, nasty type errors when people try to assign the results of the graphql query to a properly typed variable:

more info on this error here: https://stackoverflow.com/questions/56505560/could-be-instantiated-with-a-different-subtype-of-constraint-object

but TLDR:

i would recommend making graphql a generic as well so I can pass along the type i want:

// pseudocode, modified from source slightly
	graphql<T = object>(
		options: GraphQLOptions,
		additionalHeaders?: { [key: string]: string }
	): Promise<GraphQLResult<T>> | Observable<object> {
		return this._graphqlApi.graphql(options, additionalHeaders);
	}