Como gerar JSDoc para a função `pipe`d ES6

Eu tenho uma função no estilo ES6 que é definida usando a composição de funções com asyncPipe.

import { getItemAsync } from 'expo-secure-store';

const asyncPipe = (...fns) => x => fns.reduce(async (y, f) => f(await y), x);

const getToken = () => getItemAsync('token');

const liftedGetToken = async ({ ...rest }) => ({
  token: await getToken(),
  ...rest,
});

const liftedFetch = ({ body, route, token, method = 'GET' } = {}) =>
  fetch(route, {
    ...(body && { body: JSON.stringify(body) }),
    headers: {
      'Content-Type': 'application/json',
      ...(token && { Authorization: `Bearer ${token}` }),
    },
    method,
  });

const json = res => res.json();

/**
 * @method
 * @param {Object} fetchSettings the settings for the fetch request
 * @param {Object} fetchSettings.body the body of the request
 * @param {string} fetchSettings.route the URL of the request
 * @param {string} fetchSettings.method the method of the request
 * @param {string} fetchSettings.token should only be used for testing and unauthenticated requests
 */
const request = asyncPipe(liftedGetToken, liftedFetch, json);

Como você pode ver, tentei adicionar uma descrição JSDoc a ele. Mas quando eu o uso em qualquer lugar, meu editor, VSCode, não sugere seus parâmetros. Como você declara esses tipos de funções com o JSDoc? E como obtenho parâmetros para esta função funcionar com o Intellisense?

O VSCode usa o mecanismo TypeScript sob o capô, o que não é bom para inferir tipos de composições de funções e, como você viu, não reconhece uma composição sem pontos como uma declaração de função.

Se você quiser dicas de tipo, poderá especificar os argumentos para a função composta envolvendo uma função pontiaguda em torno dela.

Eu escreveria algo assim - note: os valores padrão tornam o JSDoc desnecessário para dicas de tipo, mas você pode manter o JSDoc para as descrições de qualquer maneira. Verifique também se as falhas causadas por fallbacks de valor padrão produzem mensagens de erro adequadas.

/**
  * http request with JSON parsing and token management.
  * @param {Object} fetchSettings the settings for the fetch request
  * @param {Object} fetchSettings.body the body of the request
  * @param {string} fetchSettings.route the URL of the request
  * @param {string} fetchSettings.method the method of the request
  * @param {string} fetchSettings.token should only be used for testing and unauthenticated requests
  */
const request = ({
  body = {},
  route = '',
  method = 'GET',
  token = ''
}) => asyncPipe(liftedGetToken, liftedFetch, json)({
  body, route, method, token
});

O VSCode tentará exibir o comentário da função anônima dentro asyncPipe. Se você adicionar um comentário JSDoc, poderá ver o comportamento:

const asyncPipe = (...fns) =>
  /**
   * My asyncPipe description
   * @param {Object} x Any object
   */
  x => fns.reduce(async (y, f) => f(await y), x);

const request = asyncPipe(liftedGetToken, liftedFetch, json);

Infelizmente, no JSDoc, não há como substituir a documentação da função anônima como você estava tentando fazer. No entanto, você pode forçar sua intenção ao VSCode dessa maneira, observe que isso introduz uma chamada de função extra:

const doRequest = asyncPipe(liftedGetToken, liftedFetch, json);

/**
 * @method
 * @param {Object} fetchSettings the settings for the fetch request
 * @param {Object} fetchSettings.body the body of the request
 * @param {string} fetchSettings.route the URL of the request
 * @param {string} fetchSettings.method the method of the request
 * @param {string} fetchSettings.token should only be used for testing and unauthenticated requests
 */
const request = fetchSettings => doRequest(fetchSettings);