code-snippets/javascript/js-extension/README.md

js-extension (JavaScript)

A tiny, dependency‑free utility class with a few DOM and string helpers that I often reach for in small projects and prototypes.

It includes:

• addGlobalEventListener — delegated events with a CSS selector
• createElement — quick DOM element creation with attributes, class, dataset, and text
• qs / qsa — short aliases for querySelector / querySelectorAll with optional parent
• strToHtml — convert an HTML string to a DocumentFragment
• isJson — quick check if a string parses as JSON
• sleep — simple delay (Promise-based)

Quick usage

Minimal examples showing what the helpers do. Adjust to your environment as needed.

// Assume jsExtension is available in scope

// 1) Delegated event listener
jsExtension.addGlobalEventListener("click", "[data-action=remove]", (e) => {
  const btn = e.target.closest("[data-action=remove]");
  btn?.closest(".item")?.remove();
});

// 2) Create element with attributes, class, dataset, and text
const card = jsExtension.createElement("div", {
  class: "card",
  id: "card-1",
  dataset: { id: "1", type: "example" },
  "aria-label": "Example card",
  text: "Hello!",
});

// 3) Shorthand query helpers
const firstItem = jsExtension.qs(".item");
const allItems = jsExtension.qsa(".item");

// 4) String to HTML fragment
const frag = jsExtension.strToHtml(`
  <ul>
    <li>One</li>
    <li>Two</li>
  </ul>
`);
document.body.appendChild(frag);

// 5) JSON check
jsExtension.isJson('{"a":1}'); // true
jsExtension.isJson('{a:1}');    // false

// 6) Sleep helper
await jsExtension.sleep(300);

API

addGlobalEventListener(type, selector, callback, options?, parent=document)

Adds a single delegated listener on parent and runs callback when the event target matches selector (or is inside an element that matches).

• type: string event type, e.g. "click"
• selector: CSS selector to match or closest() to
• callback: function receiving the event
• options: optional addEventListener options
• parent: HTMLElement | Document (defaults to document)

createElement(type, options={}) => HTMLElement

Creates an element and applies the provided options. Supported option keys:

• class: string — added via classList.add
• dataset: object — assigned to element.dataset[key] = value
• text: string — sets textContent
• any other key — assigned as attribute: setAttribute(key, value)

qs(selector, parent=document) => Element|null

Shorthand for parent.querySelector(selector). Returns null if parent is not a Document/HTMLElement.

qsa(selector, parent=document) => NodeList<Element>

Shorthand for parent.querySelectorAll(selector). Falls back to document.querySelectorAll when parent is not a Document/HTMLElement.

strToHtml(str) => DocumentFragment

Converts an HTML string into a DocumentFragment using Range#createContextualFragment.

isJson(str) => boolean

Returns true if JSON.parse(str) succeeds; otherwise false.

sleep(time) => Promise<void>

Resolves after time milliseconds using setTimeout.

Notes

• DOM helpers assume a browser environment (i.e., document is available).
• addGlobalEventListener uses event delegation; attach it once at a suitable ancestor.

License

See the repository-level LICENSE file.