Utilities

General-purpose helpers: UUID, clone, isEmpty, onceIdle, cookies, debounce/throttle.

import {
  uuid, deepClone, deepFreeze, isEmpty, safeClone,
  debounce, throttle, onceIdle, getCookieObj,
} from 'mates';

const id = uuid();                          // RFC 4122 v4
const copy = deepClone({ nested: [1, 2] });
deepFreeze(copy);                           // recursive Object.freeze
isEmpty('');                                // true
isEmpty({ a: 1 });                          // false
safeClone(copy);                            // structuredClone-safe clone helper

const search = debounce((q: string) => console.log(q), 400);
search('hi');                               // delayed
search.cancel();                            // cancel pending
search.flush();                             // run immediately if pending

const onScroll = throttle(() => {}, 100);
onceIdle(() => console.log('idle'));        // requestIdleCallback / setTimeout fallback
getCookieObj();                             // parse document.cookie → Record

Overview

Small helpers you reach for constantly: identity generation, deep copy/freeze, emptiness checks, idle scheduling, cookie parsing, and timing wrappers.

debounce and throttle return enhanced functions with .cancel() and .flush() — create them once outside the template. Runtime probes like isAtom live on Type Guards.

UUID generation & debounce

Generate RFC 4122 UUIDs on demand and observe debounce — the bottom value only updates 400 ms after you stop typing.

import { html, atom, renderApp, uuid, debounce } from 'mates';

const App = () => {

const ids = atom([uuid()]);

const search = atom('');

const debouncedSearch = atom('');

const doSearch = debounce((q) => debouncedSearch.set(q), 400);

return () => html`

Generate UUID

</button>

<button class="btn-ghost" @click=${() => ids.set([uuid()])}>Reset</button>

</div>

<span class="overline">Generated IDs</span>

${ids().map(id => html`<div class="mono">${id}</div>`)}

</div>

<input

.value=${search()}

@input=${e => { search.set(e.target.value); doSearch(e.target.value); }}

placeholder="Type to test debounce (400ms)…"

<span class="label">Typed:</span> <span>${search() || '—'}</span>

</div>

<span class="label">Debounced:</span>

<span>${debouncedSearch() || '—'}</span>

</div>

deepClone / deepFreeze / isEmpty

Clone mutates independently; freeze blocks further edits.

import { html, atom, renderApp, deepClone, deepFreeze, isEmpty } from 'mates';

const App = () => {

const note = atom('idle');

const run = () => {

const src = { nested: [1, 2], ok: true };

const copy = deepClone(src);

copy.nested.push(3);

deepFreeze(copy);

let froze = false;

try { copy.nested.push(4); } catch { froze = true; }

note.set(

'empty? ' + isEmpty({}) +

' | clone grew to ' + copy.nested.length +

' | freeze ' + (froze ? 'ok' : 'skipped')

);

};

return () => html`

<button class="btn-primary" @click=${run}>deepClone + deepFreeze + isEmpty</button>

</div>

};

renderApp(App, document.getElementById('app'));

API — General utilities

import { uuid, deepClone, deepFreeze, safeClone, isEmpty, debounce, throttle, onceIdle, getCookieObj } from 'mates';

Prop / Option	Type	Default	Description
`uuid()`	`string`	—	RFC 4122 v4 UUID. Uses crypto.randomUUID() when available.
`deepClone(value)`	`T`	—	Deep-copy via structuredClone (with a JSON fallback).
`safeClone(value)`	`T`	—	Clone helper tolerant of non-cloneable values.
`deepFreeze(value)`	`void`	—	Recursively Object.freeze a value in place.
`isEmpty(value)`	`boolean`	—	True for null/undefined, empty string, empty array/object, or empty Map/Set.
`debounce(fn, ms)`	`fn & { cancel, flush }`	—	Debounced fn. Also exposes `.cancel()` and `.flush()`. Same helpers as /docs/actions/debounce-throttle.
`throttle(fn, ms)`	`fn & { cancel, flush }`	—	Throttled fn (at most once per ms). Also exposes `.cancel()` and `.flush()`.
`onceIdle(fn)`	`void`	—	Schedule work on requestIdleCallback (setTimeout fallback).
`getCookieObj()`	`Record`	—	Parse document.cookie into a plain object.