feat: Add idleThreads getter (#1055)

Author: isaacparker0

README.md

@@ -50,6 +50,7 @@ For Node.js 24.x and higher.
     - [Property: `options` (readonly)](#property-options-readonly)
     - [Property: `runTime` (readonly)](#property-runtime-readonly)
     - [Property: `threads` (readonly)](#property-threads-readonly)
+    - [Property: `idleThreads` (readonly)](#property-idlethreads-readonly)
     - [Property: `queueSize` (readonly)](#property-queuesize-readonly)
     - [Property: `needsDrain` (readonly)](#property-needsdrain-readonly)
     - [Property: `utilization` (readonly)](#property-utilization-readonly)
@@ -602,6 +603,11 @@ faster or equal to the given value.
 
 An Array of the `Worker` instances used by this pool.
 
+### Property: `idleThreads` (readonly)
+
+The current number of ready (warmed up) Worker threads that are not running any
+task.
+
 ### Property: `queueSize` (readonly)
 
 The current number of tasks waiting to be assigned to a Worker thread.

docs/docs/api-reference/api-overview.md

@@ -20,6 +20,7 @@ sidebar_position: 1
 | **Property: `options` (readonly)**                                     | A copy of the options that are currently being used by this instance.                                                                                                                                                                                                                               |
 | **Property: `runTime` (readonly)**                                     | A histogram summary object summarizing the collected run times of completed tasks.                                                                                                                                                                                                                  |
 | **Property: `threads` (readonly)**                                     | An Array of the `Worker` instances used by this pool.                                                                                                                                                                                                                                               |
+| **Property: `idleThreads` (readonly)**                                 | The current number of ready (warmed up) Worker threads that are not running any task.                                                                                                                                                                                                               |
 | **Property: `queueSize` (readonly)**                                   | The current number of tasks waiting to be assigned to a Worker thread.                                                                                                                                                                                                                              |
 | **Property: `needsDrain` (readonly)**                                  | Boolean value that specifies whether the capacity of the pool has been exceeded by the number of tasks submitted.                                                                                                                                                                                   |
 | **Property: `utilization` (readonly)**                                 | A point-in-time ratio comparing the approximate total mean run time of completed tasks to the total runtime capacity of the pool.                                                                                                                                                                   |

docs/docs/api-reference/property.md

@@ -62,6 +62,11 @@ faster or equal to the given value.
 
 An Array of the `Worker` instances used by this pool.
 
+## Property: `idleThreads` (readonly)
+
+The current number of ready (warmed up) Worker threads that are not running any
+task.
+
 ## Property: `queueSize` (readonly)
 
 The current number of tasks waiting to be assigned to a Worker thread.

src/index.ts

@@ -876,6 +876,14 @@ export default class Piscina<Exports extends Record<string, (payload: any) => an
     return ret;
   }
 
+  get idleThreads () : number {
+    let count = 0;
+    for (const workerInfo of this.#pool.workers.readyItems) {
+      if (workerInfo.currentUsage() === 0) count++;
+    }
+    return count;
+  }
+
   get queueSize () : number {
     const pool = this.#pool;
     return Math.max((pool.taskQueue.size + pool.skipQueue.length) - pool.pendingCapacity(), 0);

test/thread-count.test.ts

@@ -97,6 +97,33 @@ test('conflicting min/max threads is error', () => {
   }), /options.minThreads and options.maxThreads must not conflict/);
 });
 
+test('idleThreads reflects ready, unoccupied workers', async () => {
+  const pool = new Piscina({
+    filename: resolve(__dirname, 'fixtures/sleep.js'),
+    minThreads: 2,
+    maxThreads: 2,
+    concurrentTasksPerWorker: 1
+  });
+
+  // All minThreads workers are warmed and idle from the start.
+  assert.strictEqual(pool.idleThreads, 2);
+
+  const first = pool.run({ time: 100 });
+  // One worker is now busy.
+  assert.strictEqual(pool.idleThreads, 1);
+
+  const second = pool.run({ time: 100 });
+  // Both workers are busy.
+  assert.strictEqual(pool.idleThreads, 0);
+
+  await Promise.all([first, second]);
+  // Workers return to idle once tasks complete.
+  assert.strictEqual(pool.idleThreads, 2);
+
+  await pool.destroy();
+  assert.strictEqual(pool.idleThreads, 0);
+});
+
 test('thread count should be 0 upon destruction', async () => {
   const pool = new Piscina({
     filename: resolve(__dirname, 'fixtures/eval.js'),