Great examples of advanced JSDoc annotations.

Advanced JSDoc Annotations.md

Dynamic Return Based On Object Key/Value Pairs

/**
 * @typedef {{
 *   text: {text: string};
 *   numbers: {number: number};
 *   date: {date: string, time: string};
 * }} ColumnTypeMap
 */

/**
 * @typedef {{
 *   id: string;
 *   name: string;
 * }} StandardFields
 */

/**
 * @template {Record<string, string>} TColumns
 * @typedef {StandardFields & {
 *   [K in keyof TColumns]:
 *     TColumns[K] extends keyof ColumnTypeMap
 *       ? ColumnTypeMap[TColumns[K]]
 *       : any
 * }} QueryResult
 */

/**
 * @template {Record<string, string>} TColumns
 * @param {{
 *   boardId: number;
 *   itemIds?: number[];
 *   columns: TColumns;
 * }} options
 * @returns {Promise<QueryResult<TColumns>[]>}
 */
async function queryRecords(options) {
  return [];
}

const results = await queryRecords({
  boardId: 29384,
  itemIds: [1, 2],
  columns: /** @type {const} */ ({
    first_name: 'text',
    middle_name: 'text',
    last_name: 'text',
    age: 'numbers',
    dob: 'date',
    news______tuff: 'something-else'
  })
});

results[0].id // string
results[0].name // string
results[0].age // {number: number}
results[0].dob // {date: string, time: string}
results[0].first_name // {text: string}
results[0].last_name // {text: string}
results[0].middle_name // {text: string}
results[0].news______tuff // any