@webreflection/utils

^{Social media photo by Benjamin Lehman on Unsplash}

A curated, TypeScript-friendly collection of utilities:

• accessor - wrap a { get, set } descriptor as one function: zero args read, one arg write
• all - Promise.all via object destructuring
• ascii - basic string-to-buffer conversion without validation
• async-accessor - wrap a { get, set } descriptor as one async function: zero args read, one arg write
• base64 - encode and decode binary data as base64 strings, with optional compression - base64/decode, base64/encode, base64/stream, and base64/transformer provide respective utilities
• bound-once - retrieve unique bound methods per realm
• bound-key - cache bound functions per context key, for DOM and other reuse
• bound - retrieve one-off bound methods
• cache - temporal Map for same-tick or short-lived memoization; supports Map put and getOrInsert helpers
• caller-of - borrow a method as (thisArg, ...args) => result via fn.call.bind(fn)
• class - factory for subclassing “illegal” constructors (Function, DOM elements, …) via a prototype swap, with solid TypeScript types
• content - build factories that parse markup strings into DocumentFragment instances within a chosen element context
• dedent - strip common leading indentation from the first non-empty line, as a template tag or on strings
• devtools - DevTools-style $, $$, and $x helpers for CSS and XPath queries
• dom-content - parse HTML or SVG markup strings into a DocumentFragment via ready-made html and svg helpers
• dom-diff - reconcile two arrays of DOM nodes (or persistent fragments) before a pin: remove extras, insert or reorder via moveBefore when available
• dom-fragment - DocumentFragment subclass that keeps a persistent range between comment markers, with ChildNode-like helpers for dom-diff
• dom-observer - shared document-wide MutationObserver (including shadow roots) with a subscriber set for add/remove tracking; sticky once per realm
• dom-signals - signals plus DOM subscribe/unsubscribe via dom-observer so detached nodes cannot leak listeners
• empty - frozen shared empty references: array, object, or null-prototype object
• fetch - proxied fetch that exposes Response fields as thenables (await fetch(url).text, await fetch(url).status)
• global - lazily trap globalThis so native constructors and prototypes cannot be polluted after first access
• has-own - quick polyfill for Object.hasOwn() on older browsers
• id - unique int32 counter that wraps automatically at 2 ** 31 - 1
• instance-of - return a constructor from an instanceof list so switch/case can replace switch (true)
• iterable - make plain objects iterable as Object.entries(object) pairs, without touching objects that are already iterable
• json-callback - stringify callbacks for JSON payloads, normalizing method shorthand to named function form
• json-storage - JSON-aware, iterable, Map-like localStorage / sessionStorage facade with Map put
• libwabt - bootstrap the original WABT libwabt.js in place to parse, test, and convert WAT ↔ WASM with no extra files; wat-tag wraps the common compile-and-instantiate path as a template tag
• map - native Map subclass with Map put
• next-resolver - unique ID + promise pairs; the old next-resolver module, brought in to drop that package’s heavy @webreflection/utils dependency and keep size constrained
• plain-tag - transform a generic template tag into a plain string
• python-tag - bootstrap Pyodide or MicroPython and run Python via a template tag, a string call, or a bound options tag
• ref-id - unique int32 identifier per WeakMap-compatible key
• ref-signals - signals plus subscribe/unsubscribe tied to any WeakMap-compatible key, cleaned up via FinalizationRegistry when the ref is collected
• registry - validated Map with duplicate-key protection by default; inherits Map put
• set - native Set subclass with Set put
• shared-array-buffer - simulate SAB when not available
• signals - minimalistic signals with explicit dependency lists; Object.is skips same-value writes (new Signal(v, true) / eager to notify every write): signal, computed, batch, and effect
• state-signals - signals plus create / update / raw helpers that turn plain objects into reactive state, with subscribe / unsubscribe by property key and dispose (also via using)
• sticky - keep useful values stable once per realm
• wat-tag - libwabt as a template tag: pass features, init, and import once, then compile WAT and dispose via using or [Symbol.dispose]()
• weak - import both weakmap and weakset together when both are needed
• weakmap / weak-map - native WeakMap subclass with Map put
• weakset / weak-set - native WeakSet subclass with Set put
• with-resolvers - use a self-bound Promise.withResolvers() helper for older runtimes

Background

I’ve written too many micro-utilities. When I realized I couldn’t even remember their names or where to find them, I decided to create this module. The philosophy behind it is pretty simple:

• ESM by default: most micro-utilities published as dual modules need extra maintenance I’m no longer interested in; ESM is the standard these days, and CJS can import it anyway
• if I repeat the same pattern more than once, I drop a quick helper in here so I never have to write it again
• every utility has zero runtime dependencies; the only dependencies in this repo are c8 for coverage and TypeScript for types
• every utility is 100% covered and TypeScript-friendly via its definitions, while the implementation stays plain JS for broad compatibility
• every utility can be imported individually as a standalone subpath, so via CDN you can grab only the utils a project needs
• some utilities are deliberately simple, opinionated, or both; none are meant as polyfills (unlike @ungap)

That’s it. If you keep solving or rewriting the same patterns, take a look here — and the dedicated docs page goes deeper.

I’ll gradually deprecate, archive, and abandon the older micro-utilities that landed here. For now, I just want one place I can trust and use as needed.

Map put convention

Every utility that subclasses Map or WeakMap — map, cache, registry, and weakmap — adds a put(key, value) method. It stores the entry like set, but returns the stored value instead of the map reference.

That replaces the awkward get-or-insert dance where set returns the map, not the value, and the initializer cannot be deferred:

// before: value is always computed; set returns the map, not the value
const value = map.get(key) || (map.set(key, expensive()), map.get(key));

// after: expensive() runs only when the key is absent
const value = map.get(key) ?? map.put(key, expensive());

Use set when map chaining is needed; use put when the stored value should flow into the next expression.

json-storage is not a Map subclass, but its Map-like API follows the same put contract.

Set put convention

Every utility that subclasses Set or WeakSet — set and weakset — adds a put(value) method. It stores the entry like add, but returns the value instead of the set reference.

That replaces the awkward membership dance where add returns the set, not the value, and a separate reference is needed to keep using the entry:

// before: add returns the set, not the value
set.has(value) ? value : (set.add(doSomethingWith(value)), value);

// after: put returns the value, not the set
set.has(value) ? value : set.put(doSomethingWith(value));

Use add when set chaining is needed; use put when the stored value should flow into the next expression.

Patches

Some utilities rely on modern APIs that are not available everywhere. For broader compatibility, the ungap project is usually a better fit — but when something breaks in older browsers, the patch/* exports cover only the specific APIs this collection needs:

• patch/dispose — returns Symbol.dispose when available, otherwise Symbol.for('dispose') (not a polyfill; never defines Symbol.dispose)
• patch/set-union — optionally polyfills Set.prototype.union when missing

MIT-style license.