wal.js v1.1.4
wal.js (watch and listen)
wal.js allows you to watch a value and then add listeners for when the value updates. The motivation behind this project was to create a way to easily listen to values of objects as they are updated, and then be able trigger actions as needed.
CDN
Include this in the website header
<script src="https://unpkg.com/wal.js"></script>
The Watcher class can be acccessed with the window global:
Watcher;
Install
Install from npm using your preferred package manage.
npm i wal.js
yarn add wal.js
pnpm i wal.js
Watcher
Watchers are essentially variables. You can read and store any value, but you get the benefits of making decisions about what happens before and after setting the value.
Create a new watcher
Watcher is a class. Call the constructor with the initial value as the only argument.
import { Watcher } from "wal.js";
const pageIndexWatcher = new Watcher(1);
Value
Read the watcher value
To read the watcher value, you just need to reference the .value.
const pageIndexWatcher = new Watcher(1);
console.log(pageIndexWatcher.value); // 1
Update the watcher value
To update the watcher value, set the value equal to something new.
const pageIndexWatcher = new Watcher(1);
console.log(pageIndexWatcher.value); // 1
// This updates the value
pageIndexWatcher.value = 2;
console.log(pageIndexWatcher.value); // 2
Note: in order for everything to work as intended, you need to set the actual value. It is not recomended to set a child of the value. If you need to set a child, you can call triggerListeners()
to let the watcher know you updated its value.
Listeners
Listeners are functions that are called whenever the value is updated successfully. Whenever the value is updated, it will call all the functions with the new value as the first argument.
Add a listener
addListener
is used to add a listener to the watcher. Call it with a reference to a function as the argument.
const pageIndexWatcher = new Watcher(1);
//create watcher rules
function printPageToConsole(index: number) {
console.log(index);
}
pageIndexWatcher.addListener(printPageToConsole);
pageIndexWatcher.value = 2; // This will log 2 to the console.
pageIndexWatcher.value = 3; // This will log 3 to the console.
Remove a listener
To stop a listener from triggering, call removeListener
with a reference to the original function.
const pageIndexWatcher = new Watcher(1);
function printPageToConsole(index: number) {
console.log(index);
}
pageIndexWatcher.addListener(printPageToConsole);
pageIndexWatcher.value = 2; // This will log 2 to the console.
pageIndexWatcher.removeListener(printPageToConsole);
pageIndexWatcher.value = 3; // This will update the value but not print to console
Trigger listeners
triggerListeners
will run all functions with the current value.
const pageIndexWatcher = new Watcher(1);
//create watcher rules
function printPageToConsole(index: number) {
console.log(index);
}
pageIndexWatcher.addListener(printPageToConsole);
pageIndexWatcher.value = 2; // This will log 2 to the console.
pageIndexWatcher.value = 3; // This will log 3 to the console.
Rules
Rules are similar to listeners. The difference is the functions are run before the value is set. This means that you can throw errors to prevent data from being set to the value.
Add a rule
The addRule
function is used to add rules. It takes a rule function as an argument. This rule function has 2 paramaters: the new value and the the old value. This rule function is ran before the value of the Watcher is set. When you throw an exception in a rule, it will stop the value from being written.
const pageIndexWatcher = new Watcher(1);
function isNum(newValue, oldValue) {
if (typeof value !== "number") throw "The value is not set to a number";
}
pageIndexWatcher.addRule(isNum);
pageIndexWatcher.value = "Hello world!"; // Uncaught: The value is not set to a number
Remove a rule
The removeRule
function will stop a function from being called. It takes a function as its only argument.
pageIndexWatcher.removeRule(isNum);