one-mutation
v3.0.1
Published
Observe one mutation via `MutationObserver`, then resolve a Promise.
Downloads
3,129
Maintainers
Readme
one-mutation
Observe one mutation via
MutationObserver
, then resolve a Promise.
Install
npm install one-mutation
// This module is only offered as a ES Module
import oneMutation from 'one-mutation';
Usage
oneMutation(document.body, {childList: true}).then(mutations => {
// A text node was added!
});
document.body.append('Text');
oneMutation(document.body, {
childList: true,
filter: mutations => mutations.find(mutation => {
for (const node of mutation.addedNodes) {
if (node.textContent === 'Just me!') {
return true;
}
}
})
}).then(mutations => {
// The expected 'Just me!' node was added!
});
document.body.append('Text'); // Won't resolve the promise
document.body.append(document.createElement('div')); // Won't resolve the promise
document.body.append('Just me!'); // Now!
API
oneMutation(node, options)
Example:
Returns a Promise
that is fulfilled when the expected mutation is found.
node
Type: Node
Example: document.body
, document.querySelector('.article-list')
The node/element to observe. The equivalent parameter of:
new MutationObserver(callback).observe(NODE, options)
options
Type: MutationObserverInit & {filter?: FilterFunction, signal?: AbortSignal}
Example: {childList: true}
, {subtree: true, filter: filterFunction}
This matches MutationObserverInit
and adds a filter
method and an signal
to cancel the observation.
The equivalent parameter of:
new MutationObserver(callback).observe(node, OPTIONS)
subtree, childList, ...
Refer to the MDN MutationObserver documentation to find the full list of properties.
filter
Type: boolean-returning function
Example:
function filterFunction(mutations) {
for (const mutation of mutations) {
for (const node of mutation.addedNodes) {
if (node.textContent === 'Just me!') {
return true;
}
}
}
}
A function that will be called every time that `MutationObserver` detects a change, the equivalent parameter of:
```JS
new MutationObserver(FILTER)
But it should only be used to return true
or false
so that the Promise can be resolved.
signal
Type: AbortSignal
Example:
const timeout = AbortSignal.timeout(1000);
oneMutation(document.body, {
signal: timeout,
attributes: true,
}).then(mutations => {
if (mutations.length > 0) {
console.log('No changes were detected in 1 second');
} else {
console.log('A change was detected!');
}
});
Related
- one-event - Micro module to add an event listener to be executed only once.
- select-dom - Lightweight
querySelector
/All
wrapper that outputs an Array. - doma - Parse an HTML string into
DocumentFragment
or oneElement
, in a few bytes. - Refined GitHub - Uses this module.
License
MIT © Federico Brigante