Adv-waiter NPM

AdvWaiter: Advanced wait functions library/module

Overview
How to use AdvWaiter
- Direct script loading (CDN)
- Module importing (ES6)
API References
- wait(intervalOrOpts, options)
  + Interval
  + Options
  (1) callback
  (2) while-waiting
  (3) until-waiting
  (4) timeout
  (5) onWaiting

1. Overview

AdvWaiter is a JavaScript library/module that provides a couple of wait functions to simplify the source code and make it more readable.

2. How to use AdvWaiter

Direct script loading (CDN)

Downloading library file
When you use AdvWaiter as a library, please download adv-waiter.js.
Specifying library file path
You can specify the library file path to the library within the script tag.
```
<script type="text/javascript" src="./adv-waiter.js">
```

Calling function
Invoke the function by appending the function name after the class name AdvWaiter.

// Waits until the seconds of the current time reach 0.
await AdvWaiter.wait({
    until: () => new Date().getSeconds() === 0,
    callback: () => console.log('Time is up!')
});

Module importing (ES6)

Downloading module file
If you want to use AdvWaiter as a module, just download adv-waiter.mjs.

Specifying module file path
You can use the import statement to specify the module file.

import AdvWaiter from './adv-waiter.mjs';
  or
import { wait } from './adv-waiter.mjs';

Calling function
Invoke the function.

// Waits until the seconds of the current time becomes 10, 20, 40 or 50.
await wait({
    while: () => new Date().getSeconds(),
    existsIn: [ 10, 20, 40, 50 ]
});

3. API References

`wait(intervalOrOpts, options)`

Waits for the specified time or options.

Interval

If NO arguments are specified, it waits for 100 milliseconds as a default 'wait time'.

// Waits for 100ms.
await wait();

If ONLY first argument intervalOrOpts is specified as a numeric value, it waits for the time specified in intervalOrOpts.
If a FALSY value is specified, the default value of 100 is set as the 'wait time'.

// Waits for 1 second.
await wait(1000);

// Waits for 100ms.
await wait(0);
await wait('');
await wait(null);
await wait(false);
await wait(undefined);

If ONLY first argument intervalOrOpts is specified as a JSON, the first argument is treated as options, and the default value of 100 is set as the 'wait time'.

// The first argument is treated as options.
await wait({ until: () => ... });

// The above code is equivalent to the following codes.
await wait(100, { until: () => ... });
await wait(0, { until: () => ... });
await wait('', { until: () => ... });
await wait(null, { until: () => ... });
await wait(false, { until: () => ... });
await wait(undefined, { until: () => ... });

Options

(1) callback

If options.callback is specified, it executes options.callback function after waiting.

// [Example 1.1]
// Waits for 5 seconds, then outputs a message to the console.
await wait(5000, {
  callback: () => console.log('5 seconds have passed.')
});

(2) while-waiting

	#### ① In case of only 'while' being specfied  

	<img src="https://github.com/shinnagamine/adv-waiter/blob/main/images/while-waiting_1.png" width="600">

	If `options.while` is specified and `options.existsIn` is **NOT** specified,
	it waits **WHILE** `options.while` function returns truthy value.  

	```
	// [Example 2.1.1]
	// Waits while the seconds of the current time is less than 30.
	await wait({
	  while: () => new Date().getSeconds() < 30
	});

	// [Example 2.1.2]
	// Waits while the textbox is blank.
	await wait({
	  while: () => document.querySelector('input[type="text"]').value === ''
	});

	// [Example 2.1.3]
	// Waits while the element exists.
	// * i.e., while document.querySelector() returns truthy value.
	await wait({
	  while: () => document.querySelector('#will_be_removed')
	});
	```

	#### ② In case of both 'while' and 'existsIn' being specfied  

	<img src="https://github.com/shinnagamine/adv-waiter/blob/main/images/while-waiting_2.png" width="600">

	If both `options.while` and `options.existsIn` are specified:  
	The function returns the result of `options.while` function.  

	- If the type of `options.existsIn` is Array:  
	  It waits **WHILE** the result of `options.while` function matches an element
	  in `options.existsIn` array.  

	- If the type of `options.existsIn` is other than Array and the value is **TRUTHY**:  
	  It waits **WHILE** the result of `options.while` function is equivalent
	  to the value of `options.existsIn`.  

	- If the type of `options.existsIn` is other than Array and the value is **FALSY**:  
	  The `options.existsIn` is **IGNORED**.  
	  If you want to use a falsy value for the wait condition,
	  it must be specified as an element within the array.

	```
	// [Example 2.2.1]
	// Waits while the seconds of the current time is 0, 1, 2, 3 or 4,
	// then returns the seconds of the reached time (other than 0, 1, 2, 3 and 4).
	const secondsAfterWait = await wait({
	  while: () => new Date().getSeconds(),
	  existsIn: [ 0, 1, 2, 3, 4 ]
	});

	> [!NOTE]  
	> The above code is equivalent to the following code:

	const secondsAfterWait = await wait({
	  while: () => new Date().getSeconds() <= 4
	});

	// [Example 2.2.2]
	// Waits while the value of select box is 'April', 'May' or 'June',
	// then returns the value when it becomes another month.
	return await wait({
	  while: () => document.querySelector('select').value,
	  existsIn: [ 'April', 'May', 'June' ]
	});
	```

	> [!NOTE]  
	> Without using ***AdvWaiter***, the code for the above process would be the complex code shown below:  

	```
	let selectedMonth;
	while ([ 'April', 'May', 'June' ].includes(selectedMonth = document.querySelector('select').value)) {
	  await new Promise(resolve => {
	    setTimeout(() => {
	      resolve();
	    }, 100);
	  });
	}
	return selectedMonth;
	```

