Updated dependencies. Moved away from rejecting with errors.

CHANGELOG.md

@@ -2,6 +2,13 @@
 
 The format is based on [Keep a Changelog](http://keepachangelog.com/) and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [4.0.0] (2021-07-22)
+
+### Changed
+
+- Changed `waitForTheElement()` to return `null` when a matching element is not found. It no longer throws an error.
+- Changed `waitForTheElementToDisappear()` to return a boolean, it will return `true` when no elements are matching or `false` if a match still exsits. It no longer throws an error.
+
 ## [3.0.0] (2021-07-01)
 
 ### Changed

README.md

@@ -24,15 +24,11 @@ const { waitForTheElement, waitForTheElementToDisappear } = require('wait-for-th
 You can wait for an element to match a provided selector and retrieve it:
 
 ``` js
-let element;
+const element = await waitForTheElement('.target', {
+  timeout : 5000
+});
 
-try
-{
-  element = await waitForTheElement('.target', {
-    timeout : 5000
-  });
-}
-catch (error)
+if (element === null)
 {
   // After 5 seconds, a matching element still doesn't exist.
 }
@@ -45,13 +41,11 @@ catch (error)
 You can wait for all elements to stop matching a provided selector:
 
 ``` js
-try
-{
-  await waitForTheElementToDisappear('.target', {
-    timeout : 5000
-  });
-}
-catch (error)
+const hidden = await waitForTheElementToDisappear('.target', {
+  timeout : 5000
+});
+
+if (!hidden)
 {
   // After 5 seconds, a matching element still exists.
 }

package.json

@@ -1,7 +1,7 @@
 {
     "name" : "wait-for-the-element",
 
-    "version" : "3.0.0",
+    "version" : "4.0.0",
 
     "type" : "module",
 
@@ -29,15 +29,15 @@
 
     "devDependencies" :
     {
-        "rollup" : "2.52.2",
+        "rollup" : "2.53.3",
         "rollup-plugin-terser" : "7.0.2",
-        "@rollup/plugin-node-resolve" : "13.0.0",
-        "@rollup/plugin-commonjs" : "19.0.0",
+        "@rollup/plugin-node-resolve" : "13.0.2",
+        "@rollup/plugin-commonjs" : "19.0.1",
         "@rollup/plugin-babel" : "5.3.0",
-        "mocha" : "9.0.1",
+        "mocha" : "9.0.2",
         "chai" : "4.3.4",
         "chai-as-promised" : "7.1.1",
-        "eslint" : "7.29.0",
+        "eslint" : "7.31.0",
         "eslint-plugin-import" : "2.23.4",
         "eslint-plugin-promise" : "5.1.0",
         "eslint-config-protect-me-from-my-stupidity" : "7.2.2",
@@ -46,8 +46,8 @@
         "karma-mocha-reporter" : "2.2.5",
         "karma-rollup-preprocessor" : "7.0.7",
         "karma-chrome-launcher" : "3.1.0",
-        "@babel/core" : "7.14.6",
-        "@babel/preset-env" : "7.14.7",
+        "@babel/core" : "7.14.8",
+        "@babel/preset-env" : "7.14.8",
         "timeout-as-promise" : "1.0.0"
     },
 

src/wait-for-the-element.js

@@ -75,7 +75,7 @@ export function waitForTheElement (selector, {
 	timeout = 2500, scope = document
 } = {})
 {
-	return new Promise((resolve, reject) =>
+	return new Promise(resolve =>
 	{
 		const element = scope.querySelector(selector);
 
@@ -110,9 +110,7 @@ export function waitForTheElement (selector, {
 		{
 			observer.disconnect();
 
-			reject(
-				new Error(`An element still does not match selector ${selector} after ${timeout} milliseconds.`)
-			);
+			resolve(null);
 
 		}, timeout);
 	});
@@ -124,15 +122,15 @@ export function waitForTheElementToDisappear (selector, {
 	timeout = 2500, scope = document
 } = {})
 {
-	return new Promise((resolve, reject) =>
+	return new Promise(resolve =>
 	{
 		let timer = null;
 
 		if (
 			scope.querySelector(selector) === null
 		)
 		{
-			resolve();
+			resolve(true);
 
 			return;
 		}
@@ -147,7 +145,7 @@ export function waitForTheElementToDisappear (selector, {
 
 				observer.disconnect();
 
-				resolve();
+				resolve(true);
 			}
 		});
 
@@ -159,9 +157,7 @@ export function waitForTheElementToDisappear (selector, {
 		{
 			observer.disconnect();
 
-			reject(
-				new Error(`An element still matches selector ${selector} after ${timeout} milliseconds.`)
-			);
+			resolve(false);
 
 		}, timeout);
 	});

tests/wait-for-the-element.test.js

@@ -57,22 +57,22 @@ describe('function waitForTheElement(selector, options)', function ()
 
 	describe('when no elements matching `selector` exist', function ()
 	{
-		it('shall throw an error if an element is not matched after 2.5 seconds', function ()
+		it('shall return a promise that will be fulfilled with `null` if an element is not matched after 2.5 seconds', function ()
 		{
 			// Act & Assert.
 			return expect(
 				waitForTheElement('.target')
-			).to.be.rejectedWith(Error);
+			).to.eventually.be.null;
 		});
 
-		it('shall throw an error if an element is not matched after `options.timeout`', function ()
+		it('shall return a promise that will be fulfilled with `null` if an element is not matched after `options.timeout`', function ()
 		{
 			// Act & Assert.
 			return expect(
 				waitForTheElement('.target', {
 					timeout : 4000
 				})
-			).to.be.rejectedWith(Error);
+			).to.eventually.be.null;
 		});
 
 		it('shall return a promise that will be fulfilled with a matching element that was eventually added', async function ()
@@ -212,15 +212,15 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 {
 	describe('when no elements matching `selector` exist', function ()
 	{
-		it('shall return a promise that will be fulfilled', function ()
+		it('shall return a promise that will be fulfilled with `true`', function ()
 		{
 			// Act & Assert.
 			return expect(
 				waitForTheElementToDisappear('.target')
-			).to.be.fulfilled;
+			).to.eventually.be.true;
 		});
 
-		it('shall return a promise that will be fulfilled when no match is found inside `options.scope`', function ()
+		it('shall return a promise that will be fulfilled with `true` when no match is found inside `options.scope`', function ()
 		{
 			// Setup.
 			document.body.innerHTML = `
@@ -233,13 +233,13 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 				waitForTheElementToDisappear('.target', {
 					scope : document.querySelector('#parent')
 				})
-			).to.be.fulfilled;
+			).to.eventually.be.true;
 		});
 	});
 
 	describe('when elements matching `selector` already exist', function ()
 	{
-		it('shall throw an error if an element still matches after 2.5 seconds', function ()
+		it('shall return a promise that will be fulfilled with `false` if an element still matches after 2.5 seconds', function ()
 		{
 			// Setup.
 			document.body.innerHTML = `
@@ -249,10 +249,10 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 			// Act & Assert.
 			return expect(
 				waitForTheElementToDisappear('.target')
-			).to.be.rejectedWith(Error);
+			).to.eventually.be.false;
 		});
 
-		it('shall throw an error if an element still matches after `options.timeout`', function ()
+		it('shall return a promise that will be fulfilled with `false` if an element still matches after `options.timeout`', function ()
 		{
 			// Setup.
 			document.body.innerHTML = `
@@ -264,10 +264,10 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 				waitForTheElementToDisappear('.target', {
 					timeout : 4000
 				})
-			).to.be.rejectedWith(Error);
+			).to.eventually.be.false;
 		});
 
-		it('shall return a promise that will be fulfilled when the matching element is eventually removed', async function ()
+		it('shall return a promise that will be fulfilled with `true` when the matching element is eventually removed', async function ()
 		{
 			// Setup.
 			document.body.innerHTML = `
@@ -284,10 +284,10 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 			document.querySelector('#target').remove();
 
 			// Assert.
-			return expect(result).to.be.fulfilled;
+			return expect(result).to.eventually.be.true;
 		});
 
-		it('shall return a promise that will be fulfilled only when all matching elements are removed', async function ()
+		it('shall return a promise that will be fulfilled with `true` only when all matching elements are removed', async function ()
 		{
 			// Setup.
 			document.body.innerHTML = `
@@ -305,10 +305,10 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 			document.querySelector('.target').remove();
 
 			// Assert.
-			return expect(result).to.be.rejectedWith(Error);
+			return expect(result).to.eventually.be.false;
 		});
 
-		describe('shall return a promise that will be fulfilled when no element matches after an attribute change', function ()
+		describe('shall return a promise that will be fulfilled with `true` when no element matches after an attribute change', function ()
 		{
 			it('including class attributes', async function ()
 			{
@@ -327,7 +327,7 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 				document.querySelector('#target').setAttribute('class', 'ignore');
 
 				// Assert.
-				return expect(result).to.be.fulfilled;
+				return expect(result).to.eventually.be.true;
 			});
 
 			it('including id attributes', async function ()
@@ -347,7 +347,7 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 				document.querySelector('#target').setAttribute('id', 'ignore');
 
 				// Assert.
-				return expect(result).to.be.fulfilled;
+				return expect(result).to.eventually.be.true;
 			});
 
 			it('including miscellaneous attributes', async function ()
@@ -367,7 +367,7 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 				document.querySelector('#target').setAttribute('name', 'ignore');
 
 				// Assert.
-				return expect(result).to.be.fulfilled;
+				return expect(result).to.eventually.be.true;
 			});
 
 			it('including data attributes', async function ()
@@ -387,11 +387,11 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 				document.querySelector('#target').setAttribute('data-attribute', 'ignore');
 
 				// Assert.
-				return expect(result).to.be.fulfilled;
+				return expect(result).to.eventually.be.true;
 			});
 		});
 
-		it('shall return a promise that will be fulfilled when all matching elements are removed from `options.scope`', async function ()
+		it('shall return a promise that will be fulfilled with `true` when all matching elements are removed from `options.scope`', async function ()
 		{
 			// Setup.
 			document.body.innerHTML = `
@@ -402,7 +402,7 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 			`;
 
 			// Act.
-			const result = waitForTheElement('.target', {
+			const result = waitForTheElementToDisappear('.target', {
 				scope : document.querySelector('#parent')
 			});
 
@@ -413,7 +413,7 @@ describe('function waitForTheElementToDisappear(selector, options)', function ()
 			document.querySelector('#target').remove();
 
 			// Assert.
-			return expect(result).to.be.fulfilled;
+			return expect(result).to.eventually.be.true;
 		});
 	});
 });

wait-for-the-element.d.ts

@@ -26,50 +26,45 @@ export interface ElementSearchOptions
  * Example usage:
  *
  * ``` js
- * let element;
- *
- * try
+ * const element = await waitForTheElement('.target', {
  * {
- *     element = await waitForTheElement('.target', {
- *         timeout : 5000
- *     });
- * }
- * catch (error)
+ *     timeout : 5000
+ * });
+ *
+ * if (element === null)
  * {
  *     // After 5 seconds, a matching element still doesn't exist.
  * }
  * ```
  *
  * @param selector The selector that an element must match. This can be any selector that `document.querySelector()` supports.
- * @param options  The options that define how elements should be searched for.
+ * @param options The options that define how elements should be searched for.
  *
  * @typeParam E The type of the element you expect to be found.
  *
- * @returns A promise that will resolve with the first element matching `selector`, or reject with an error if a matching element is not found.
+ * @returns A promise that will resolve with the first element matching the `selector`, or resolve with `null` if a matching element is not found.
  */
-export function waitForTheElement<E extends Element> (selector : string, options? : ElementSearchOptions) : Promise<E>;
+export function waitForTheElement<E extends Element> (selector : string, options? : ElementSearchOptions) : Promise<E | null>;
 
 /**
  * Waits for all elements to stop matching a provided selector.
  *
  * Example usage:
  *
  * ``` js
- * try
- * {
- *     await waitForTheElementToDisappear('.target', {
- *         timeout : 5000
- *     });
- * }
- * catch (error)
+ * const hidden = await waitForTheElementToDisappear('.target', {
+ *     timeout : 5000
+ * });
+ *
+ * if (!hidden)
  * {
  *     // After 5 seconds, a matching element still exists.
  * }
  * ```
  *
  * @param selector The selector that elements must not match. This can be any selector that `document.querySelector()` supports.
- * @param options  Options that define how elements should be searched for.
+ * @param options Options that define how elements should be searched for.
  *
- * @returns A promise that will resolve, or reject with an error if elements are still found to be matching.
+ * @returns A promise that will resolve with `false` if elements are still found to be matching the `selector`, otherwise it will resolve with `true`.
  */
-export function waitForTheElementToDisappear(selector : string, options? : ElementSearchOptions) : Promise<void>;
+export function waitForTheElementToDisappear(selector : string, options? : ElementSearchOptions) : Promise<boolean>;