JSDoc: specifying the type of an Object passed as a parameter?

Question

I have a method in a module. It takes an object that is an instance of a very specific class. For example:

    /** Validate a unit against the database's list of valid units
     * @param {Object} db - ???
     * @param {string} unit - unit to validate
     * @returns {Promise} Promise to query unit validation
     */
    validateUnit: (db, unit) => {
        return new Promise((resolve, reject) => {

I want to make it very clear that the db parameter is a Knex object as returned from require('knex')({...}).

It isn't, no. If use `@param {Knex}` it shows: https://i.imgur.com/PE7oq3e.png As I temporary workaround I'll just write "Knex object" in the description... but I'd really like to do it the "right way!" — SpidaFly, Nov 15 '19 at 06:28

score 0 · Answer 1 · answered Nov 15 '19 at 20:52

I think on balance I'd probably use typedef:

/**
 * @typedef {Function} Knex
 */

Note that Knex exports a function, not a Plain Ol' JavaScript Object. It does add properties to that function, and as we know in JS functions are also objects! However, if we do it this way, I think your IDE may display:

validateUnit(db: Function, unit: string)

which I gather is not really what you're after. If we do this:

/**
 * @typedef {Object} Knex
 * @property {Function} select - Select columns to retrieve
 * @see {@link https://knexjs.org|Documentation}
 */

we get:

You could go into as much detail as you like with the properties, or keep things simple. Someone may have already exhaustively JSDoc'd Knex for you, I haven't searched! Then you've got a type you can use for your params:

/** Validate a unit against the database's list of valid units
 * @param {Knex} db - database instance
 * @param {string} unit - unit to validate
 * @returns {Promise} Promise to query unit validation
 */

JSDoc: specifying the type of an Object passed as a parameter?

1 Answers1