@einfach.design/el

Small DOM selector helper with a stable root import and an SSR-safe inert fallback.

Install

npm install @einfach.design/el

Import

import { el } from "@einfach.design/el";
import type { El, ElCache, ElOptions } from "@einfach.design/el";

The package has one public entry point: @einfach.design/el.

Select Elements

const button = el<HTMLButtonElement>("#save");
const byId = el.byId<HTMLButtonElement>("save");
const items = el.all<HTMLLIElement>(".item");

el(...) and el.byId(...) return an element or null. el.all(...) returns the native NodeListOf<Element> result from querySelectorAll.

Class Lists

const actions = el.all.classList(".action");

actions.add("is-ready");
actions.toggle("is-selected", true);
actions.contains("is-ready");

el.all.classList(...) applies class operations to every element in the resolved list.

Scoped Lookup

const item = el(".item", { root: "#dialog" });
const labels = el.all(".label", { root: document.querySelector("form")! });

root is the root identity for DOM lookup, cache reads, and cache clear semantics. It does not imply subtree invalidation beyond the resolved root.

Missing Results

const fallback = el("#missing", {
  onMissing: () => document.createElement("div"),
});

const nodes = el.all(".missing", {
  onMissing: (_nodes) => document.querySelectorAll(".fallback"),
});

Missing hooks only affect selector results. They do not change context resolution.

Cache

Caching is opt-in.

const shared = el("#save", { cache: true });
el.cache.clear(true);

const cache = el.cache.create();
const first = el.byId("save", { cache });
cache.clear("save", { lookup: "el.byId" });

cache: true uses the shared cache. el.cache.create() creates a dedicated cache. Only cache handles returned by el.cache.create() are accepted; passing an arbitrary object as cache throws TypeError.

Use cacheMisses: true when missing results should be cached explicitly.

el("#optional", { cache: true, cacheMisses: true });

SSR

In non-DOM environments, the exported el object is inert:

el("body"); // null
el.byId("app"); // null
el.all(".item").length; // 0
el.cache.create().clear(true); // no-op

Cache option validation still applies in SSR.

License

MIT. Attribution is appreciated but not required.