@evolv/mutate

Evolv AI - Mutate

Mutate is a library of helpers to maintain persistent modifications to the rendered DOM of a web page for implementation of temporary, experimental changes and features for rapid experimentation.

It is intended to be framework independent and equally effective for SPAs and traditionally rendered webpages.

Getting Set Up

Installation

$ npm install @evolv/mutate

Building From Source

Clone the repository and run the following commands.

$ npm install
$ npm run build

Run Demo Website

There is a demo site included.

Fair warning: It is hideous and may cause seizures :)

$ npm run demo

Getting Started

The API for Mutate is similar in a lot of ways to the API of jQuery with a significant difference, that is selectors (Collectors) refer to all current and future matching Elements, and the functions to modify the DOM (Mutations) are persistent.

This means that you don't need to worry about timing, or dynamic areas of the rendered page.

Mutate also provides the ability to "project" Elements of the DOM into other Elements of the DOM, binding all interactions with the "projection" back to the original Elements.

As everyone building variants have learned the hard way, most Elements are dependent on their location in the DOM for both style and functionality. Projection allows the implementer to "move" and restyle Elements without losing the position dependent functionality of the original Elements.

Importing

import {collect, mutate} from '@evolv/mutate';

Basic Usage

The basic flow when using Mutate is to first define a Collector.

collect('<selector>', '<collector name>');

Then to define a Mutator for the Collector.

mutate('<collector name>').hide();

Mutators allow for Mutations to be chained together, similar to jQuery which will be evaluated in order of invocation.

mutate('<collector name>').text('<new text value>').classes({'<new class>': true});

Updating the Mutate library

For updating instructions refer to the Update Process

Reference

collect(selector: string, name: string, parent?: string): Collector

Create a new named Collector.

note If parent is not specified, the library will attempt to discover the closest non-volatile parents of any Element that match the selector.

Parameters

Name	Type	Description
selector	string	A CSS selector that the Collector should manage.
name	string	The name of the collector of future reference from mutate.
parent?	string	(Optional) An optional selector if the nearest non-volatile parent is known.

Returns

Collector

The Collector instance created. This Collector can be retrieved by name as well.

---

mutate(collectorName: string, variantKey?: string): Mutator

Create a Mutator associated with an named Collector

Parameters

Name	Type
collectorName	string
variantKey?	string

Returns

Mutator

Collector

The Collector provides all functionality for creating persistent select Elements currently present or that will be present on the page at a future time.

A Collector can have any number of Mutator associated with it.

destroyed: boolean

True if the Collector has been destroyed, otherwise False.

---

elements: Element[]

All Elements the Collector has collected.

---

id: string

The id of the Collector.

---

isValid: boolean

True if all validation has been satisfied, otherwise False.

---

name: undefined | string

The name of the Collector.

---

observedTargets: Element[]

All Elements the Collector is currently observing.

---

parentSelector: undefined | string

The current selector for parent Elements if set.

---

paused: boolean

True if the Collector is paused, otherwise False.

---

root: Element | Document

The outermost parent Element to observe.

---

selector: undefined | string

The current selector for Elements to be collected if set.

atLeast(count: number): Collector

Specify the minimum number of Elements the Collector must find before it is considered valid.

Parameters

Name	Type	Description
count	number	The minimum number of Elements the Collector must match to be considered value.

Returns

Collector

---

atMost(count: number): Collector

Specify the maximum number of Elements the Collector should find to be considered valid.

Parameters

Name	Type	Description
count	number	The maximum number of Elements the Collector must match to be considered value.

Returns

Collector

---

claim(): Promise<Element>

Permanently claim a collected Element for modification.

Returns

Promise<Element>

---

destroy(): void

Permanently destroy this Collector.

---

exactly(count): Collector

Specify the total number of Elements the Collector should find to be considered valid.

Parameters

Name	Type	Description
count	number	The total number of Elements the Collector must match to be considered value.

Returns

Collector

---

filter(predicate: Predicate): Collector

Add a Predicate Elements must satisfy to be included in the Collector.

Parameters

Name	Type	Description
predicate	Predicate	A Predicate Elements must satisfy to be included in the in the Collector

Returns

Collector

---

observeParent(parentSelector): Collector

Set a selector for the parent Elements to be observed for matching Elements.

Parameters

Name	Type	Description
parentSelector	string	The selector for parent Elements.

Returns

Collector

---

pause(): Collector

Pause collection and Element related notifications for this Collector.

Returns

Collector

---

subscribe(listener: ElementListener): Collector

Subscribe to notifications about the changing of Elements within the Collector.

Parameters

Name	Type	Description
listener	ElementListener	A callback to be notified about changes in the Elements.

Returns

Collector

---

subscribeState(listener: CollectorStateListener): Collector

Subscribe to notifications about the changing of state within the collector.

Parameters

Name	Type	Description
listener	CollectorStateListener	A callback to be notified when the state of the Collector changes.

Returns

Collector

---

unpause

unpause(): Collector

Unpause collection and Element related notifications for this Collector.

Returns

Collector

---

validate(predicate: Predicate): Collector

Add a Predicate that the Collector must satisfy before it is considered valid and ready to apply Effects.

Parameters

Name	Type	Description
predicate	Predicate	A Predicate the collector must meet before applying Effects.

