Browser Utilities

These APIs are available directly on Utils in this wrapper package.

They cover DOM access, events, storage, cookies, and runtime stylesheet injection.

Browser-safe vs browser-required

The browser entrypoint contains two kinds of behavior:

• soft runtime guards: some helpers return null or no-op when browser globals are missing
• strict DOM helpers: some functions throw when a real document is required

This distinction matters in hybrid apps.

Soft runtime guards

• storage helpers use safe accessors for localStorage and sessionStorage
• cookie helpers return null or no-op when document is unavailable
• stylesheet helpers no-op when document.head is missing

Strict DOM requirements

• getElem()
• createElem()
• templateToHtml()
• DOM insertion helpers

These functions expect a real DOM and throw if the runtime cannot provide one.

Storage utilities

The storageUtils namespace provides helpers for local storage, session storage, and cookies.

Local and session storage

• setLocalValue(key, value, stringify = true) stores values in localStorage.
• getLocalValue(key, parseJson = true) returns parsed JSON when possible, or the raw string when parsing is disabled or fails.
• removeLocalValue(key) removes a local storage key.
• setSessionValue(), getSessionValue(), and removeSessionValue() do the same for sessionStorage.

If stored data is invalid JSON, the read helpers report the parsing error and return the original string.

Example:

import Utils from '@carry0987/utils-full';

Utils.setLocalValue('preferences', { theme: 'light', density: 'compact' });
Utils.setSessionValue('csrf-token', 'token-123', false);

const preferences = Utils.getLocalValue<{ theme: string; density: string }>('preferences');
const token = Utils.getLocalValue('csrf-token', false);

Cookies

• setCookie(name, value, options?) writes a cookie with sensible defaults.
• getCookie(name) reads a cookie value.
• removeCookie(name) expires a cookie immediately.

Default cookie behavior:

• expires: 1 day from now
• path: /
• secure: false
• sameSite: Lax

Example:

import Utils from '@carry0987/utils-full';

Utils.setCookie('locale', 'en', {
  secure: true,
  sameSite: 'Strict',
});

console.log(Utils.getCookie('locale'));
Utils.removeCookie('locale');

DOM utilities

The domUtils module focuses on practical querying, creation, insertion, and traversal helpers.

Query and create

• getElem(selector) returns the first matching element.
• getElem(selector, 'all') returns all matching elements.
• getElem(existingElement) returns the element unchanged.
• createElem(tagName, attrs, text?) creates an element and applies attributes.

Insert nodes

• insertAfter(referenceNode, newNode) inserts a node or HTML string after a reference node.
• insertBefore(referenceNode, newNode) inserts a node or HTML string before a reference node.

Class helpers

• addClass(element, className)
• removeClass(element, className)
• toggleClass(element, className, force?)
• hasClass(element, className)

Parent and child traversal

• hasParent(element, selector, maxDepth?)
• findParent(element, selector)
• findParents(element, selector, maxDepth?)
• hasChild(element, selector)
• findChild(element, selector)
• findChilds(element, selector, maxDepth?)

Templates

• templateToHtml(templateOrFragment) converts a template fragment into an HTML string.

Example:

import Utils from '@carry0987/utils-full';

const title = Utils.createElem('h2', { class: 'section-title' }, 'API Reference');
document.body.appendChild(title);

Utils.insertAfter(title, '<p class="section-summary">Generated with Utils-Full-JS.</p>');
Utils.addClass(title, 'is-ready');

const summary = Utils.getElem('.section-summary');
console.log(Utils.findParent(summary as Element, 'body'));

const template = document.createElement('template');
template.innerHTML = '<div class="card">Content</div>';
console.log(Utils.templateToHtml(template));

Event utilities

The eventUtils module wraps native DOM events with typed helpers.

• addEventListener(element, eventName, handler, options?)
• removeEventListener(element, eventName, handler, options?)
• createEvent(name, detail?, options?) creates a CustomEvent
• dispatchEvent(eventOrName, element?, detail?, options?) dispatches either a pre-built event or a named custom event

dispatchEvent() returns false when the target or event type is invalid and reports the error.

Example:

import Utils from '@carry0987/utils-full';

const handler = (event: Event) => {
  console.log('Custom event received', event);
};

Utils.addEventListener(document, 'docs:ready', handler as EventListener);
Utils.dispatchEvent('docs:ready', document, { section: 'browser' });
Utils.removeEventListener(document, 'docs:ready', handler as EventListener);

Interactive browser playground

Live Editor

function BrowserUtilitiesPlayground() {
  const [count, setCount] = React.useState(() => Utils.getLocalValue('utils-full-docs-count') ?? 0);
  const [message, setMessage] = React.useState('No custom event yet');

  React.useEffect(() => {
    Utils.setStylesheetId('docs-live-');
    Utils.injectStylesheet(
      {
        '.utils-card': {
          padding: '16px',
          borderRadius: '14px',
          backgroundColor: '#fff7ed',
          border: '1px solid #fdba74',
        },
      },
      'browser-demo'
    );

    const handler = (event) => {
      setMessage(JSON.stringify(event.detail));
    };

    Utils.addEventListener(document, 'utils-full:preview', handler);

    return () => {
      Utils.removeEventListener(document, 'utils-full:preview', handler);
      Utils.removeStylesheet('browser-demo');
    };
  }, []);

  const increment = () => {
    const next = Number(count) + 1;
    setCount(next);
    Utils.setLocalValue('utils-full-docs-count', next);
    Utils.dispatchEvent('utils-full:preview', document, { count: next });
  };

  return (
    <div className="utils-card" style={{ display: 'grid', gap: 12 }}>
      <div>
        <strong>Stored click count:</strong> {count}
      </div>
      <button className="button button--primary" onClick={increment}>
        Save count and emit event
      </button>
      <div>
        <strong>Last event detail:</strong> {message}
      </div>
    </div>
  );
}

Result

Loading...

Runtime stylesheet utilities

The browser common module exports helpers for injecting small runtime-generated styles.

• stylesheetId stores the current stylesheet prefix, defaulting to utils-style
• replaceRule stores selector replacement rules, defaulting to .utils -> .utils-
• setStylesheetId(id) changes the stylesheet id prefix
• setReplaceRule(from, to) changes selector replacement behavior
• injectStylesheet(stylesObject, id?) creates a style element and inserts generated rules
• buildRules(ruleObject) converts a CSS-like object into a CSS string
• compatInsertRule(stylesheet, selector, cssText, id?) inserts a single generated CSS rule
• removeStylesheet(id?) removes the generated style element

Example:

import Utils from '@carry0987/utils-full';

Utils.setStylesheetId('docs-theme-');
Utils.setReplaceRule('.utils', '.docs');

Utils.injectStylesheet(
  {
    '.utils-card': {
      backgroundColor: '#ffffff',
      borderRadius: '16px',
      padding: '20px',
      boxShadow: '0 10px 30px rgba(18, 38, 63, 0.08)',
    },
  },
  'landing'
);

Utils.removeStylesheet('landing');