Incompatible type notation in JSDoc for Google Apps Script online vs locally

Question

Consider the following script

function caller(){
  getSpreadsheet1();// only the online IDE understands this
  getSpreadsheet2();// only the local IDE (VS Code) understands this
}

/**
 * @returns {SpreadsheetApp.Spreadsheet}
 */
function getSpreadsheet1(){
  var spreadsheet = SpreadsheetApp.openById('');
  return spreadsheet;
}

/**
 * @returns {GoogleAppsScript.Spreadsheet.Spreadsheet}
 */
function getSpreadsheet2(){
  var spreadsheet = SpreadsheetApp.openById('');
  return spreadsheet;
}

If you paste this script into the (new) Google Apps Script IDE, placing a period (.) after getSpreadsheet1() will trigger the IDE to display the member functions of class Spreadsheet, like addEditor(), for the sake of auto-completion. That is to say, the online IDE understands the type of getSpreadsheet1().

I have tried to achieve the same behaviour locally. I copied the script to a local file and I ran npm i -S @types/google-apps-script in the same folder, as per this guide. However, I get no autocompletion when placing a period after getSpreadsheet1(), but instead I only get it after placing the period after getSpreadsheet2().

Note that my local IDE (VS Code) does understand the type of SpreadsheetApp.openById(''), so that does seem to work correctly.

Is there a way to get my local IDE to understand the JSDoc comments that use the types like SpreadsheetApp.Spreadsheet required by the online IDE?

Answer 1

Besides removing the @returns completely to let Typescript infer the result type automatically it's possible to make it work in both cases with the following trick:

function caller() {
    getSpreadsheet1();// only the online IDE understands this
    getSpreadsheet2();// only the local IDE (VS Code) understands this
}

/**
 * @typedef {ReturnType<typeof SpreadsheetApp['openById']>} Spreadsheet
 */

/**
 * @returns {Spreadsheet}
 */
function getSpreadsheet1() {
    var spreadsheet = SpreadsheetApp.openById('');
    return spreadsheet;
}

/**
 * @returns {Spreadsheet}
 */
function getSpreadsheet2() {
    var spreadsheet = SpreadsheetApp.openById('');
    return spreadsheet;
}