Generate types from JSDoc comments with TypeScript compiler. (#415)

* Generate types from JSDoc comments with TypeScript compiler.

* minor edit

* - Use import('child_process').ForkOptions and import('worker_threads').WorkerOptions
- Remove the WorkerOptions definition, which is already defined by default.

* Change to private

* Fix types

* Add tests for type generation.

* Edit a test

* Tweak the way of exporting Promise to make the generated types compatible with @types/workerpool.

* minor edit

Author: tamuratak

.gitignore

@@ -1,3 +1,5 @@
+/types
+
 # Logs
 logs
 *.log

package-lock.json

@@ -18,6 +18,7 @@
   ],
   "main": "src/index.js",
   "browser": "dist/workerpool.js",
+  "types": "types/index.d.ts",
   "files": [
     "dist",
     "src",
@@ -26,14 +27,17 @@
     "README.md"
   ],
   "scripts": {
-    "build": "rollup -c rollup.config.mjs",
+    "build": "rollup -c rollup.config.mjs && npm run build:types",
+    "build:types": "tsc -p .",
     "watch": "rollup -c rollup.config.mjs -w",
-    "test": "npm run build && mocha test",
+    "test": "npm run build && mocha test && npm run test:types",
+    "test:types": "tsc -p test/types",
     "test:debug": "npm run build && mocha debug test",
     "coverage": "npm run build && c8 mocha && c8 report --reporter=html && echo Coverage report is available at ./coverage/index.html",
     "prepublishOnly": "npm run test"
   },
   "devDependencies": {
+    "@types/node": "20.10.4",
     "@babel/core": "7.23.5",
     "@babel/preset-env": "7.23.5",
     "@rollup/plugin-babel": "6.0.4",
@@ -46,6 +50,7 @@
     "fs-extra": "11.2.0",
     "find-process": "1.4.7",
     "mocha": "10.2.0",
-    "rollup": "4.6.1"
+    "rollup": "4.6.1",
+    "typescript": "5.3.3"
   }
 }

package.json

