Dom (@m5nv/dom)

A nano‑jQuery–like DOM manipulation library for evergreen browsers.

Overview

@m5nv/dom is a zero‑dependency library that wraps most commonly used native DOM APIs in a chainable, jQuery‑like fluent API. Event binding, class manipulation (add, remove, toggle, has), attribute handling, CSS styling, and DOM traversal can be achieved with much less code without loss of performance or code comprehension.

Why

The Document Object Model is like a castle. You might know it exists and have seen it in action using your favorite frameworks. The hard truth is you don't know it well enough until you explore it on your own.

Frameworks are like tour buses with tour guides—they keep you on the trodden path. On the flip side, exploring the DOM using its API can get tiring. You know the roads to take to get to the parts of the DOM you want to interact with—up close. This library is designed to be your bicycle, helping you get there faster without the baggage or the guardrails offered by frameworks.

Concepts

Selectors

A selector in @m5nv/dom is a value used to specify which DOM elements to wrap into a chainable collection. The library supports several types of selectors:

• CSS Selectors (String):
  Pass a CSS selector string (e.g., "#myId", ".my-class", "div > p") to internally use document.querySelectorAll to select elements.

• DOM Node:
  Pass a single DOM node (e.g., the result of document.getElementById("myId")) to wrap that specific element.

• NodeList or Array of Nodes:
  Pass a NodeList (e.g., from document.querySelectorAll) or an array of DOM nodes, and each node will be wrapped.

• Global Objects:
  Pass the global window or document objects to work with them directly.

By abstracting selectors, @m5nv/dom enables you to interact with any set of elements in a consistent, chainable way.

Features

• Minimal Footprint:
  Minimal code with no loss in performance.

• Chainable API:
  Write fluent code that reads naturally—no more nesting callbacks or cumbersome syntax.

Installation

npm

npm install @m5nv/dom

Usage

Import the default export (recommended aliases: $ or dom):

import $ from "@m5nv/dom";

Example: Selecting Elements & Event Binding

// Bind a click event to a button
$("#myButton").on("click", () => console.log("Button clicked!"));

// Toggle a class on an element
$("#myPanel").toggleClass("active");

Equivalence Examples

1. Element Selection & Event Binding

Native DOM:

const btn = document.getElementById("myButton");
btn.addEventListener("click", () => console.log("Clicked!"));

@m5nv/dom:

$("#myButton").on("click", () => console.log("Clicked!"));

2. Class Manipulation

Native DOM:

document.querySelector(".item").classList.add("active");
document.querySelector(".item").classList.toggle("active");
const has = document.querySelector(".item").classList.contains("active");

@m5nv/dom:

$(".item").addClass("active");
$(".item").toggleClass("active");
const has = $(".item").hasClass("active");

3. DOM Traversal

Native DOM:

const parent = document.getElementById("child").parentNode;

@m5nv/dom:

$("#child").parent();

API Reference

When you call dom(selector), you receive an object with the following methods:

Selection & Traversal

• dom(sel)
  Wraps a CSS selector, DOM node, or NodeList into a chainable object.

• find(selector)
  Returns a new wrapped collection of descendant elements.

• closest(selector)
  Returns the nearest ancestor matching the selector.

• next()
  Returns the next sibling element.

• parent()
  Returns the parent node.

Event Binding

• on(event, callback)
  Binds an event listener to all selected elements.

Iteration

• each(callback)
  Iterates over each element, passing (index, element) to the callback.

Class Manipulation

• addClass(className)
  Adds the specified class to all elements.

• removeClass(className)
  Removes the specified class from all elements.

• toggleClass(className)
  Toggles the class on all elements.

• hasClass(className)
  Returns a boolean indicating if the first element has the specified class.

Attributes & CSS

• attr(name, value?)
  Gets or sets an attribute. (If value is omitted, returns the attribute on the first element.)

• css(property, value)
  Sets an inline CSS style on all elements.

Contributing

Contributions to improve @m5nv/dom are welcome. Please submit issues or pull requests on our GitHub repository.

License

Distributed under the MIT License. See LICENSE for details.

Happy DOM-ing!