How to provide type hints in JavaScript using JSDoc for Apollo Client based code?

I have trouble setting up type hints for my JavaScript code using JSDoc (trying to make this work with VSCode and WebStorm).

As first step, I converted GraphQL schema into set of JSDoc @typedef entries using @graphql-codegen/cli. For the sake of this conversation, lets talk about this one:

// schema.js

/**
 * @typedef {Object} Country
 * @property {string} code
 * @property {string} name
 */

Then, somewhere in my App.js I tried writing:

// App.js

const GET_COUNTRIES = gql`
  query GetCountries {
    countries {
      code
      name
    }
  }
`;

/**
 * @typedef {import("./schema").Country} Country
 * @typedef {import("@apollo/client").QueryResult} QueryResult

 * @returns {QueryResult<Country>}
 */
const useGetCountries = () => {
  return useQuery(GET_COUNTRIES);
};

However, it looks like the type definitions from schema.js are being ignored (both App.js and schema.js are in the same directory).

My question is this: is it possible to setup something like this – have IDE pickup JSDoc type definitions and provide type hints? If the answer is YES, how would I go around settings this up?

I’ve created a simple repro on CodeSandbox at https://codesandbox.io/s/graphql-type-hints-n1vh0

Answer

While I was unable to make this work using just JSDoc, I had a good success using the same @graphql-codegen/cli utility and generating .d.ts file instead. After that, I was able to provide correct type hints using the following code:

/**
 * @typedef {import("../types/schema").Country} Country
 * @typedef {import("../types/helpers").ApolloQueryResult<{countries: Country[]}>} QueryResult
 *
 * @returns {QueryResult}
 */
const useGetCountries = () => {
  return useQuery(GET_COUNTRIES);
};

I also implemented helpers.d.ts so that I can easily make fields of my choosing optional (unlike the built-int Partial type that makes all fiels optional) and make data filed of QueryResult optional as well (as in Apollo documentation. Didn’t had the time to figure out why it is not already in Apollo’s .d.ts)

type OptionalKey<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

export type ApolloQueryResult<TData = any, TVariables = any> = OptionalKey<
  QueryResult<TData, TVariables>,
  "data"
>;