@untemps/dom-observer

Class to observe DOM mutations of a specific element in one-shot or continuous mode.

The class is a wrapper around the MutationObserver API to target an element in particular.
That means you can observe an element to be added to the DOM and access to its properties, an attribute from that element to be changed and get the old and the new values, the element to be removed from the DOM and destroy all its dependencies.

Installation

yarn add @untemps/dom-observer

Usage

Import DOMObserver:

import { DOMObserver } from '@untemps/dom-observer'

Create an instance of DOMObserver:

const observer = new DOMObserver()

Wait for an element to be added to, removed from or changed in the DOM

Two observation modes are available :

• One-shot: Get a promise from the wait method to observe a mutation once.
• Continuous: Register a callback in the wait method and be notified every time a mutation you declare to be observed occurs.

To switch from one mode to another, you just have to pass a callback as second parameter to turn continuous mode on or leave it null to get a promise.

Continuous mode

Call the wait method with the element or the selector of the element you want to target, a callback function and an optional object to initiate the observation.

Once the element is added to, removed from or changed in the DOM, the callback function is triggered with various number of arguments depending on the observed event.

import { DOMObserver } from '@untemps/dom-observer'

const observer = new DOMObserver()
const onEvent = (node, event, { attributeName } = {}) => {
	switch (event) {
		case DOMObserver.REMOVE: {
			console.log('Element ' + node.id + 'has been removed')
		}
		case DOMObserver.CHANGE: {
			console.log('Element ' + node.id + 'has been changed (' + attributeName + ')')
		}
	}
}
observer.wait('#foo', onEvent, {events: [DOMObserver.ADD, DOMObserver.REMOVE]})

One-shot mode

Call the wait method with the element or the selector of the element you want to target, null as second parameter and an optional object to initiate the observation.

Once the element is added to, removed from or changed in the DOM, the promise is resolved with various number of arguments depending on the observed event.

In this mode, if the element is not added before the timeout elapses, the promise will be rejected with an error object.

import { DOMObserver } from '@untemps/dom-observer'

const observer = new DOMObserver()
const { node, event, options: { attributeName } } = observer.wait('#foo', null, {events: [DOMObserver.REMOVE, DOMObserver.CHANGE]})
switch (event) {
	case DOMObserver.REMOVE: {
		console.log('Element ' + node.id + 'has been removed')
	}
	case DOMObserver.CHANGE: {
		console.log('Element ' + node.id + 'has been changed (' + attributeName + ')')
	}
}

wait method arguments

| Props | Type | Description | | -------------------- | -------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | target | Element or String | DOM element or selector of the DOM element to observe. See querySelector spec | | onEvent | Function or null | Callback triggered when an event occurred with the observed element (depending on the events listed in events option. Pass null to activate one-shot mode and retrieve a promise from the method | | options | Object | Options object: | | - events | Array | List of events to observe (All events are observed by default) | | - timeout | Number | Duration (in ms) of observation before triggering the onError callback (DOMObserver.ADD event only) | | - onError | Function | Callback triggered when timeout elapses (DOMObserver.ADD event only) | | - attributeFilter | Array | List of attribute names to observe (DOMObserver.CHANGE event only) |

onEvent arguments

| Props | Type | Description | | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | node | Node | Observed element node | | event | String | Event that triggered the callback | | options | Object | Options object: | | - attributeName | String | Name of the attribute that has changed (DOMObserver.CHANGE event only) | | - oldValue | Any | Old value of the attribute that has changed (DOMObserver.CHANGE event only) |

onError arguments

| Props | Type | Description | | ------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------- | | error | Error | Error thrown |

Events

DOMObserver static properties list all observable events.

| Props | Description | |----------------------|-------------------------------------------------------------------------------------------| | DOMObserver.EXIST | Observe whether the element is already created (not necessarily added to the DOM though) | | DOMObserver.ADD | Observe when the element is added to the DOM | | DOMObserver.REMOVE | Observe when the element is removed from the DOM | | DOMObserver.CHANGE | Observe when an attribute has changed on the element | | DOMObserver.EVENTS | Array of all four events |

One or more events can be passed to the events option of the wait method. By default, all events are observed.

{ events: [DOMObserver.ADD, DOMObserver.REMOVE] }
{ events: DOMObserver.EVENTS }

Discard observation

Call the clear method to discard observation:

await observer.clear()

Example

import { DOMObserver } from '@untemps/dom-observer'

const onEvent = (node, event, { attributeName } = {}) => {
	switch (event) {
		case DOMObserver.EXIST: { 
			console.log('Element ' + node.id + 'exists already')
		}
		case DOMObserver.ADD: {
			console.log('Element ' + node.id + 'has been added')
		}
		case DOMObserver.REMOVE: {
			console.log('Element ' + node.id + 'has been removed')
		}
		case DOMObserver.CHANGE: {
			console.log('Element ' + node.id + 'has been changed (' + attributeName + ')')
		}
	}
}
const onError = (err) => {
	console.error(err.message)
}
const observer = new DOMObserver()
observer.wait(
    '.foo',
    onEvent,
    {
    	events: [DOMObserver.EXIST, DOMObserver.ADD, DOMObserver.REMOVE, DOMObserver.CHANGE],
        timeout: 2000,
        onError,
        attributeFilter: ['class']
    }
)

Development

A demo can be served for development purpose on http://localhost:10001/ running:

yarn dev