Fix timeout-dependent return types of add and addAll

readme.md

@@ -63,7 +63,8 @@ Concurrency limit.
 
 ##### timeout
 
-Type: `number`
+Type: `number`\
+Default: `undefined` (i.e. no timeout is enforced)
 
 Per-operation timeout in milliseconds. Operations fulfill once `timeout` elapses if they haven't already.
 
@@ -72,7 +73,9 @@ Per-operation timeout in milliseconds. Operations fulfill once `timeout` elapses
 Type: `boolean`\
 Default: `false`
 
-Whether or not a timeout is considered an exception.
+Whether or not a timeout is considered an exception. When `false`, promises will resolve without a value on timeout.
+
+Obviously, this option only has an effect when `timeout` is defined.
 
 ##### autoStart
 

source/index.ts

@@ -2,7 +2,7 @@ import {EventEmitter} from 'eventemitter3';
 import pTimeout, {TimeoutError} from 'p-timeout';
 import {type Queue, type RunFunction} from './queue.js';
 import PriorityQueue from './priority-queue.js';
-import {type QueueAddOptions, type Options, type TaskOptions} from './options.js';
+import {type QueueAddOptions, type Options, type TaskOptions, type WithoutTimeout, type WithoutTimeoutThrow, type WithTimeoutThrow} from './options.js';
 
 type Task<TaskResultType> =
 	| ((options: TaskOptions) => PromiseLike<TaskResultType>)
@@ -231,15 +231,32 @@ export default class PQueue<QueueType extends Queue<RunFunction, EnqueueOptionsT
 	/**
 	Adds a sync or async task to the queue. Always returns a promise.
 	*/
-	async add<TaskResultType>(function_: Task<TaskResultType>, options: {throwOnTimeout: true} & Exclude<EnqueueOptionsType, 'throwOnTimeout'>): Promise<TaskResultType>;
-	async add<TaskResultType>(function_: Task<TaskResultType>, options?: Partial<EnqueueOptionsType>): Promise<TaskResultType | void>;
-	async add<TaskResultType>(function_: Task<TaskResultType>, options: Partial<EnqueueOptionsType> = {}): Promise<TaskResultType | void> {
+	async add<TaskResultType>(
+		function_: Task<TaskResultType>,
+		options?: WithoutTimeout<Partial<EnqueueOptionsType>>
+	): Promise<TaskResultType>;
+	async add<TaskResultType>(
+		function_: Task<TaskResultType>,
+		options: WithTimeoutThrow<Partial<EnqueueOptionsType>>
+	): Promise<TaskResultType>;
+	async add<TaskResultType>(
+		function_: Task<TaskResultType>,
+		options: WithoutTimeoutThrow<Partial<EnqueueOptionsType>>
+	): Promise<TaskResultType | void>;
+	async add<TaskResultType>(
+		function_: Task<TaskResultType>,
+		options: Partial<EnqueueOptionsType> = {},
+	): Promise<TaskResultType | void> {
 		options = {
 			timeout: this.timeout,
 			throwOnTimeout: this.#throwOnTimeout,
 			...options,
 		};
 
+		if (!options.timeout && options.throwOnTimeout) {
+			console.warn('You specified `throwOnTimeout=true` without defining `timeout`.');
+		}
+
 		return new Promise((resolve, reject) => {
 			this.#queue.enqueue(async () => {
 				this.#pending++;
@@ -287,15 +304,19 @@ export default class PQueue<QueueType extends Queue<RunFunction, EnqueueOptionsT
 	*/
 	async addAll<TaskResultsType>(
 		functions: ReadonlyArray<Task<TaskResultsType>>,
-		options?: {throwOnTimeout: true} & Partial<Exclude<EnqueueOptionsType, 'throwOnTimeout'>>,
+		options?: WithoutTimeout<Partial<EnqueueOptionsType>>,
+	): Promise<TaskResultsType[]>;
+	async addAll<TaskResultsType>(
+		functions: ReadonlyArray<Task<TaskResultsType>>,
+		options: WithTimeoutThrow<Partial<EnqueueOptionsType>>
 	): Promise<TaskResultsType[]>;
 	async addAll<TaskResultsType>(
 		functions: ReadonlyArray<Task<TaskResultsType>>,
-		options?: Partial<EnqueueOptionsType>,
+		options: WithoutTimeoutThrow<Partial<EnqueueOptionsType>>,
 	): Promise<Array<TaskResultsType | void>>;
 	async addAll<TaskResultsType>(
 		functions: ReadonlyArray<Task<TaskResultsType>>,
-		options?: Partial<EnqueueOptionsType>,
+		options: Partial<EnqueueOptionsType> = {},
 	): Promise<Array<TaskResultsType | void>> {
 		return Promise.all(functions.map(async function_ => this.add(function_, options)));
 	}

source/options.ts

@@ -109,3 +109,23 @@ export type TaskOptions = {
 	*/
 	readonly signal?: AbortSignal;
 };
+
+/**
+Helper type to target the case where timeout=number.
+*/
+export type WithTimeout<Options> = Options & {timeout: number};
+
+/**
+Helper type to target the case where timeout=undefined.
+*/
+export type WithoutTimeout<Options> = Omit<Options, 'timeout'> | {timeout: undefined};
+
+/**
+Helper type to target the case where timeout=number and throwOnTimeout=true.
+*/
+export type WithTimeoutThrow<Options> = WithTimeout<Options> & {throwOnTimeout: true};
+
+/**
+Helper type to target the case where timeout=number and throwOnTimeout=false/undefined.
+*/
+export type WithoutTimeoutThrow<Options> = WithTimeout<Options> & {throwOnTimeout?: false};

test-d/index.test-d.ts

@@ -3,5 +3,14 @@ import PQueue from '../source/index.js';
 
 const queue = new PQueue();
 
-expectType<Promise<string | void>>(queue.add(async () => '🦄'));
+expectType<Promise<string>>(queue.add(async () => '🦄'));
+expectType<Promise<string>>(queue.add(async () => '🦄', {}));
+expectType<Promise<string>>(queue.add(async () => '🦄', {throwOnTimeout: undefined}));
+expectType<Promise<string>>(queue.add(async () => '🦄', {throwOnTimeout: false}));
 expectType<Promise<string>>(queue.add(async () => '🦄', {throwOnTimeout: true}));
+expectType<Promise<string>>(queue.add(async () => '🦄', {timeout: undefined}));
+expectType<Promise<string>>(queue.add(async () => '🦄', {timeout: 1, throwOnTimeout: true}));
+expectType<Promise<string | void>>(queue.add(async () => '🦄', {timeout: 1}));
+expectType<Promise<string | void>>(queue.add(async () => '🦄', {timeout: 1, throwOnTimeout: undefined}));
+expectType<Promise<string | void>>(queue.add(async () => '🦄', {timeout: 1, throwOnTimeout: false}));
+expectType<Promise<string>>(queue.add(async () => '🦄', {priority: 1}));