JsDoc: How do I document that an object can have arbritrary (unknown) properties but with a particular type?

Question

This is a similar to question 30360391. I want to express that the parameter of a function is a plain JS object that can have arbitrary properties (with unknown) names but all properties are objects themselves with fixed properties.

An example: The function is just like this

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

and a typical desc looks like

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

I already have

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

I still need a typedef for Descriptor that basically express that Descriptor is an object with arbitrary properties but all of type DescriptorEntry. As pseudo-code it would be something like

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

Of course, the asterisk * as a wildcard for "any property" is invalid Jsdoc syntax. But how do I do it correctly?

Repentance

Answer 1

Per https://jsdoc.app/tags-type.html , as of JSDoc 3.2, JSDoc has had full support of Google Closure Compiler type expressions. One such format is described at https://jsdoc.app/tags-type.html#jsdoc-types :

{Object.<string, number>}

So in your case, you should be able to do:

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

or just:

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

You could even replace string in the above examples with its own type, if you wanted to have a special type called DescriptorName or such and detailing the allowable string values.

One note, however. In my case at least, while JSDoc is not rejecting the latter format, at least with the default template, it is only showing it as an "Object" without any special details. The first format is shown correctly, however.

Jacquejacquelin

This doesn't work in PHPStorm as of 2020.3.1. I still get the "Possible iteration over custom/inherited properties" diagnostic when I do for(let key in desc). – Lonna

Today one may reference jsdoc.app/tags-type.html, as usejsdoc.org is no longer. – Undercool

Answer 2

These are Typescript Interfaces for PropertyDescriptor and PropertyDescriptorMap. (They are also used by PhpStorm 2020 for code completion): 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;
}

You could either use them directly as @type {} or re-define both:

/**
 * @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){}
};

Micropyle