dom-mutations

> Observe changes to the DOM using an async iterable — A nicer API for MutationObserver

This package only works in the browser.

Install

``sh
npm install dom-mutations
`

Usage

`js
import domMutations from 'dom-mutations';

const target = document.querySelector('#unicorn');

for await (const mutation of domMutations(target, {childList: true})) {
console.log('Mutation:', mutation);
}
`

API

$3

Accepts the same arguments as MutationObserver#observe() with an additional optional signal option to abort the observation. If the signal is triggered, the async iterable throws an abort error.

Returns an AsyncIterable that yields MutationRecord objects representing individual mutations.

$3

Similar to domMutations(), but yields batches of MutationRecord objects, each batch representing a group of mutations captured together. This method is less convenient, but can be useful in some cases when you need to handle mutations together as a group.

`js
import {batchedDomMutations} from 'dom-mutations';

const target = document.querySelector('#unicorn');

for await (const mutations of batchedDomMutations(target, {childList: true})) {
console.log('Batch of mutations:', mutations);
}
`

FAQ

$3

Simply return or break in the loop body.

$3

Triggering the iterator to return

`js
import domMutations from 'dom-mutations';

const target = document.querySelector('#unicorn');

const mutationIterator = domMutations(target, {childList: true})[Symbol.asyncIterator]();

(async () => {
for await (const mutation of mutationIterator) {
console.log('Mutation:', mutation);
}
})();

setTimeout(() => {
mutationIterator.return();
}, 10000);
`

Using a variable

This has the downside of not ending the iteration until the next mutation.

`js
import domMutations from 'dom-mutations';

const target = document.querySelector('#unicorn');

let shouldStop = false;

(async () => {
for await (const mutation of domMutations(target, {childList: true})) {
if (shouldStop) {
break;
}

console.log('Mutation:', mutation);
}
})();

setTimeout(() => {
shouldStop = true;
}, 10000);
`

Using AbortController

Unlike the above approaches, this will make the iterable throw an abort error.

`js
import domMutations from 'dom-mutations';

const target = document.querySelector('#unicorn');
const controller = new AbortController();
const {signal} = controller;

(async () => {
for await (const mutation of domMutations(target, {childList: true, signal})) {
console.log('Mutation:', mutation);
}
})();

setTimeout(() => {
controller.abort();
}, 10000);
`

Related

- request-animation-frames - Use requestAnimationFrame` as an async iterable, in any JavaScript environment