@jackcarey/mutative

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.

~1.3kb minified, ~800 bytes gzipped.

Use

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

// 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:

<script type="module">
import mutative from "https://esm.sh/@jackcarey/mutative"

// pass a single selector and callback
Mutative.observe("p",(record)=>console.log(record));

//pass multiple selectors with the same callback
Mutative.observe(["p",".text","*[data-text]"],(record)=>console.log("text mutated",record));

//pass multiple selectors at once with different callbacks
Mutative.observe({
    "*[data-text]": (rec)=>console.log(rec),
    "p":(rec)=>alert("paragraph edited"),
    "output":(rec)=>console.log("calculation updated",rec)
});

//Remove observations for the 'p' selector only
Mutative.disconnect("p");

// Pause all observations
Mutative.disconnect();

//Resume existing observations
Mutative.observe();

</script>

observe()

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.

disconnect()

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.

takeRecords()

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.