(3) until-waiting

① In case of only 'until' being specfied

If options.until is specified and options.existsIn is NOT specified, it waits UNTIL options.until function returns truthy value.

// [Example 3.1.1]
// Waits until the seconds of the current time reach 0.
await wait({
  until: () => new Date().getSeconds() === 0
});

// [Example 3.1.2]
// Waits until the checkbox is checked.
await wait({
  until: () => document.querySelector('input[type="checkbox"]').checked
});

// [Example 3.1.3]
// Waits until the element is created.
// * i.e., until document.querySelector() returns truthy value.
await wait({
  until: () => document.querySelector('#will_be_created')
});

② In case of both 'until' and 'existsIn' being specfied

If both options.until and options.existsIn are specified:
The function returns the result of options.until function.

If the type of options.existsIn is Array:
It waits UNTIL the result of options.until function matches an element in options.existsIn array.
If the type of options.existsIn is other than Array and the value is TRUTHY:
It waits UNTIL the result of options.until function is equivalent to the value of options.existsIn.
If the type of options.existsIn is other than Array and the value is FALSY:
The options.existsIn is IGNORED.
If you want to use a falsy value for the wait condition, it must be specified as an element within the array.

// [Example 3.2.1]
// Waits until the seconds of the current time reach 0, 15, 30 or 45,
// then returns the seconds of the reached time (0, 15, 30 or 45).
const secondsAfterWait = await wait({
  until: () => new Date().getSeconds(),
  existsIn: [ 0, 15, 30, 45 ]
});

> [!NOTE]  
> The above code is equivalent to the following codes:

const secondsAfterWait = await wait({
  until: () => (new Date().getSeconds()) % 15,
  existsIn: 0
});

const secondsAfterWait = await wait({
  until: () => (new Date().getSeconds()) % 15 === 0
});

// [Example 3.2.2]
// Waits until the 'Sunday' or 'Saturday' radio button is selected,
// then returns the selected value when either is selected.
return await wait({
  until: () => document.querySelectorAll('input[type="radio"]:checked').value,
  existsIn: [ 'Sunday', 'Saturday' ]
});

!NOTE
Without using AdvWaiter, the code for the above process would be the complex code shown below:

const getCheckedRadio = () => document.querySelector('input[type="radio"]:checked');
while (!(getCheckedRadio() && [ 'Sunday', 'Saturday' ].includes(getCheckedRadio().value)) {
  await new Promise(resolve => {
    setTimeout(() => {
      resolve();
    }, 100);
  });
}
return getCheckedRadio().value;

(4) timeout

If options.timeout is specified, the waiting process will terminate after specified time.
If options.onTimeout is specified, the specified function will be executed when a timeout occurs.

// [Example 4]
// Waiting process will terminate after 3 seconds, then outputs a message to the console.
await wait({
  while: () => true,
  timeout: 3000,
  onTimeout: () => console.log('Waiting process terminated...')
});

(5) onWaiting

If options.onWaiting is specified, the specified function will be executed at specified intervals while waiting.
This option may be used primarily for debugging purposes.

// [Example 5]
// Outputs the current time to the console while waiting.
await wait({
  while: () => true,
  onWaiting: () => console.log(new Date())
});