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 one Element, in a few bytes.
• Refined GitHub - Uses this module.

License

MIT © Federico Brigante