Introduction

This is the API documentation for the Mutation Summary library. Mutation Summary is a JavaScript library that makes observing changes to the DOM fast, easy and safe. It is built on top of (and requires) a new API called DOM Mutation Observers.

Basic Usage

The main class is the MutationSummary class. To use the library construct a new MutationSummary passing it options telling it where and what to listen to, and how to notify you of changes.

const ms = new MutationSummary({
  callback(summaries: Summary[]) {
    summaries.forEach((summary: Summary) => console.log(summary));
  },
  queries: [
    { all: true }
  ]
});

Queries

Queries determine which elements and changes are observed and reported on. There are four types of Query objects:

• attribute
• element
• characterData
• all

Attribute Query

Summarize changes to the presence and value of the given attribute throughout the observed subtree.

Query Format

{
  /**
   * The name of a single attribute to observe throughout the subtree.
   */
  attribute: string 
}

Summary Format

{
  /**
   * All elements presently in the subtree and having the given attribute,
   * but that were not in the subtree, lacked the given attribute or both.
   */
  added: Node[]

  /**
   * All elements previously in the subtree and having the given attribute,
   * but that now are not in the subtree, lack the given attribute or both.
   */
  removed: Node[]

  /**
   * All elements previously and presently in the subtree and previously and
   * presently having the given attribute, for whom the value of the given
   * attribute change.
   */
  valueChanged: Node[]
}

Element Query

Summarize the changes to the presence and location of the elements matching the given selector string, and (optionally) changes to the given set of attribute of those elements throughout the observed subtree.

Query Format

{
  /**
   * A “selector” string which describes what elements are to be observed.
   */
  element: string
  
  /**
   * A space separated list of attributes to observe for value changes
   * on the specified element.
   */
  elementAttributes?: string
}

Summary Format

{
  /**
   * All elements are presently in the subtree and match at least one
   * pattern, but previously were not in the subtree, now match zero
   * patterns or both.
   */
  added: Node[]

  /**
   * All elements were previously in the subtree and matched at least one
   * pattern, but which now are not in the subtree, new match zero patterns
   * or both.
   */
  removed: Node[]
  
  /**
   * All elements previously & presently in the subtree and previously &
   * presently matching at least one pattern, which were moved to be 
   * children of a new parent (their present parentNode is distinct from
   * the previous parentNode). 
   */
  reparented: Node[]

  /**
   * An object reporting attribute value changes. The object contains one key
   * for each attribute name contained in `elementAttributes`. The value of
   * each key is an array of elements previously & presently in the subtree
   * and previously & presently matching at least one pattern for whom the
   * corresponding attribute changed value. Only present if elementAttributes
   * was specified
   */
  attributeChanged: {
    attributeName1: Node[]
    attributeName2: Node[]
    ...
  }
}

Character Data Query

Summarize the effective changes to the presence and value of characterData nodes in the observed subtree.

Query Format

{
  /**
   * Indicates to observe to characterData nodes.
   */
  characterData: true 
}

Summary Format

{
  /**
   * All character data nodes presently in the subtree, but previously 
   * were not in the subtree.
   */
  added: Node[]

  /**
   * All character data nodes previously in the subtree, which now are
   * not in the subtree.
   */
  removed: Node[]

  /**
   * All character data nodes previously & presently in the subtree,
   * which were moved to be children of a new parent (their present 
   * parentNode is distinct from the previous parentNode).
   */
  reparented: Node[]

  /**
   * All character data nodes previously & presently whose value changed.
   */
  valueChanged: Node[]
}

All Query

Observes all changes to a given subtree.

Query Format

{
  /**
   * Indicates that all modifications to the subtree should be
   * observed.
   */
  all: true 
}

Summary Format

{
  /**
   * All nodes presently in the subtree, but previously were not in the
   * subtree.
   */
  added: Node[]

  /**
   * All nodes previously in the subtree, which now are not in the subtree.
   */
  removed: Node[]
  
  /**
   * All nodes previously & presently in the subtree, which were moved to be
   * children of a new parent (their present parentNode is distinct from the
   * previous parentNode).
   */
  reparented: Node[]

  /**
   * All nodes previously & presently in the subtree and previously &
   * presently are children of the same parent, but have moved to a new
   * location in their parentNode’s childList.
   */
  reorderd: Node[]

  /**
   * An object reporting attribute value changes. The object contains one key
   * for each attribute name contained in `elementAttributes`. The value of
   * each key is an array of elements previously & presently in the subtree
   * and previously & presently matching at least one pattern for whom the
   * corresponding attribute changed value. Only present if 
   * elementAttributes specified
   */
  attributeChanged: {
    attributeName1: Node[]
    attributeName2: Node[]
  ...
  }

  /**
   * All characterData nodes previously & presently whose value changed.
   */
  characterDataChanged: Node[]
}