为创建动态类的函数添加 JSDoc 返回类型

/**
 * Creates a new class that extends the given base class. The new class
 * will have additional methods 'bindServerSocket' and 'onConnect'.
 *
 * @template T - The base class to extend.
 * @param {new(...args: any[]) => T} UserProvidedClass - The class to be extended.
 * @returns {new(...args: any[]) => T & ClientClassMethods} - A new class that extends the UserProvidedClass and adds new methods.
 */
function createClientClass(UserProvidedClass) {
  return class ClientClass extends UserProvidedClass {
    bindServerSocket(socket) {
      this.server = socket;
      this.onConnect();
    }
    onConnect() {
      super.onConnect?.();
      if (DEBUG) console.log(`client connected`);
    }
  };
}

/**
 * This is a helper type that defines additional methods added by ClientClass.
 * @typedef {Object} ClientClassMethods
 * @property {Function} bindServerSocket - Method to bind a server socket.
 * @property {Function} onConnect - Method called on connection.
 */

// Usage Example:
const instance = createClientClass(CustomClass);
instance.bindServerSocket(new WebSocket('ws://localhost:8000'));
instance.testServer();

This appears to not officially be possible due to there not being any official JSDoc syntax for indicating that a parameter or return is for "an actual class definition" rather than for "an instance of some class".

There are a number of issues about this on the JSDoc issue tracker, with the most appropriate appearing to be issue 1349, "Document class types/constructor types", filed in 2017, which has not been resolved as of the time of this post in late 2023.

See Julio's answer for a possible approach, but note that there do not appear to be any official or even unofficial docs for the typing tricks used, and so that may or may not work for you depending on when you find this post, or the tooling you're using.

(VS Code with the source marked as TypeScript to maximize type-awareness, for instance, can tell that is defined in the function, but cannot tell that is defined in instance.bindServerSocket()createClientClassinstance.test()CustomClass)

The return type can only be properly defined if , or a corresponding (the equivalent of an interface), is not hidden inside .ClientClasstypedefcreateClientClass

Below is some code, simply using a , that seems to do the trick (tested at playcode.io). Also, you had a error in your code: returns a constructor, not an instance.typedefcreateClientClass

By the way, I find your construction a bit "suspect", but I don't know your actual design requirements, and I have only replied to your direct question.

/**
 * Represents the 'ClientClass' component of
 * the return type of {@link createClientClass}.
 * 
 * @typedef IClientClass
 * @type {object}
 * @property {(socket: string) => void} bindServerSocket
 */

/**
 * Returns a class of type {@link IClientClass} that
 * extends the given {@link UserProvidedClass}.
 * 
 * @template {class} T
 * @param {abstract new () => T} UserProvidedClass
 * @returns {new () => IClientClass & T}
 */
function createClientClass(UserProvidedClass) {
  return class ClientClass extends UserProvidedClass {
    bindServerSocket(socket) {
      this.server = socket;
    }
  };
}

// And then an example of how this gets used:

class CustomClass {
  testServer() {
    console.log(`instance has server:`, !!this.server);
  }
}

// create the constructor
const clientClass = createClientClass(CustomClass);

// create an instance
const clientInstance = new clientClass();

// check methods are visible
clientInstance.bindServerSocket("1");
clientInstance.testServer();

A side note about "reputable sources": it is not even possible here to link to the reference documentation since 1) the JSDoc reference documentation is minimal to say the least and in fact not at all exhaustive; moreover, 2) most tooling actually leverages TypeScript for parsing JSDoc typing annotations and checking code, so results are not strictly determined by JSDoc anyway, results here are more of a half way between what JSDoc is supposed to offer and the support that TS engines actually give to typing annotations. And none of that is properly documented anywhere.