@aegisjsproject/iota

A zero-build, fine-grained reactivity library leveraging the TC39 Signals proposal.

Iota delivers the microscopic DOM mutation performance of compiled frameworks (like Solid or Svelte) entirely at runtime. It bypasses the Virtual DOM by surgically targeting individual Text and Attr nodes, utilizing Explicit Resource Management (DisposableStack) for deterministic memory cleanup.

• Code of Conduct
• Contributing

Features

• Zero-Build: Runs natively in the browser. No compilers, no bundlers required.
• Micro-Updates: Mutates specific Text and Attr nodes. Re-renders are physically impossible.
• Deterministic Cleanup: Built-in memory management via Symbol.dispose and DisposableStack prevents zombie listeners.
• Security by Default: Bypasses innerHTML during reactive updates. By assigning directly to Node.textContent and Attr.value, markup injection is neutralized by the platform.
• Web Component Native: Designed to cleanly hydrate Shadow DOMs and standard elements alike.

Installation

NPM

npm install @aegisjsproject/iota

<script type="importmap">

<script type="importmap">
  "imports": {
    "@shgysk8zer0/signals": "https://unpkg.com/@shgysk8zer0/[email protected]/signals.js,
    "@aegisjsproject/iota": "https://unpkg.com/@aegisjsproject/[email protected]/iota.js"
  }
</script>

Usage

Iota uses string placeholders (HTML comments and data-attributes) to position signals in your markup, which are then hydrated via $observe().

import { $text, $attr, $observe } from '@aegisjsproject/iota';
import { html } from '@aegisjsproject/core/parsers/html.js';
import { onInput, observeEvents } from '@aegisjsproject/callback-registry';
import { sanitizer as sanitizerConfig } from '@aegisjsproject/sanitizer/config/base.js';

// Manage lifecycle natively
const stack = new DisposableStack();

// Initialize signals and bind them to the stack
const $name = stack.use($text('World'));
const $value = stack.use($attr('value', () => $name.get()));

document.body.append(html`
    <h1>Hello, ${$name}!</h1>
    <form id="container">
        <input 
            type="text" 
            ${$value} 
            ${onInput}="${$name.handleEvent}" 
        />
        <button type="button" command="--dispose" commandfor="root">Dispose</button>
    </form>
`);

// Hydrate the DOM (replaces placeholders with live Text/Attr nodes)
$observe();
observeEvents();

// Tie disposal to a DOM event (e.g., Invoker Commands or unmount lifecycle)
document.addEventListener('command', ({ command }) => {
    if (command === '--dispose') stack.dispose();
});

API Reference

Primitives

• $text(value | computeFn): Creates a TextState or TextComputed signal. Returns an HTML comment placeholder <!--ref--> when cast to a string.
• $attr(name, value | computeFn): Creates an AttrState or AttrComputed signal. Returns a data-attribute placeholder data-attr-signal="ref" when cast to a string.
• $signal(value): Creates a base DisposableState. Includes a .handleEvent(e) method that automatically updates the signal value from form inputs.
• $computed(fn): Creates a base DisposableComputed signal.

Observers & Hydration

• $observe(target = document.body, { stack, signal, base } = {}): Walks the target DOM node, locates signal placeholders, and replaces them with live, reactive Text and Attr nodes.
• observeTextSignalRefs(...): Hydrates only text nodes.
• observeAttrSignalRefs(...): Hydrates only attribute nodes.

Watchers

• $watch(signal, callback): Manually subscribe to a signal.
• $unwatch(signal): Stop tracking a specific signal.
• unwatchSignalCallback(signal, callback): Remove a specific callback from a signal.

Registry & Internal

• RegistryKey: An extended String representing the signal's internal ID. Implements [Symbol.dispose] to automatically unwatch and unregister the associated signal when the stack clears.
• registerSignal(ref, signal) / unregisterSignal(ref): Manages the global Map of active signals used during hydration.