mutative

Persistent DOM mutation observations based on CSS query selectors. It's essentially a wrapper for a global MutationObserver that filters records to specific callbacks. The API is _similar_ to MutationObserver, but not the same.

The advantage is that observers can be set up independently/ahead of matching DOM elements, which is useful when working with SPAs or other reactive content.

$3

Use

Import the package by using a CDN or saving it locally.

``javascript
// esm.sh
import mutative from "https://esm.sh/@jackcarey/mutative";
// jsdelivr (with ESM)
import mutative from "https://cdn.jsdelivr.net/npm/@jackcarey/mutative/+esm";
//jsDelivr (with version)
import mutative from "https://cdn.jsdelivr.net/npm/@jackcarey/mutative@1.3.1/mutative.min.js";
//GitHub (always latest code, possibly unstable)
import mutative from "https://cdn.jsdelivr.net/gh/jackcarey/mutative/mutative.min.js";
// local file
import mutative from "./mutative.min.js";
`

Then call it in a script tag:

`javascript

`

$3

The parameters are different from the MutationObserver implementation. Instead of a target and options there is selectors and callback.

- selectors - Several types are allowed:
- null - If no arguments are passed, observation of existing selectors will continue.
- string - a single CSS query selector.
- string[] - multiple CSS query selectors that use the same callback.
- object - CSS query selectors strings as keys, callbacks as values.
- callback - Only required when selectors is a string or array of strings. A function that accepts a MutationRecord as it's only parameter.

$3

Mutations that have been detected but not yet reported to observers are _not_ discarded. Observer callbacks are triggered before disconnection. This method pauses observation and callbacks.

- When called with no arguments: acts the same as disconnect(), ignoring all _future_ observations. Note: this does not clear the internal selector list, so calling observe() again will continue with existing selectors.
- When passed with an argument: The arguments follow the same formats as observe()'s selectors parameter. Only observers with the passed selectors are removed.

$3

Takes all records from the Mutative object, use carefully. See: takeRecords().

How it works

A single MutationObserver is created on the document body with the first call of mutative.observe(). MutatioNrecords are only passed to callbacks that have a matching selector for at least one of target, addedNodes, or removedNodes`.