JsDoc：如何記錄對象可以具有任意（未知）屬性但具有特定類型？

Question

這與問題 30360391類似。 我想表達一個函數的參數是一個普通的 JS 對象，它可以具有任意屬性（未知）名稱，但所有屬性都是具有固定屬性的對象本身。

一個例子：函數就是這樣

/**
 * @param {Descriptor} desc
 */
function foo( desc ) {
  // ...
}

一個典型的desc看起來像

desc = {
  unknownEntity1: {
    priority: 5;
    writable: false;
  },
  unknownEntity2: {
    priority: 42;
    writable: true;
  },
  unknownEntity3: {
    priority: 9;
    writable: false;
  }
}

我已經有了

/**
 * @typedef {Object} DescriptorEntry
 * @property {number} priority - The priority of the entity
 * @property {boolean} writable - True, if the entity can be modified
 */

我仍然需要一個用於Descriptor的typedef ，它基本上表示 Descriptor 是一個具有任意屬性但所有類型為DescriptorEntry 。 作為偽代碼，它將類似於

/**
 * @typedef {Object} Descriptor
 * @property {DescriptorEntry} *
 */

當然，星號*作為“任何屬性”的通配符是無效的 Jsdoc 語法。 但是我該如何正確地做到這一點？

Answer 1

根據http://usejsdoc.org/tags-type.html ，從 JSDoc 3.2 開始，JSDoc 已經完全支持 Google Closure Compiler 類型表達式。 http://usejsdoc.org/tags-type.html#jsdoc-types描述了一種這樣的格式：

{Object.<string, number>}

所以在你的情況下，你應該能夠做到：

/**
 * @typedef {Object.<string, DescriptorEntry>} Descriptor
 */

或者只是：

/**
 * @typedef {{string, DescriptorEntry}} Descriptor
 */

你甚至可以替換string用其自己的類型在上面的例子，如果你想有一個特殊類型，稱為DescriptorName或這樣或細節允許的字符串值。

但是，有一個注意事項。 至少在我的情況下，雖然 JSDoc 沒有拒絕后一種格式，至少使用默認模板，但它僅將其顯示為“對象”而沒有任何特殊細節。 但是，第一種格式顯示正確。

Answer 2

這是PropertyDescriptor和PropertyDescriptorMap Typescript 接口。 （它們也被 PhpStorm 2020 用於代碼完成）： TypeScript/lib/lib.es5.d.ts

interface PropertyDescriptor {
    configurable?: boolean;
    enumerable?: boolean;
    value?: any;
    writable?: boolean;
    get?(): any;
    set?(v: any): void;
}

interface PropertyDescriptorMap {
    [s: string]: PropertyDescriptor;
}

您可以直接將它們用作@type {}或重新定義兩者：

/**
 * @typedef {Object} PropertyDescriptor
 * @property {function(v: *): void} [set]             - Set [name](v){...}      'accessor descriptor' only
 * @property {function(): *}        [get]             - Get [name](){...}       'accessor descriptor' only
 * @property {undefined|*}          [value]           - Value (primitive|func)  valid in 'data descriptor' only
 * @property {undefined|boolean}    [writable]        - Writable                valid in 'data descriptor' only
 * @property {undefined|boolean}    [configurable]    - Configurable            valid in 'data && accessor - descriptor'
 * @property {undefined|boolean}    [enumerable]      - Enumerable              valid in 'data && accessor - descriptor'
 */

/**
 * @typedef {Object<string,PropertyDescriptor>} PropertyDescriptorMap
 */

/**
 *  @type {PropertyDescriptor} myDescriptor
 */
let myDescriptor = {
    configurable: true,
    enumerable: true,
    // value: {},
    // writable: true,
    get myGet(){},
    set myGet(v){}
};