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