p-wait-for - npm Package Compare versions

Comparing version 4.1.0 to 5.0.0

index.d.ts

@@ -1,4 +0,6 @@
-export interface Options {
+import {Options as TimeoutOptions} from 'p-timeout';
+
+export interface Options<ResolveValueType> {
 	/**
-	Number of milliseconds to wait before retrying `condition`.
+	Number of milliseconds to wait after `condition` resolves to `false` before calling it again.
 
@@ -12,5 +14,31 @@ @default 20
 
+	You can customize the timeout `Error` by specifying `TimeoutOptions`.
+
 	@default Infinity
+
+	@example
+	```
+	import pWaitFor from 'p-wait-for';
+	import {pathExists} from 'path-exists';
+
+	const originalSetTimeout = setTimeout;
+	const originalClearTimeout = clearTimeout;
+
+	sinon.useFakeTimers();
+
+	await pWaitFor(() => pathExists('unicorn.png'), {
+		timeout: {
+			milliseconds: 100,
+			message: new MyError('Time’s up!'),
+			customTimers: {
+				setTimeout: originalSetTimeout,
+				clearTimeout: originalClearTimeout
+			}
+		}
+	});
+
+	console.log('Yay! The file now exists.');
+	```
 	*/
-	readonly timeout?: number;
+	readonly timeout?: number | TimeoutOptions<ResolveValueType>; // eslint-disable-line @typescript-eslint/no-redundant-type-constituents
 
@@ -27,18 +55,47 @@ /**
 
-/**
-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;
+}
 
-@example
-```
-import pWaitFor from 'p-wait-for';
-import pathExists from 'path-exists';
+declare const pWaitFor: {
+	/**
+	Wait for a condition to be true.
 
-await pWaitFor(() => pathExists('unicorn.png'));
-console.log('Yay! The file now exists.');
-```
-*/
-export default function pWaitFor(condition: () => PromiseLike<boolean> | boolean, options?: Options): Promise<void>;
+	@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<ResolveValueType>): Promise<ResolveValueType>;
+
+	/**
+	Resolve the main promise with a custom value.
+
+	@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>;
+};
+
+export default pWaitFor;
+
 export {TimeoutError} from 'p-timeout';

index.js

 import pTimeout from 'p-timeout';
 
+const resolveValue = Symbol('resolveValue');
+
 export default async function pWaitFor(condition, options = {}) {
@@ -7,3 +9,3 @@ const {
 		timeout = Number.POSITIVE_INFINITY,
-		before = true
+		before = true,
 	} = options;
@@ -18,7 +20,7 @@
 
-				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();
@@ -40,17 +42,15 @@ } else {
 
-	if (timeout !== Number.POSITIVE_INFINITY) {
-		try {
-			return await pTimeout(promise, timeout);
-		} catch (error) {
-			if (retryTimeout) {
-				clearTimeout(retryTimeout);
-			}
+	if (timeout === Number.POSITIVE_INFINITY) {
+		return promise;
+	}
 
-			throw error;
-		}
+	try {
+		return await pTimeout(promise, typeof timeout === 'number' ? {milliseconds: timeout} : timeout);
+	} finally {
+		clearTimeout(retryTimeout);
 	}
-
-	return promise;
 }
 
+pWaitFor.resolveWith = value => ({[resolveValue]: value});
+
 export {TimeoutError} from 'p-timeout';

package.json

 {
 	"name": "p-wait-for",
-	"version": "4.1.0",
+	"version": "5.0.0",
 	"description": "Wait for a condition to be true",
@@ -40,11 +40,11 @@ "license": "MIT",
 	"dependencies": {
-		"p-timeout": "^5.0.0"
+		"p-timeout": "^6.0.0"
 	},
 	"devDependencies": {
-		"ava": "^3.15.0",
+		"ava": "^4.3.1",
 		"delay": "^5.0.0",
-		"time-span": "^4.0.0",
-		"tsd": "^0.14.0",
-		"xo": "^0.38.2"
+		"time-span": "^5.1.0",
+		"tsd": "^0.22.0",
+		"xo": "^0.51.0"
 	}
 }

readme.md

@@ -9,5 +9,5 @@ # p-wait-for
 
+```sh
+npm install p-wait-for
 ```
-$ npm install p-wait-for
-```
 
@@ -18,3 +18,3 @@ ## Usage
 import pWaitFor from 'p-wait-for';
-import pathExists from 'path-exists';
+import {pathExists} from 'path-exists';
 
@@ -46,7 +46,7 @@ await pWaitFor(() => pathExists('unicorn.png'));
 
-Number of milliseconds to wait before retrying `condition`.
+Number of milliseconds to wait after `condition` resolves to `false` before calling it again.
 
 ##### timeout
 
-Type: `number`\
+Type: `number | TimeoutOptions`\
 Default: `Infinity`
@@ -56,2 +56,75 @@
 
+You can customize the timeout `Error` by specifying `TimeoutOptions`.
+
+```js
+import pWaitFor from 'p-wait-for';
+import {pathExists} from 'path-exists';
+
+const originalSetTimeout = setTimeout;
+const originalClearTimeout = clearTimeout;
+
+sinon.useFakeTimers();
+
+await pWaitFor(() => pathExists('unicorn.png'), {
+	timeout: {
+		milliseconds: 100,
+		message: new MyError('Time’s up!'),
+		customTimers: {
+			setTimeout: originalSetTimeout,
+			clearTimeout: originalClearTimeout
+		}
+	}
+});
+
+console.log('Yay! The file now exists.');
+```
+
+###### milliseconds
+
+Type: `number`\
+Default: `Infinity`
+
+Milliseconds before timing out.
+
+Passing `Infinity` will cause it to never time out.
+
+###### message
+
+Type: `string | Error`
+Default: `'Promise timed out after 50 milliseconds'`
+
+Specify a custom error message or error.
+
+If you do a custom error, it's recommended to sub-class `TimeoutError`.
+
+###### customTimers
+
+Type: `object` with function properties `setTimeout` and `clearTimeout`
+
+Custom implementations for the `setTimeout` and `clearTimeout` functions.
+
+Useful for testing purposes, in particular to work around [`sinon.useFakeTimers()`](https://sinonjs.org/releases/latest/fake-timers/).
+
+###### fallback
+
+Type: `Function`
+
+Do something other than rejecting with an error on timeout.
+
+Example:
+
+```js
+import pWaitFor from 'p-wait-for';
+import {pathExists} from 'path-exists';
+
+await pWaitFor(() => pathExists('unicorn.png'), {
+	timeout: {
+		milliseconds: 50,
+		fallback: () => {
+			console.log('Time’s up! executed the fallback function!');
+		},
+	}
+});
+```
+
 ##### before
@@ -66,2 +139,18 @@
 
+#### 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
@@ -68,0 +157,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

9081

increased by68.67%

Lines of code

117

increased by58.11%

Number of lines in readme file

159

increased by127.14%

Dependency changes

• + Addedp-timeout@6.1.3(transitive)

• - Removedp-timeout@5.1.0(transitive)

• Updatedp-timeout@^6.0.0