npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@jackcarey/mutative

v1.3.1

Published

A function for handling global DOM mutation observation

Downloads

3

Readme

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/[email protected]/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.