@@ -1,44 +1,62 @@
-var Promise = require('./Promise');
+var {Promise} = require('./Promise');
 var WorkerHandler = require('./WorkerHandler');
 var environment = require('./environment');
 var DebugPortAllocator = require('./debug-port-allocator');
 var DEBUG_PORT_ALLOCATOR = new DebugPortAllocator();
 /**
- * A pool to manage workers
+ * A pool to manage workers, which can be created using the function workerpool.pool.
+ *
  * @param {String} [script]   Optional worker script
- * @param {WorkerPoolOptions} [options]  See docs
+ * @param {import('./types.js').WorkerPoolOptions} [options]  See docs
  * @constructor
  */
 function Pool(script, options) {
   if (typeof script === 'string') {
+    /** @readonly */
     this.script = script || null;
   }
   else {
     this.script = null;
     options = script;
   }
 
+  /** @private */
   this.workers = [];  // queue with all workers
+  /** @private */
   this.tasks = [];    // queue with tasks awaiting execution
 
   options = options || {};
 
+  /** @readonly */
   this.forkArgs = Object.freeze(options.forkArgs || []);
+  /** @readonly */
   this.forkOpts = Object.freeze(options.forkOpts || {});
+  /** @readonly */
   this.workerOpts = Object.freeze(options.workerOpts || {});
+  /** @readonly */
   this.workerThreadOpts = Object.freeze(options.workerThreadOpts || {})
+  /** @private */
   this.debugPortStart = (options.debugPortStart || 43210);
+  /** @readonly @deprecated */
   this.nodeWorker = options.nodeWorker;
+  /** @readonly
+   * @type {'auto' | 'web' | 'process' | 'thread'}
+   */
   this.workerType = options.workerType || options.nodeWorker || 'auto'
+  /** @readonly */
   this.maxQueueSize = options.maxQueueSize || Infinity;
+  /** @readonly */
   this.workerTerminateTimeout = options.workerTerminateTimeout || 1000;
 
+  /** @readonly */
   this.onCreateWorker = options.onCreateWorker || (() => null);
+  /** @readonly */
   this.onTerminateWorker = options.onTerminateWorker || (() => null);
 
   // configuration
   if (options && 'maxWorkers' in options) {
     validateMaxWorkers(options.maxWorkers);
+    /** @readonly */
     this.maxWorkers = options.maxWorkers;
   }
   else {
@@ -47,6 +65,7 @@ function Pool(script, options) {
 
   if (options && 'minWorkers' in options) {
     if(options.minWorkers === 'max') {
+      /** @readonly */
       this.minWorkers = this.maxWorkers;
     } else {
       validateMinWorkers(options.minWorkers);
@@ -56,6 +75,7 @@ function Pool(script, options) {
     this._ensureMinWorkers();
   }
 
+  /** @private */
   this._boundNext = this._next.bind(this);
 
 
@@ -86,16 +106,16 @@ function Pool(script, options) {
  *       .catch(function(error) {
  *         console.log(error);
  *       });
- *
- * @param {String | Function} method  Function name or function.
+ * @template { (...args: any[]) => any } T
+ * @param {String | T} method  Function name or function.
  *                                    If `method` is a string, the corresponding
  *                                    method on the worker will be executed
  *                                    If `method` is a Function, the function
  *                                    will be stringified and executed via the
  *                                    workers built-in function `run(fn, args)`.
- * @param {Array} [params]  Function arguments applied when calling the function
- * @param {ExecOptions} [options]  Options object
- * @return {Promise.<*, Error>} result
+ * @param {Parameters<T> | null} [params]  Function arguments applied when calling the function
+ * @param {import('./types.js').ExecOptions} [options]  Options
+ * @return {Promise<ReturnType<T>>}
  */
 Pool.prototype.exec = function (method, params, options) {
   // validate type of arguments
@@ -152,9 +172,9 @@ Pool.prototype.exec = function (method, params, options) {
 
 /**
  * Create a proxy for current worker. Returns an object containing all
- * methods available on the worker. The methods always return a promise.
- *
- * @return {Promise.<Object, Error>} proxy
+ * methods available on the worker. All methods return promises resolving the methods result.
+ * @template { { [k: string]: (...args: any[]) => any } } T
+ * @return {Promise<import('./types.js').Proxy<T>, Error>} Returns a promise which resolves with a proxy object
  */
 Pool.prototype.proxy = function () {
   if (arguments.length > 0) {
@@ -194,7 +214,7 @@ Pool.prototype.map = function (array, callback) {
 /**
  * Grab the first task from the queue, find a free worker, and assign the
  * worker to the task.
- * @protected
+ * @private
  */
 Pool.prototype._next = function () {
   if (this.tasks.length > 0) {
@@ -268,7 +288,7 @@ Pool.prototype._getWorker = function() {
  * pool size is met.
  * @param {WorkerHandler} worker
  * @return {Promise<WorkerHandler>}
- * @protected
+ * @private
  */
 Pool.prototype._removeWorker = function(worker) {
   var me = this;
@@ -299,7 +319,7 @@ Pool.prototype._removeWorker = function(worker) {
 /**
  * Remove a worker from the pool list.
  * @param {WorkerHandler} worker
- * @protected
+ * @private
  */
 Pool.prototype._removeWorkerFromList = function(worker) {
   // remove from the list with workers
@@ -374,7 +394,7 @@ Pool.prototype.stats = function () {
 
 /**
  * Ensures that a minimum of minWorkers is up and running
- * @protected
+ * @private
  */
 Pool.prototype._ensureMinWorkers = function() {
   if (this.minWorkers) {

src/Pool.js

@@ -4,7 +4,8 @@
  * Promise
  *
  * Inspired by https://gist.github.com/RubaXa/8501359 from RubaXa <[email protected]>
- *
+ * @template T
+ * @template [E=Error]
  * @param {Function} handler   Called as handler(resolve: Function, reject: Function)
  * @param {Promise} [parent]   Parent promise for propagation of cancel and timeout
  */
@@ -23,8 +24,17 @@ function Promise(handler, parent) {
   var _onFail = [];
 
   // status
+  /**
+   * @readonly
+   */
   this.resolved = false;
+  /**
+   * @readonly
+   */
   this.rejected = false;
+  /**
+   * @readonly
+   */
   this.pending = true;
 
   /**
@@ -41,9 +51,11 @@ function Promise(handler, parent) {
 
   /**
    * Add an onSuccess callback and optionally an onFail callback to the Promise
-   * @param {Function} onSuccess
-   * @param {Function} [onFail]
-   * @returns {Promise} promise
+   * @template TT
+   * @template [TE=never]
+   * @param {(r: T) => TT} onSuccess
+   * @param {(r: E) => TE} [onFail]
+   * @returns {Promise<TT | TE, any>} promise
    */
   this.then = function (onSuccess, onFail) {
     return new Promise(function (resolve, reject) {
@@ -104,7 +116,7 @@ function Promise(handler, parent) {
 
   /**
    * Cancel te promise. This will reject the promise with a CancellationError
-   * @returns {Promise} self
+   * @returns {this} self
    */
   this.cancel = function () {
     if (parent) {
@@ -122,7 +134,7 @@ function Promise(handler, parent) {
    * the time, the promise will be cancelled and a TimeoutError is thrown.
    * If the promise is resolved in time, the timeout is removed.
    * @param {number} delay     Delay in milliseconds
-   * @returns {Promise} self
+   * @returns {this} self
    */
   this.timeout = function (delay) {
     if (parent) {
@@ -177,8 +189,9 @@ function _then(callback, resolve, reject) {
 
 /**
  * Add an onFail callback to the Promise
- * @param {Function} onFail
- * @returns {Promise} promise
+ * @template TT
+ * @param {(error: E) => TT} onFail
+ * @returns {Promise<T | TT>} promise
  */
 Promise.prototype['catch'] = function (onFail) {
   return this.then(null, onFail);
@@ -189,8 +202,9 @@ Promise.prototype['catch'] = function (onFail) {
 
 /**
  * Execute given callback when the promise either resolves or rejects.
- * @param {Function} fn
- * @returns {Promise} promise
+ * @template TT
+ * @param {() => Promise<TT>} fn
+ * @returns {Promise<TT>} promise
  */
 Promise.prototype.always = function (fn) {
   return this.then(fn, fn);
@@ -200,7 +214,7 @@ Promise.prototype.always = function (fn) {
  * Create a promise which resolves when all provided promises are resolved,
  * and fails when any of the promises resolves.
  * @param {Promise[]} promises
- * @returns {Promise} promise
+ * @returns {Promise<any[], any>} promise
  */
 Promise.all = function (promises){
   return new Promise(function (resolve, reject) {
@@ -276,4 +290,4 @@ TimeoutError.prototype.name = 'TimeoutError';
 Promise.TimeoutError = TimeoutError;
 
 
-module.exports = Promise;
+exports.Promise = Promise;

src/Promise.js

@@ -1,6 +1,6 @@
 'use strict';
 
-var Promise = require('./Promise');
+var {Promise} = require('./Promise');
 var environment = require('./environment');
 const {validateOptions, forkOptsNames, workerThreadOptsNames, workerOptsNames} = require("./validateOptions");
 
@@ -206,7 +206,7 @@ function objectToError (obj) {
  * on node.js or a WebWorker in a browser environment.
  * @param {String} [script] If no script is provided, a default worker with a
  *                          function run will be created.
- * @param {WorkerPoolOptions} _options See docs
+ * @param {import('./types.js').WorkerPoolOptions} [_options] See docs
  * @constructor
  */
 function WorkerHandler(script, _options) {
@@ -328,7 +328,7 @@ WorkerHandler.prototype.methods = function () {
  * @param {String} method
  * @param {Array} [params]
  * @param {{resolve: Function, reject: Function}} [resolver]
- * @param {ExecOptions}  [options]
+ * @param {import('./types.js').ExecOptions}  [options]
  * @return {Promise.<*, Error>} result
  */
 WorkerHandler.prototype.exec = function(method, params, resolver, options) {