Components in Exodra
A component is one value carrying two halves:
| Half | When it runs | What it is |
|---|---|---|
| the schema | once, when the module loads | the constant shape — static markup, plus the ports where values may later be put |
| the wiring function | once per instance | the code that puts values in those ports, through a connector |
That split is the whole design. Everything expensive — deciding what the markup is, which attribute lives where, how deep a node sits — happens once per component for the life of the process. What a render repeats is: clone the prepared element, then one indirect call per port.
There is no per-render tree, no props object to diff, and no walk at render time. A port is named by identity, so a wiring function cannot count wrong and does not look anything up.
The smallest component
import {
EXO_PORT_TEXT,
composeExoMachine,
createExoMachine,
createExoSchema,
exoPorts,
withExoWire,
} from '@exodra/core';
import type { TExoMachineNode } from '@exodra/core';
import { ExoDomBackend, withExoCompiler } from '@exodra/dom';
/** ONE backend for the application, at module level — it is the schema cache key.
* `render` arrives with the compiler: a bare backend has no way to turn a
* declaration into a schema, and says so at the type level. */
const backend = withExoCompiler(new ExoDomBackend());
const GreetingPorts = exoPorts({ name: EXO_PORT_TEXT });
// ── the schema: runs once, at module load ────────────────────────────
const greetingSchema = createExoSchema(GreetingPorts, (b) => {
b.el('p', { class: 'greeting' }, (p) => {
p.text('Hello, ');
p.el('strong', null, (strong) => {
strong.textPort(GreetingPorts.name);
});
});
});
// ── the machine: its wire writes the ports of each instance ─────────
const greetingMachine = composeExoMachine(
createExoMachine<TExoMachineNode>(greetingSchema),
(m) =>
withExoWire(m, (c) => {
c.text(GreetingPorts.name, 'world');
})
);
backend.render(greetingMachine, document.body);
backend.render mounts one instance, handed the params it is given.
There is no instance count, because a lone root has nothing else to be about and
no library asks an application how many copies of its root to make. Rows that
vary are a list — a children port filled by c.list (fixed) or by
a reconciler from createExoChildrenReconciler (live). That is also what a rival framework's
participant is doing when a benchmark says "render 1000 rows": the count belongs
to the list, never to the mount.
There are no props, anywhere. The initial state's second argument is the
instance's params, and that is the whole of what a view is told about itself. A row
is handed its own datum as its params by whoever builds it — the reconciler that
creates the row is the place that knows the item, so it wires the row with it.
Params are read once, when the instance is armed, and again only when wireExoNode
re-runs the wire. Props would have to be serviced: stored per instance, compared on
every update, and turned into a decision about which transitions to re-run. Params
cost one argument.
A machine is put together in two moves. createExoMachine(schema, options?) makes
the base machine: the schema, plus the createInitialState option when the
instance keeps state. Each decorator then adds one part and returns a new
machine, leaving its input untouched — withExoWire the wire, withExoHandlers
the event handlers, withExoEffects the effects, withExoTransitions the named
transitions callable from outside, read back as machine.transitions.
composeExoMachine(base, …steps) passes the base
through the steps in order, so a machine reads top to bottom: what it keeps, what
it can be told, what it writes, what it listens to, what it follows. A machine has
one wire; withExoWire on a machine that already has one throws (EXO0101).
Read createExoMachine<TWiring> by its type argument — written out, or
inferred from the exonode annotation of the createInitialState option when the
base machine is handed one. TWiring is what
every wire, handler, effect and transition may assume about the exonode it is handed: TExoMachineNode from
@exodra/core is the surface all backends share — attr, text, on,
provide, inject — so a component naming it is served, client-rendered and
hydrated as one value. A machine that also nests components takes
TExoChildrenWiring & TExoMachineNode, which adds one, list and build. Naming
one backend's exonode instead — createExoMachine<TExoDomNode> — types the
component against the browser alone, because a machine's exonode parameter is
contravariant. What the initial state returns is what the instance keeps: the
value lands in enode.state, typed as the return type in every wire, handler, effect and
transition. A machine that only fills ports returns nothing. A plain function that
works on the exonode takes TExoMachineNodeOf<typeof base>: the base machine's
exonode type with its state, which is why such a machine keeps its base in a
constant of its own (timerBase below).
Two details are worth reading twice:
- The ports are a value before the schema is, and the schema before the machine.
exoPortsdeclares the component's port interface,createExoSchemaplaces each port in the markup once, at module load, andcreateExoMachineis handed the result, so the ports are named once asGreetingPorts(the same object asgreetingSchema.ports) rather than passed to every instance. It also makes the order structural: a wire cannot be written before the ports it fills exist. p.text('Hello, ')is folded into the prepared markup. It costs nothing per instance.strong.textPort(GreetingPorts.name)is a place, and costs one call. A text port stands for an element's whole content, so it gets an element of its own rather than sitting beside static text.
Static is not a bucket, it is an argument
Anything passed to el() is known now and is baked into the markup:
import { createExoStatic } from '@exodra/core';
export const EmptyState = createExoStatic((b) => {
b.el('div', { class: 'empty', role: 'status' }, (div) => {
div.el('span', { class: 'empty__icon', 'aria-hidden': 'true' }, (icon) => {
icon.text('∅');
});
div.text('Nothing here yet');
});
});
createExoStatic is for a component with nothing to fill — an icon, a separator,
a conditional block's body, an empty state. It refuses a builder that declares
ports, because a component with ports and no wiring is an attribute stuck empty:
a silent wrong page rather than an error.
An attribute whose value varies is not an attribute here. It is a port.
The schema builder
| Call | Declares |
|---|---|
el(tag, attrs?, fn?) | a child element with its static attributes, and optionally a body |
text(value) | static text |
attrPort(Ports.x, name) | places an EXO_PORT_ATTR port on one attribute |
eventPort(Ports.x, name) | places an EXO_PORT_EVENT port on one listener |
textPort(Ports.x) | places an EXO_PORT_TEXT port on the whole text content of the current element |
childrenPort(Ports.x) | places an EXO_PORT_CHILDREN port: a variable-length sequence of children |
Each port is first declared in the component's port interface,
exoPorts({ x: EXO_PORT_ATTR, … }), and createExoSchema(Ports, build) places it.
A children port is a child: it is appended where the call appears, so a conditional block between a heading and a footer is the ordinary case, not an awkward one.
The wiring function
(connector, params) => state
paramsis the only thing this instance is told. A row ofc.listgets its element of the array the list was handed,wireExoNode(node, params)andc.one(port, component, params)pass whatever the caller hands them, andbackend.render(component, parent, params)passes its third argument.- It is what the instance was handed at build time and nothing more. When rows move, the reconciler moves nodes — it does not re-run wiring — so a component that needs a live position must be handed it by a transition, not capture it here.
What the connector offers:
| Call | Meaning |
|---|---|
c.attr(port, value) | write an attribute, once |
c.text(port, value) | write an element's whole text, once |
c.unsafeHtml(port, markup) | write raw markup into a children port |
c.on(port, handler, subject?) | a listener |
c.one(port, component, params?) | one nested instance |
c.list(port, component, rows) | a fixed run, one instance per element of rows, each handed its element as params |
c.createExoNode(component) | a child as a value, unwired and placed nowhere; wireExoNode(node, params) wires it |
c.appendChild(port, node) and the other port methods | place, move and remove a child by hand — see Children |
c.onTeardown(off) | hand the instance a disposer to run when it goes |
c.provide(token, value) / c.inject(token) | contexts |
Nothing in that table watches a source, and that is the design. A machine
writes "state → ports" in its wire, its handlers and its effects, and in a
transition — withExoTransitions(m, { show: (c) => … }), called through
toggleMachine.transitions.show — when that one place must also be fired or
overridden from outside the machine. Following data that lives outside
the instance is an effect that writes the ports once, then subscribes, and
returns the unsubscribe. Keeping a child list in step is a call to a
reconciler made by createExoChildrenReconciler from @exodra/list-reconcile. A door
would have made every page link subscription machinery it may never use, and
would have let the backend decide what counts as a source. As plain calls inside
the wire, the handlers and the effects, the application composes them — or does not, and pays
nothing.
The same wiring function runs on the server, on a client render and through hydration. Write it against the methods it actually uses and all three backends accept it with no cast.
State and transitions
State that belongs to one instance is machine state: the createInitialState
option of the base machine returns it once per instance, a handler changes it, and a transition writes it to
the ports.
import {
EXO_PORT_ATTR,
EXO_PORT_EVENT,
EXO_PORT_TEXT,
composeExoMachine,
createExoMachine,
createExoSchema,
exoPorts,
withExoHandlers,
withExoTransitions,
withExoWire,
} from '@exodra/core';
import { ExoDomBackend, withExoCompiler } from '@exodra/dom';
import type { TExoDomNode } from '@exodra/dom';
const backend = withExoCompiler(new ExoDomBackend());
const TogglePorts = exoPorts({ rootClass: EXO_PORT_ATTR, click: EXO_PORT_EVENT, text: EXO_PORT_TEXT });
const toggleSchema = createExoSchema(TogglePorts, (b) => {
b.el('div', null, (div) => {
div.attrPort(TogglePorts.rootClass, 'class');
div.el('button', { type: 'button' }, (btn) => {
btn.eventPort(TogglePorts.click, 'click');
btn.textPort(TogglePorts.text);
});
});
});
const toggleMachine = composeExoMachine(
createExoMachine(toggleSchema, {
createInitialState: (_c: TExoDomNode, _params: unknown) => ({ on: false }),
}),
(m) =>
withExoTransitions(m, {
show: (c) => {
c.attr(TogglePorts.rootClass, c.state.on ? 'toggle toggle--active' : 'toggle');
c.text(TogglePorts.text, c.state.on ? 'ON' : 'OFF');
},
}),
(m) =>
{
const { show } = m.transitions;
return withExoWire(m, (c) => {
show(c);
});
},
(m) =>
{
const { show } = m.transitions;
return withExoHandlers(m, (on) => {
on(TogglePorts.click, (c) => {
c.state.on = !c.state.on;
show(c);
});
});
}
);
backend.render(toggleMachine, document.body);
A derived value is computed in the transition — the label and the class above
are both read off one boolean at the moment they are written. show is taken off
toggleMachine.transitions after the machine is composed; the wire and the handler
only call it once an instance runs, by which time it exists.
:::caution The one rule that has no exception
A connector is reused: one of them serves every row of a list. A callback
that read the connector's fields would follow it onto the next row and update
the wrong element — a bug with no assertion failure and no wrong-looking line,
just a table where every row shows the last row's data. A transition is handed
the exonode it runs on, and an effect's subscriber closes over the c that effect
was started for, which is that instance's own. If you write a subscription by
hand anywhere else, capture the node, never the connector.
:::
Composition
Components nest through a children port. one puts a single instance in it.
It takes the port, the component and optional params — here there are none: the
child is not handed data, it goes and reads it.
import {
EXO_PORT_CHILDREN,
EXO_PORT_TEXT,
composeExoMachine,
createExoMachine,
createExoSchema,
exoPorts,
withExoEffects,
} from '@exodra/core';
import type { TExoDomNode } from '@exodra/dom';
function createStore<TValue>(value: TValue) {
const listeners = new Set<() => void>();
return {
getValue: () => value,
setValue(next: TValue) {
value = next;
for (const listener of Array.from(listeners)) listener();
},
onChange(listener: () => void): () => void {
listeners.add(listener);
return () => {
listeners.delete(listener);
};
},
};
}
type TUser = { readonly name: string; readonly role: string };
const user = createStore<TUser>({ name: 'Ada', role: 'author' });
const AvatarPorts = exoPorts({ initials: EXO_PORT_TEXT });
const avatarSchema = createExoSchema(AvatarPorts, (b) => {
b.el('span', { class: 'avatar' }, (span) => {
span.textPort(AvatarPorts.initials);
});
});
const avatarMachine = composeExoMachine(createExoMachine<TExoDomNode>(avatarSchema), (m) =>
withExoEffects(m, (effect) => {
effect((c) => {
const showInitial = () => {
c.text(AvatarPorts.initials, user.getValue().name.slice(0, 1).toUpperCase());
};
showInitial();
return user.onChange(showInitial);
});
})
);
const UserCardPorts = exoPorts({ slot: EXO_PORT_CHILDREN, name: EXO_PORT_TEXT, role: EXO_PORT_TEXT });
const userCardSchema = createExoSchema(UserCardPorts, (b) => {
b.el('div', { class: 'user' }, (div) => {
// The children port sits between two static siblings — and renders there.
div.el('div', { class: 'user__avatar' }, (holder) => {
holder.childrenPort(UserCardPorts.slot);
});
div.el('strong', null, (strong) => {
strong.textPort(UserCardPorts.name);
});
div.el('em', null, (em) => {
em.textPort(UserCardPorts.role);
});
});
});
const userCardMachine = composeExoMachine(
createExoMachine(userCardSchema, {
createInitialState: (c: TExoDomNode, _params: unknown) => {
c.one(UserCardPorts.slot, avatarMachine);
},
}),
(m) =>
withExoEffects(m, (effect) => {
effect((c) => {
const showUser = () => {
const { name, role } = user.getValue();
c.text(UserCardPorts.name, name);
c.text(UserCardPorts.role, role);
};
showUser();
return user.onChange(showUser);
});
})
);
The effect draws first and subscribes second, synchronously: hydration adopts the server's markup only while the instance is being armed, which is when effects start. What it returns is its stop, run when the instance leaves.
avatarMachine names the source it reads. That is the trade the no-props design makes
and it is worth stating plainly: a component is not a function of arguments
you can call with anything — it is wired to where its data lives. Reuse comes
from the data layer, not from the parameter list: the same component over a
different user is a different source, and the same component over a thousand
rows is handed each row's item as its params, which is what a reconciled list wires
each row with. See
Rendering.
backend.render is for the top of a page, where there is no row to be about — so the root
component is the one that goes and gets the data, which is what every
component here does.
Note what is not here: no props object, no bucket, no children key, and
no diffing of any of them.
"Slots"
A slot is a children port. A component with two of them takes two nested instances; which component goes in each is decided by the wiring function that fills them, so a layout is written once and reused by naming different components at the call site.
Lists
createExoChildrenReconciler(rowMachine) from @exodra/list-reconcile makes, once at
module level, a function that reconciles a children port against an array, by object
identity: reconcile(c, port, items) gives each new item a row of rowMachine wired with
the item as params, keeps the row of every item that stays, and destroys the rest. It
remembers what it showed per node and port, so the machine keeps no shown order. A row that
survives is the same element it was. No keys are involved on this path — and where identity
is not available, the { key } option supplies one. See
Keys, when identity is not available.
import {
EXO_PORT_ATTR,
EXO_PORT_CHILDREN,
EXO_PORT_TEXT,
composeExoMachine,
createExoMachine,
createExoSchema,
exoPorts,
withExoEffects,
withExoWire,
} from '@exodra/core';
import { ExoDomBackend, withExoCompiler } from '@exodra/dom';
import type { TExoDomNode } from '@exodra/dom';
import { createExoChildrenReconciler } from '@exodra/list-reconcile';
const backend = withExoCompiler(new ExoDomBackend());
function createStore<TValue>(value: TValue) {
const listeners = new Set<() => void>();
return {
getValue: () => value,
setValue(next: TValue) {
value = next;
for (const listener of Array.from(listeners)) listener();
},
onChange(listener: () => void): () => void {
listeners.add(listener);
return () => {
listeners.delete(listener);
};
},
};
}
type TItem = { readonly id: string; readonly label: string };
const RowPorts = exoPorts({ id: EXO_PORT_ATTR, label: EXO_PORT_TEXT });
const rowSchema = createExoSchema(RowPorts, (b) => {
b.el('li', null, (li) => {
li.attrPort(RowPorts.id, 'data-id');
li.textPort(RowPorts.label);
});
});
const rowMachine = composeExoMachine(
createExoMachine(rowSchema, {
createInitialState: (_c: TExoDomNode, item: TItem) => item,
}),
(m) =>
withExoWire(m, (c) => {
const item = c.state;
c.attr(RowPorts.id, item.id);
c.text(RowPorts.label, item.label);
})
);
const reconcileItems = createExoChildrenReconciler<TItem>(rowMachine);
const items = createStore<readonly TItem[]>([
{ id: 'a', label: 'First' },
{ id: 'b', label: 'Second' },
]);
const ListPorts = exoPorts({ rows: EXO_PORT_CHILDREN });
const listSchema = createExoSchema(ListPorts, (b) => {
b.el('ul', { class: 'list' }, (ul) => {
ul.childrenPort(ListPorts.rows);
});
});
const listMachine = composeExoMachine(createExoMachine<TExoDomNode>(listSchema), (m) =>
withExoEffects(m, (effect) => {
effect((c) => {
const showRows = () => reconcileItems(c, ListPorts.rows, items.getValue());
showRows();
return items.onChange(showRows);
});
})
);
backend.render(listMachine, document.body);
items.setValue([...items.getValue(), { id: 'c', label: 'Third' }]);
The list machine keeps nothing in its state: the reconciler remembers what it showed. Only
c.one and c.list are placed once and refused in a wire that runs again; a reconciler and the
port methods may be called from any wire, transition or effect — see Children.
When the contents cannot change, use c.list(port, component, rows) instead: a
fixed list pays for no row records, no diff and no teardown.
For a filtered view, compute the subset before the call and hand that as the items: rows are matched by the item objects, so a row the filter keeps is the same element it was. See the Lists guide.
Side effects and cleanup
An effect owns what it starts: the function it returns is its stop, run when the
instance leaves, and backend.render hands back a disposer that ends everything
at once. Anything started outside an effect is registered with c.onTeardown,
against the child the exonode is currently wiring:
import {
EXO_PORT_TEXT,
composeExoMachine,
createExoMachine,
createExoSchema,
exoPorts,
withExoEffects,
withExoWire,
} from '@exodra/core';
import type { TExoMachineNodeOf } from '@exodra/core';
import { ExoDomBackend, withExoCompiler } from '@exodra/dom';
import type { TExoDomNode } from '@exodra/dom';
const backend = withExoCompiler(new ExoDomBackend());
const TimerPorts = exoPorts({ text: EXO_PORT_TEXT });
const timerSchema = createExoSchema(TimerPorts, (b) => {
b.el('div', { class: 'timer' }, (div) => {
div.textPort(TimerPorts.text);
});
});
const timerBase = createExoMachine(timerSchema, {
createInitialState: (_c: TExoDomNode, _params: unknown) => ({ seconds: 0 }),
});
function show(c: TExoMachineNodeOf<typeof timerBase>): void {
c.text(TimerPorts.text, `Time: ${c.state.seconds}s`);
}
const timerMachine = composeExoMachine(
timerBase,
(m) =>
withExoWire(m, (c) => {
show(c);
}),
(m) =>
withExoEffects(m, (effect) => {
effect((c) => {
const id = setInterval(() => {
c.state.seconds++;
show(c);
}, 1000);
return () => clearInterval(id);
});
})
);
const dispose = backend.render(timerMachine, document.body);
// Stops the interval along with every other effect this render started.
dispose();
A subscription with nothing to end it is refused, rather than quietly outliving the page that made it.
onTeardown is on every backend, including the server's — what differs is
when it runs. In the browser it runs when the instance leaves. On the server
it runs at the end of the render, in registration order, after the markup has
already been taken: a disposer that writes to a port cannot change the bytes
that were printed
(packages/string/src/node/tests/render-exo-instance.test.ts:105-129). That is
what makes a disposer safe to register on three backends — whatever it stops is
started and ended in both places, and only the browser keeps it running between
the two.
Restarting an effect by name
An effect reads what it needs from c.state, so moving it to other data is two steps: write the
new value into the state, then restart the effect. Declared as a dictionary, each effect is reached
by its name on m.effects; the restart runs its old stop first and then starts it again.
import {
EXO_PORT_EVENT,
EXO_PORT_TEXT,
composeExoMachine,
createExoMachine,
createExoSchema,
exoPorts,
withExoEffects,
withExoHandlers,
withExoTransitions,
} from '@exodra/core';
import type { TExoMachineNodeOf } from '@exodra/core';
import { ExoDomBackend, withExoCompiler } from '@exodra/dom';
import type { TExoDomNode } from '@exodra/dom';
const backend = withExoCompiler(new ExoDomBackend());
const PagerPorts = exoPorts({ page: EXO_PORT_TEXT, next: EXO_PORT_EVENT });
const pagerSchema = createExoSchema(PagerPorts, (b) => {
b.el('div', { class: 'pager' }, (div) => {
div.el('p', null, (p) => p.textPort(PagerPorts.page));
div.el('button', null, (button) => {
button.eventPort(PagerPorts.next, 'click');
button.text('next');
});
});
});
const pagerBase = createExoMachine(pagerSchema, {
createInitialState: (_c: TExoDomNode, _params: unknown) => ({ page: 1 }),
});
function show(c: TExoMachineNodeOf<typeof pagerBase>, seconds: number): void {
c.text(PagerPorts.page, `Page ${c.state.page}, open for ${seconds}s`);
}
const pagerMachine = composeExoMachine(
pagerBase,
(m) =>
withExoEffects(m, {
showPage: (c) => {
let seconds = 0;
show(c, seconds);
const id = setInterval(() => show(c, ++seconds), 1000);
return () => clearInterval(id);
},
}),
(m) => {
const { showPage } = m.effects;
return withExoTransitions(m, {
nextPage: (c) => {
c.state.page++;
c.restartEffect(showPage);
},
});
},
(m) => {
const { nextPage } = m.transitions;
return withExoHandlers(m, (on) => on(PagerPorts.next, (c) => nextPage(c)));
}
);
backend.render(pagerMachine, document.body);
The callback form, withExoEffects(m, (effect) => { effect(start) }), still hands back the same
handle, and m.effects[i] still reaches it by position: the names are set on that same array.
Restarting an effect when its params change
withExoParamsEffects declares effects that follow the params of the wire. Each one names a key
read from the params and a start that receives the params themselves. When wireExoNode runs the
wire again, every effect whose key changed is restarted; the others are left running.
import {
EXO_PORT_TEXT,
composeExoMachine,
createExoMachine,
createExoSchema,
exoPorts,
withExoParamsEffects,
withExoWire,
wireExoNode,
} from '@exodra/core';
import { ExoDomBackend, withExoCompiler } from '@exodra/dom';
import type { TExoDomNode } from '@exodra/dom';
type TFeed = { onChange(listener: () => void): () => void; read(id: string): string };
declare const feed: TFeed;
const backend = withExoCompiler(new ExoDomBackend());
const TickerPorts = exoPorts({ title: EXO_PORT_TEXT, price: EXO_PORT_TEXT });
const tickerSchema = createExoSchema(TickerPorts, (b) => {
b.el('div', { class: 'ticker' }, (div) => {
div.el('b', null, (title) => title.textPort(TickerPorts.title));
div.el('span', null, (price) => price.textPort(TickerPorts.price));
});
});
type TTickerParams = { symbol: string; title: string };
const tickerMachine = composeExoMachine(
createExoMachine(tickerSchema, {
createInitialState: (_c: TExoDomNode, _params: TTickerParams) => ({}),
}),
(m) =>
withExoWire(m, (c, params) => {
c.text(TickerPorts.title, params.title);
}),
(m) =>
withExoParamsEffects(m, {
followPrice: {
key: (params) => params.symbol,
start: (c, params) => {
const show = () => c.text(TickerPorts.price, feed.read(params.symbol));
show();
return feed.onChange(show);
},
},
})
);
const ticker = backend.createExoNode(tickerMachine);
wireExoNode(ticker, { symbol: 'ACME', title: 'Acme' });
backend.mountRoot(ticker, document.body);
wireExoNode(ticker, { symbol: 'ACME', title: 'Acme Corp' });
wireExoNode(ticker, { symbol: 'INIT', title: 'Initech' });
The second call rewrites the title only; the third one also stops the ACME subscription and
starts the INIT one. A restart from anywhere else — c.restartEffect(m.effects.followPrice)
from a transition, or connectExoNode after disconnectExoNode — hands start the params of
the last wire. Those params are kept in the node's serviceState, the field swapExoParams uses,
so the exonode gains no field and a machine that does not use the decorator pays nothing.
Several steps of one kind: what happens
Every decorator returns a new machine, so the same decorator can appear in more than one step. This is what each combination does, and what is refused.
Effects
| written | result |
|---|---|
two withExoEffects steps with dictionaries | one effects array; the names of both steps are on it, and at follows declaration order across the steps |
| a callback step and a dictionary step, in either order | one array; the dictionary's effects also have names, the callback's are reached by position or by the handle effect(...) returned |
| a name an earlier step used | refused, EXO0112 |
a name the array itself has (push, map, length, at, keys …) or a name made of digits | refused, EXO0112: it would shadow an array member or write an element |
withExoEffects and withExoParamsEffects names | one namespace, the same array: a clash between them is refused the same way |
| two machines composed from one base | each has its own copy of the array; a handle belongs to the machine that declared it and must be restarted on that machine's nodes only, because it addresses a slot by position |
Transitions
| written | result |
|---|---|
two withExoTransitions steps | one transitions dictionary; a step reads the earlier steps' transitions from m.transitions |
overrides({ … }) with names from several steps | one table; each name is checked against its own transition's signature |
| a name an earlier step used, or a name made of digits | refused, EXO0113: a repeated name would leave two wrappers and an override would reach only the first |
a name the machine does not have, in overrides | refused, EXO0102 |
Wire and params effects
| written | result |
|---|---|
withExoParamsEffects after withExoWire, or before it | the same machine: the params effects run around the wire either way, after it has written its ports |
two withExoWire steps, with or without params effects between them | refused, EXO0101 |
two withExoParamsEffects steps | both compare against the params of the previous wire |
swapExoParams(c, params) inside the wire | still returns the previous params |
| the instance was built with no params | the first wireExoNode with params compares against undefined and restarts what changed |
a key that builds a new object or array each time | compared with Object.is, so it changes on every wire and the effect restarts every time: return a primitive or a stable reference |
restartEffect on a node that disconnectExoNode switched off | starts the effect, although the node is disconnected; connectExoNode later starts it again over the live one. Known defect, not fixed yet |
Contexts
A context token is an identity, not a string, so two packages cannot collide on
a name. provide and inject are methods on the connector — there is nothing
to import to use them, because a context exists only while a wiring is running.
import {
EXO_PORT_ATTR,
EXO_PORT_CHILDREN,
composeExoMachine,
createExoMachine,
createExoSchema,
exoPorts,
withExoWire,
} from '@exodra/core';
import type { TExoChildrenWiring, TExoMachineNode } from '@exodra/core';
import { exoContextToken } from '@exodra/context';
import { ExoDomBackend, withExoCompiler } from '@exodra/dom';
const backend = withExoCompiler(new ExoDomBackend());
const THEME = exoContextToken<string>('theme');
const LabelPorts = exoPorts({ cls: EXO_PORT_ATTR });
const labelSchema = createExoSchema(LabelPorts, (b) => {
b.el('span', null, (span) => {
span.attrPort(LabelPorts.cls, 'class');
});
});
const labelMachine = composeExoMachine(createExoMachine<TExoMachineNode>(labelSchema), (m) =>
withExoWire(m, (c) => {
// `undefined` when nobody provided it — not a throw.
c.attr(LabelPorts.cls, 'label label--' + (c.inject(THEME) ?? 'light'));
})
);
const ShellPorts = exoPorts({ slot: EXO_PORT_CHILDREN });
const shellSchema = createExoSchema(ShellPorts, (b) => {
b.el('div', { class: 'shell' }, (div) => {
div.childrenPort(ShellPorts.slot);
});
});
const shellMachine = createExoMachine(shellSchema, {
createInitialState: (c: TExoChildrenWiring & TExoMachineNode, _params: unknown) => {
c.provide(THEME, 'dark');
c.one(ShellPorts.slot, labelMachine);
},
});
backend.render(shellMachine, document.body);
The chain provide returns travels downwards as an ordinary value: it goes on
the exonode, and every one, list and createExoNode wired after it
inherits it. A reconciled list captures the chain when it is wired and holds it for its whole
life, so a row added an hour later — from inside a subscriber, with no render on
the stack — resolves what the page provided without touching the DOM at all.
A context does not travel through the document. A second, independent
render() into an element that some other render provided into starts from
nothing: it reads undefined, not the surrounding page's value. There used to be
a second channel — provide marked the instance's root element and each entry
point climbed parentNode from the parent it was handed — and it was removed. A
host that wants a separately-mounted widget to see a value hands it over: by
putting it where the widget's root component reads it, or by rendering the widget
inside the same render that provided.
The reasoning: it was a whole per-provider storage scheme on the element, paid by every page, for a case where the host already owns the mount call and can pass the value at it. What the DOM bought over passing it was the absence of an interface; what it cost was a channel that depended on mount order and document position.
inject walks a frame chain, never the DOM: 1.67 ns at one link, 7.67 ns at
eight (context-cost axis, b4 label).
Providing a token something above already provided shadows it for that subtree and nothing else.
:::caution Contexts are not reactive by themselves
What you provide is what a consumer holds forever. Put a source in the context
and follow it with an effect: read c.inject(THEME), write the ports, and
return theme.onChange(() => show(c)). A context that tried to be
reactive itself would be a second, weaker subscription mechanism on top of the
one that already works.
:::
Writing the schema in JSX
Exodra JSX is another way to write the schema half:
exoJsx<TPorts>(($) => <markup/>) declares markup and named ports —
data-id={$.id}, {$.title}, onClick={$.toggle}, <$.rows /> — and
@exodra/babel-plugin-schema compiles it into the module-level schema this page
builds by hand. The machine is the same machine, written as on this page and
filling the ports through XPorts = xSchema.ports. Nothing on this page depends on JSX — a
hand-written schema needs no build step at all.
Performance notes
- Declare in
el(), not in a port. A port costs a slot and a call per instance; a static attribute costs nothing. - A bare
c.attrin the wire when it cannot change, an effect when it can. The bare write is two array loads and a call, with nothing retained. c.listfor a fixed list, acreateExoChildrenReconcilerreconciler for a live one. A list whose contents cannot change should not pay for the possibility that they might.- Use a shared handler for a repeated handler. A module-level function taking
(event, subject)is one function object for the whole template; a closure is one per row — and the subject is what the delegated event pack needs a fill to carry. - Let effects own their subscriptions. An effect returns its stop; registering teardown by hand is only for what you start outside one.