Returns

Collector

---

within(`millis`: number): Collector

Specify the maximum amount of time in milliseconds that a Collector has to satisfy all validation criteria.

Parameters

Name	Type	Description
millis	number	The maximum amount of time the Collector has to satisfy validation criteria.

Returns

Collector

Mutator

Mutator provides a collection of methods to persistently mutate the DOM.

with: Binder

Bind Effects to non-DOM related events or state changes.

The bound value will be available for use in Effects as well as triggering reapplication of Effects.

Type declaration

Name	Type
attr	(attrName: string, transform?: (v: any) => any) => Binder
content	(transform?: (v: any) => any) => Binder
context	(propertyName: string, transform?: (v: any) => any) => Binder

apply(transform): Mutator

WARNING! This function is experimental and should only be used in testing.

Parameters

Name	Type	Description
transform	(subject: Element) => Element	A function that modifies the DOM of subject.

Returns

Mutator

---

attributes

attributes(attributes): Mutator

Set attributes on the Elements in the Collector.

Parameters

Name	Type	Description
attributes	object | Map<string, string | (state: Map<string, any>) => string>	A {@type Map} of attribute names to {@type string} or {@type (() => string)} representing their desired state.

Returns

Mutator

---

classes

classes(classes): Mutator

Set or remove classes on the Elements in the Collector.

Parameters

Name	Type	Description
classes	object | Map<string, boolean | (state: Map<string, any>) => boolean>	A {@type Map} of class names to {@type boolean} or {@type (() => boolean)} representing their desired state.

Returns

Mutator

---

customEffect(initialize, modify, revert): Mutator

Create a custom Effect that is persistently applied.

Parameters

Name	Type	Description
initialize	() => void	The function to be invoked to initialize the Effect.
modify	() => void	The function to be invoked when an Element is modified.
revert	() => void	The function to be invoked when the Effect should be reverted.

Returns

Mutator

---

hide(): Mutator

Hide all Elements in the Collector.

Returns

Mutator

---

html(newHtml, clone?): Mutator

Replace the HTML content of the Elements matched by the Collector.

Parameters

Name	Type	Default value	Description
newHtml	string | Node[]	undefined	The new HTML or Nodes to replace the content with.
clone	boolean	true	Whether or not a the nodes should be cloned before insertion. (Default: True)

Returns

Mutator

---

insert

insert(nodes, clone?): Mutator

Insert one or more Nodes into all elements in the Collector.

Parameters

Name	Type	Default value	Description
nodes	string | Node | Node[]	undefined	The Nodes to insert, or a string containing the HTML to insert.
clone	boolean	true	Whether or not a the nodes should be cloned before insertion. (Default: True)

Returns

Mutator

---

once(): Mutator

Specify that the Effects be applied no more than once.

Returns

Mutator

---

pause(): Mutator

Pause all Effects that are applied through this Mutator.

Returns

Mutator

---

project(to): Mutator

Clone and hide an Element, mapping all events from the clone into the original elements. The clone is then inserted into the DOM element that matches the {@param to} selector.

The purpose of the functionality is to avoid disabling or otherwise negatively impacting existing event listeners.

Parameters

Name	Type	Description
to	string	The selector for an element into which the cloned Element should be projected.

Returns

Mutator

---

reevaluate(): Mutator

Reinitialize all Effects on the Elements in the Collector.

Returns

Mutator

---

remove(nodes: Node[]): Mutator

Remove the specified Nodes from all elements in the Collector.

Parameters

Name	Type	Description
nodes	string | Node | Node[]	the Nodes or a selector for Nodes that should be removed.

Returns

Mutator

---

revert(subject?): Mutator

Revert all Effects applied through this Mutator to all Elements in the Collector or the specified {@param subject}.

Parameters

Name	Type	Description
subject?	Element	(Optional) The Element to revert the Effects on.

Returns

Mutator

---

show(): Mutator

Show all Elements in the Collector.

Returns

Mutator

---

styles(styles): Mutator

Set styles on the Elements in the Collector.

Parameters

Name	Type	Description
styles	object | Map<string, string | (state: Map<string, any>) => string>	A {@type Map} of style names to {@type string} or {@type (() => string)} representing their desired state.

Returns

Mutator

---

text(newText: string): Mutator

Replace the text content of the Elements matched by the Collector.

Parameters

Name	Type	Description
newText	string | (state: default) => string	The new text content.

Returns

Mutator

---

unpause(): Mutator

Unpause all Effects that are applied through this Mutator.

Returns

Mutator

---

interface CollectorStateListener

Type declaration

(collectorState, collector): void

Parameters

Name	Type
collectorState	CollectorState
collector	Collector

---

interface ElementListener

Type declaration

(action, element, elementList): void

Parameters

Name	Type
action	EventType
element	Element
elementList	Element[]

---

interface Predicate

Type declaration

(element): boolean

Parameters

Name	Type
element	HTMLElement

Returns

boolean

How to test your changes

1. run npm start
2. Create a simple website or use codesandbox
3. Add a snippet to head <script src="http://localhost:8080/index.js"></script> (make sure that your local is running on 8080, otherwise update src)
4. Apply changes to the website in the console

evolv.collect('h1', 'l6aiigykj')
evolv.mutate("l6aiigykj").html("Test");