Allow resolving with a custom value (#25)

index.d.ts

@@ -23,20 +23,49 @@ export interface Options {
 	readonly before?: boolean;
 }
 
-/**
-Wait for a condition to be true.
+// https://github.com/sindresorhus/type-fest/blob/043b732bf02c2b700245aa6501116a6646d50732/source/opaque.d.ts
+declare const resolveValueSymbol: unique symbol;
 
-@returns A promise that resolves when `condition` returns `true`. Rejects if `condition` throws or returns a `Promise` that rejects.
+interface ResolveValue<ResolveValueType> {
+	[resolveValueSymbol]: ResolveValueType;
+}
+
+declare const pWaitFor: {
+	/**
+	Wait for a condition to be true.
+
+	@returns A promise that resolves when `condition` returns `true`. Rejects if `condition` throws or returns a `Promise` that rejects.
+
+	@example
+	```
+	import pWaitFor from 'p-wait-for';
+	import {pathExists} from 'path-exists';
+
+	await pWaitFor(() => pathExists('unicorn.png'));
+	console.log('Yay! The file now exists.');
+	```
+	*/
+	<ResolveValueType>(condition: () => PromiseLike<boolean> | boolean | ResolveValue<ResolveValueType> | PromiseLike<ResolveValue<ResolveValueType>>, options?: Options): Promise<ResolveValueType>;
+
+	/**
+	Resolve the main promise with a custom value.
 
-@example
-```
-import pWaitFor from 'p-wait-for';
-import {pathExists} from 'path-exists';
+	@example
+	```
+	import pWaitFor from 'p-wait-for';
+	import pathExists from 'path-exists';
+
+	const path = await pWaitFor(async () => {
+		const path = getPath();
+		return await pathExists(path) && pWaitFor.resolveWith(path);
+	});
+
+	console.log(path);
+	```
+	*/
+	resolveWith<ValueType>(value: ValueType): ResolveValue<ValueType>;
+};
 
-await pWaitFor(() => pathExists('unicorn.png'));
-console.log('Yay! The file now exists.');
-```
-*/
-export default function pWaitFor(condition: () => PromiseLike<boolean> | boolean, options?: Options): Promise<void>;
+export default pWaitFor;
 
 export {TimeoutError} from 'p-timeout';

index.js

@@ -1,5 +1,7 @@
 import pTimeout from 'p-timeout';
 
+const resolveValue = Symbol('resolveValue');
+
 export default async function pWaitFor(condition, options = {}) {
 	const {
 		interval = 20,
@@ -14,11 +16,11 @@ export default async function pWaitFor(condition, options = {}) {
 			try {
 				const value = await condition();
 
-				if (typeof value !== 'boolean') {
+				if (typeof value === 'object' && value[resolveValue]) {
+					resolve(value[resolveValue]);
+				} else if (typeof value !== 'boolean') {
 					throw new TypeError('Expected condition to return a boolean');
-				}
-
-				if (value === true) {
+				} else if (value === true) {
 					resolve();
 				} else {
 					retryTimeout = setTimeout(check, interval);
@@ -50,4 +52,6 @@ export default async function pWaitFor(condition, options = {}) {
 	return promise;
 }
 
+pWaitFor.resolveWith = value => ({[resolveValue]: value});
+
 export {TimeoutError} from 'p-timeout';

index.test-d.ts

@@ -6,3 +6,5 @@ expectType<Promise<void>>(pWaitFor(async () => false));
 expectType<Promise<void>>(pWaitFor(() => true, {interval: 1}));
 expectType<Promise<void>>(pWaitFor(() => true, {timeout: 1}));
 expectType<Promise<void>>(pWaitFor(() => true, {before: false}));
+expectType<Promise<number>>(pWaitFor(() => pWaitFor.resolveWith(1)));
+expectType<Promise<number>>(pWaitFor(() => pWaitFor.resolveWith(1)));

readme.md

@@ -59,6 +59,22 @@ Whether to run the check immediately rather than starting by waiting `interval`
 
 Useful for when the check, if run immediately, would likely return `false`. In this scenario, set `before` to `false`.
 
+#### resolveWith(value)
+
+Resolve the main promise with a custom value.
+
+```js
+import pWaitFor from 'p-wait-for';
+import pathExists from 'path-exists';
+
+const path = await pWaitFor(async () => {
+	const path = getPath();
+	return await pathExists(path) && pWaitFor.resolveWith(path);
+});
+
+console.log(path);
+```
+
 ### TimeoutError
 
 Exposed for instance checking.

test.js

@@ -70,3 +70,7 @@ test('does not perform a leading check', async t => {
 
 	t.true(end() > (ms - 20));
 });
+
+test('resolveWith()', async t => {
+	t.true(await pWaitFor(() => pWaitFor.resolveWith(true)));
+});