mutative

Persistent DOM mutation observations based on CSS query selectors

• Version: 1.0.41
• License: LGPL-3

Using this package

Browser

• via the ESM CDN: https://esm.sh/jsr/@web-components/mutative

<script src="https://esm.sh/jsr/@web-components/mutative" type="module"></script>

Deno

deno add jsr:@web-components/mutative

NPM

• JSR provides NPM compatibility. You can install this package with:

npx jsr add @web-components/mutative

Documentation

• Open examples for mutative on Storybook.

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.

// 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();

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 resume.
  • 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 will either pause or remove observations and callbacks.

• When called with no arguments: acts the same as disconnect(), ignoring all future mutations. 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. If no selectors remain, observation is paused (as if no arguments were passed).

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.

Made by jackcarey.