Add timeoutRemaining to runningTasks

Fixes #247

Author: sindresorhus

readme.md

@@ -476,14 +476,14 @@ setInterval(() => {
 
 #### .runningTasks
 
-The tasks currently being executed. Each task includes its `id`, `priority`, `startTime`, and `timeout` (if set).
+The tasks currently being executed. Each task includes its `id`, `priority`, `startTime`, `timeout` (if set), and `timeoutRemaining` (milliseconds until the task times out, or `undefined` if no timeout is set).
 
 Returns an array of task info objects.
 
 ```js
 import PQueue from 'p-queue';
 
-const queue = new PQueue({concurrency: 2});
+const queue = new PQueue({concurrency: 2, timeout: 10000});
 
 // Add tasks with IDs for better debugging
 queue.add(() => fetchUser(123), {id: 'user-123'});
@@ -497,13 +497,15 @@ console.log(queue.runningTasks);
 		id: 'user-123',
 		priority: 0,
 		startTime: 1759253001716,
-		timeout: undefined
+		timeout: 10000,
+		timeoutRemaining: 9700
 	},
 	{
 		id: 'posts-456',
 		priority: 1,
 		startTime: 1759253001916,
-		timeout: undefined
+		timeout: 10000,
+		timeoutRemaining: 9900
 	}
 ]
 */

source/index.ts

@@ -921,14 +921,14 @@ export default class PQueue<QueueType extends Queue<RunFunction, EnqueueOptionsT
 	}
 
 	/**
-	The tasks currently being executed. Each task includes its `id`, `priority`, `startTime`, and `timeout` (if set).
+	The tasks currently being executed. Each task includes its `id`, `priority`, `startTime`, `timeout` (if set), and `timeoutRemaining` (milliseconds until the task times out, or `undefined` if no timeout is set).
 
 	Returns an array of task info objects.
 
 	```js
 	import PQueue from 'p-queue';
 
-	const queue = new PQueue({concurrency: 2});
+	const queue = new PQueue({concurrency: 2, timeout: 10000});
 
 	// Add tasks with IDs for better debugging
 	queue.add(() => fetchUser(123), {id: 'user-123'});
@@ -940,12 +940,14 @@ export default class PQueue<QueueType extends Queue<RunFunction, EnqueueOptionsT
 	//   id: 'user-123',
 	//   priority: 0,
 	//   startTime: 1759253001716,
-	//   timeout: undefined
+	//   timeout: 10000,
+	//   timeoutRemaining: 9700
 	// }, {
 	//   id: 'posts-456',
 	//   priority: 1,
 	//   startTime: 1759253001916,
-	//   timeout: undefined
+	//   timeout: 10000,
+	//   timeoutRemaining: 9900
 	// }]
 	```
 	*/
@@ -954,9 +956,13 @@ export default class PQueue<QueueType extends Queue<RunFunction, EnqueueOptionsT
 		readonly priority: number;
 		readonly startTime: number;
 		readonly timeout?: number;
+		readonly timeoutRemaining?: number;
 	}> {
 		// Return fresh array with fresh objects to prevent mutations
-		return [...this.#runningTasks.values()].map(task => ({...task}));
+		return [...this.#runningTasks.values()].map(task => ({
+			...task,
+			timeoutRemaining: task.timeout ? Math.max(0, task.startTime + task.timeout - Date.now()) : undefined,
+		}));
 	}
 }
 

test/debug.ts

@@ -1,5 +1,5 @@
 import {test} from 'node:test';
-import assert from 'node:assert';
+import assert from 'node:assert/strict';
 import delay from 'delay';
 import PQueue from '../source/index.js';
 
@@ -122,6 +122,63 @@ test('runningTasks returns fresh arrays', async () => {
 	await queue.onIdle();
 });
 
+test('runningTasks includes timeoutRemaining for tasks with timeout', async () => {
+	const queue = new PQueue({concurrency: 2, timeout: 5000});
+
+	queue.add(async () => delay(200), {id: 'with-timeout'});
+	queue.add(async () => delay(200), {id: 'custom-timeout', timeout: 2000});
+
+	await delay(10);
+
+	const running = queue.runningTasks;
+	const withTimeout = running.find(t => t.id === 'with-timeout');
+	const customTimeout = running.find(t => t.id === 'custom-timeout');
+
+	assert.ok(withTimeout);
+	assert.ok(typeof withTimeout.timeoutRemaining === 'number');
+	assert.ok(withTimeout.timeoutRemaining! > 0);
+	assert.ok(withTimeout.timeoutRemaining! <= 5000);
+
+	assert.ok(customTimeout);
+	assert.ok(typeof customTimeout.timeoutRemaining === 'number');
+	assert.ok(customTimeout.timeoutRemaining! > 0);
+	assert.ok(customTimeout.timeoutRemaining! <= 2000);
+
+	await queue.onIdle();
+});
+
+test('runningTasks timeoutRemaining is undefined when no timeout is set', async () => {
+	const queue = new PQueue({concurrency: 1});
+
+	queue.add(async () => delay(100), {id: 'no-timeout'});
+
+	await delay(10);
+
+	const running = queue.runningTasks;
+	assert.equal(running.length, 1);
+	assert.equal(running[0].timeoutRemaining, undefined);
+
+	await queue.onIdle();
+});
+
+test('runningTasks timeoutRemaining decreases over time', async () => {
+	const queue = new PQueue({concurrency: 1, timeout: 5000});
+
+	queue.add(async () => delay(300), {id: 'task'});
+
+	await delay(10);
+
+	const remaining1 = queue.runningTasks[0].timeoutRemaining!;
+
+	await delay(100);
+
+	const remaining2 = queue.runningTasks[0].timeoutRemaining!;
+
+	assert.ok(remaining2 < remaining1, `Expected ${remaining2} < ${remaining1}`);
+
+	await queue.onIdle();
+});
+
 test('runningTasks handles tasks without IDs', async () => {
 	const queue = new PQueue({concurrency: 2});