@webreflection/utils

^{Social media photo by Benjamin Lehman on Unsplash}

A curated, TypeScript-friendly collection of utilities:

• 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 and base64/encode 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
• 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
• empty - frozen shared empty references: array, object, or null-prototype object
• 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
• map - native Map subclass with Map put
• plain-tag - transform a generic template tag into a plain string
• 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
• sticky - keep useful values stable once per realm
• weakmap - native WeakMap subclass with Map put
• weakset - 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.

MIT-style license.