@wmdigi/dom

A lightweight, type-safe DOM manipulation library with jQuery-like syntax.

Installation

# Using npm
npm install @wmdigi/dom

# Using yarn
yarn add @wmdigi/dom

# Using bun
bun add @wmdigi/dom

Usage

import { $ } from "@wmdigi/dom";

// Basic selectors
$(".button").addClass("active");
$("#main").hide();
$('input[type="text"]').val("Hello");

// Class checking
if ($(".card").hasClass("active")) {
	console.log("Card is active");
}

// Timeout utility
const clear = $.timeout(() => {
	console.log("This will run after 1 second");
}, 1000);

// Optional: Cancel timeout
clear();

// Chaining
$(".card").addClass("highlight").attr("data-active", "true").show();

// Type-safe event handling
$<HTMLButtonElement>(".submit-button").on("click", (e) => {
	console.log("Button clicked at:", e.clientX, e.clientY);
});

// Input handling with type safety
$<HTMLInputElement>('input[name="email"]').val("[email protected]");

// DOM Ready
$.ready(() => {
	console.log("DOM is ready");
});

// Creating elements
$.create('<div class="new">Content</div>').addClass("active");

API

Selectors

• $(selector) - Select elements using CSS selector
• $(element) - Wrap DOM element
• $(elements) - Wrap array of DOM elements

Methods

• .first - Get first element
• .array - Get array of elements

Values & Content

• .val([value]) - Get/set input value
• .text([content]) - Get/set text content

Classes

• .addClass(...classes) - Add classes
• .removeClass(...classes) - Remove classes
• .toggleClass(class) - Toggle class
• .hasClass(class) - Check if element has class

Attributes

• .attr(name, [value]) - Get/set attribute

Events

• .on(event, callback) - Add event listener

Display

• .hide() - Hide elements
• .show() - Show elements

Static Methods

• $.ready(callback) - DOM ready handler
• $.create(html) - Create element from HTML
• $.timeout(callback, ms) - Execute callback after delay with auto cleanup

Type Safety

The library is fully typed and provides TypeScript support out of the box:

// Proper type inference
$<HTMLInputElement>("input").val(); // Returns string
$<HTMLButtonElement>("button").on("click", (e) => {
	// e is properly typed as MouseEvent
});

Development

# Clone the repository
git clone https://github.com/wmdigi/dom.git
cd dom

# Install dependencies
bun install

# Build
bun run build

Publishing

# Publish patch version (1.0.0 -> 1.0.1)
bun pub

# Publish minor version (1.0.0 -> 1.1.0)
bun pub minor

# Publish major version (1.0.0 -> 2.0.0)
bun pub major

This will automatically:

1. Build the library
2. Commit changes
3. Bump version
4. Push to git (with tags)
5. Publish to npm

License

MIT

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Credits

Created by Wonder Makers - a digital studio, making the web simpler, one library at a time.