Als-DOM

Als-DOM is a lean, high-performing JavaScript library designed for efficient DOM manipulation and traversal. Emulating a jQuery-like interface, it offers an intuitive way to select and manipulate DOM elements while being much smaller in size, a characteristic crucial for performance-sensitive web applications.

Instalation and Usage

npm install als-dom

<script src="/node_modules/als-dom/dom.js"></script>
<script>
   const {$,$$,$$$} = Dom
</script>

Query selectors

$(selector, parent = document)

$ method similar to querySelector with only difference, the returned element has additional properties and methods.

Example:

const div = $('div.some') // instanceof HTMLElement || null
const span = div.$('span.some') || $('span.some',div)

$$(selector, parent = document)

$$ method similar to querySelectorAll with only difference, the returned collection is regular array with elements which has additional properties and methods.

$$$(selector, parent = document)

$$$ method similar to querySelectorAll with only difference, the returned collection is regular array.

Additional properties and methods

Attributes

All existing (only existing) attibutes have getters and setters with prefix $.

Example:

<div some="test"></div>
<script>
   const div = $('div')
   div.$some // test
   div.$some = 'super' // set new value
   div.$some // super
   div.$some = null // remove some attribute
   div.$some // null
</script>

Attribute which starts with json-, will try to parse json value on getter and stringify json value on setter. Attribute with value "true" and "false" will be converted to boolean type on getter. Attribute with value number will be converted to number.

Selecting elements

• $next: This is a getter that returns the next sibling element of the current element in the DOM tree. If there is no next sibling element, it will return the current element itself. It also adds additional methods and properties to the returned element.

• $prev: This is a getter that returns the previous sibling element of the current element in the DOM tree. If there is no previous sibling element, it will return the current element itself. It also adds additional methods and properties to the returned element.

• $parent: This is a getter that returns the parent element of the current element in the DOM tree. If the current element is the topmost element in the tree (i.e., the document), it will return itself. It also adds additional methods and properties to the returned element.

• $children: This is a getter that returns an array of all child elements of the current element in the DOM tree. Each child element in the array has additional methods and properties.

Creating new element

• $addBefore(newElement): This is a method that takes an HTMLElement or string representing an HTML fragment and adds it as a new element before the current element in the DOM tree. The new element is returned with additional methods and properties.

• $firstChild(newElement): This is a method that takes an HTMLElement or string representing an HTML fragment and adds it as the first child element of the current element in the DOM tree. The new child element is returned with additional methods and properties.

• $lastChild(newElement): This is a method that takes an HTMLElement or string representing an HTML fragment and adds it as the last child element of the current element in the DOM tree. The new child element is returned with additional methods and properties.

• $addAfter(newElement): This is a method that takes an HTMLElement or string representing an HTML fragment and adds it as a new element after the current element in the DOM tree. The new element is returned with additional methods and properties.

Additionally, please note that for the $addBefore(newElement), $firstChild(newElement), $lastChild(newElement), $addAfter(newElement) methods, if a string is provided as newElement, the string is treated as an HTML string, and it is first converted to a DOM Node before the operation. These methods return the new element (either the original HTMLElement or the newly created one from the string), with the added DOM methods and properties.

Selcting and manipulating collection

• $entries(attr,selector): This method returns an object where the keys are the attribute values of child elements, and the values are the child elements themselves. The attr parameter specifies the attribute name to use for the keys. If the selector parameter is provided, it will find a child element within each child to use for the attribute value, otherwise, it uses the attribute value from the child element itself.

• $values(attr,selector): This method returns an array of the attribute values of the child elements. The attr parameter specifies the attribute name to use. If the selector parameter is provided, it will find a child element within each child to use for the attribute value, otherwise, it uses the attribute value from the child element itself.

• $asc(attr,selector): This method sorts the child elements in ascending order based on the attribute value specified by the attr parameter. If the selector parameter is provided, it will find a child element within each child to use for the attribute value, otherwise, it uses the attribute value from the child element itself. The sorted children are appended back to the current element in the new order.

• $filter(attr,selector,remove=true): This method filters the child elements based on the attribute specified by the attr parameter. It returns an array of the remaining child elements. The attr parameter should be in the format attribute or attribute=value or attribute*=value or attribute^=value or attribute$=value or attribute|=value or attribute~=value. If the selector parameter is provided, it will find a child element within each child to use for the attribute value, otherwise, it uses the attribute value from the child element itself. If the remove parameter is set to true (default), it will remove the filtered elements from the DOM, otherwise, it sets the display style of the filtered elements to 'none'.

• $reverse(): This method reverses the order of the child elements within the current element and returns an array of the child elements in the new order.

Examples

// Assuming we have multiple div elements with the class name "some"
const divs = $$('div.some'); // Returns an array of HTMLElements or empty array

// This array can be looped over just like a regular array
divs.forEach(div => console.log(div));

// Since each element in the array has additional properties and methods, you can do the following:
const firstDiv = divs[0];

// Getting the next sibling
const nextSibling = firstDiv.$next;
console.log(nextSibling); 

// Getting the parent
const parent = firstDiv.$parent;
console.log(parent); 

// Adding a new element before the first div
firstDiv.$addBefore('<p>New paragraph before the first div</p>');

// Adding a new element after the first div
firstDiv.$addAfter('<p>New paragraph after the first div</p>');

// Adding a new element as the first child of the first div
firstDiv.$firstChild('<p>New first child for the first div</p>');

// Adding a new element as the last child of the first div
firstDiv.$lastChild('<p>New last child for the first div</p>');

// Filtering children elements of the first div based on an attribute
const filtered = firstDiv.$filter('data-value=100');
console.log(filtered);