Signals: the ypy-signals extension
Some page state has no business on the server: whether a box is ticked, what is typed in a field, whether a panel is
open. ypy-signals keeps that state in the page as named values called signals. Inputs bind to them and attributes read
them. The server can read them from every request and change them with a JSON patch. The extension needs no build step
and no eval.
<script src="ypy.min.js"></script>
<script src="ext/ypy-signals.min.js"></script> <!-- ypy.max already includes it -->
<form ypy-signals="name:'', agree:false" ypy-post="/signup" ypy-target="#result">
<input ypy-bind="name" placeholder="Name">
<label><input type="checkbox" ypy-bind="agree"> I agree</label>
<p ypy-show="$name.length > 0">Hello, <b ypy-text="$name"></b></p>
<button ypy-attr:disabled="!$agree || $name == ''">Send</button>
<span ypy-show="$_dirty">Unsaved</span>
</form>Expressions are parsed by a small parser into closures and never compiled into code. They work with callbacks:"none"
(the default), a strict CSP and Trusted Types.
Scopes and names
An element with ypy-signals is a scope. Its signals are visible to the element and its descendants, scopes nest, and a
name is looked up in the nearest scope that has it. Put signals shared by the whole page on <body>.
-
$namereads a signal,$user.address.cityand$list[0]read inside it. A path that does not exist isundefined, never an error. Writes copy along the path, so a change is always a new object. - A name that starts with
_is local: it is never sent to the server, at any depth. - A signal nobody declared is created, when something writes it, in the outermost scope that reaches the writer.
constructor,prototypeand__proto__are refused everywhere.- Every scope has a read-only local signal
$_dirty. -
In an attribute name a hyphen stands for a capital:
ypy-computed:total-priceistotalPrice. In a value, write the name as it is.
Attributes
All of them also exist with the data- prefix. They are read when the element is processed, after a swap included.
| Attribute | Value | What it does |
|---|---|---|
ypy-signals |
count:0, name:'x' (braces optional, JSON works) |
Declares signals in a scope. An existing signal keeps its value when the markup is processed again. |
ypy-signals.server |
same | Server-owned signals, read-only for the client. |
ypy-signals.local, ypy-signals.session |
same | Persisted in localStorage or sessionStorage. The element needs an id. |
ypy-computed:name |
expression | A derived, read-only signal. Not sent to the server. |
ypy-bind or ypy-bind:name |
path (user.name) |
Two-way binding with a form control. |
ypy-text |
expression | Sets textContent, never markup. |
ypy-show |
expression | Hides the element while the value is false. |
ypy-class:name or ypy-class |
expression | One class (ypy-class:active="$on") or several (ypy-class="{red: $bad}"). |
ypy-attr:name or ypy-attr |
expression | Sets an attribute. false, null and undefined remove it. Refused: on*, srcdoc, ypy-* and script URLs in href, src, action and similar. |
ypy-on:event |
statements | An event handler. |
ypy-signals-send="false" |
On the element or an ancestor: its requests do not carry the signals. |
Effects run once when wired and again, in a batch, when a signal they read changes. They track exactly what they read, and effects that keep waking each other stop after 100 rounds with an error in the console.
Expressions
One small language for every attribute. Handlers also take statements separated by ;.
- Literals: numbers, strings (
"..."or'...'),true,false,null,undefined, lists and objects. -
Operators:
! - +,* / %,+ -,< > <= >=,== != === !==,&&,||,??, the ternarya ? b : c.&&,||and??short-circuit. - Assignment (
=,+=,-=,*=,/=,%=,??=) and++/--work in handlers only. -
Reading is lenient. Only own properties are read, so
$text.lengthand$list[1]work, and$o.toStringand$list.mapareundefined. -
The only names are signals (
$name) and functions given toypy.signals.register, for exampleypy.signals.register('upper', s => String(s).toUpperCase())makesupper($name)available. There is nowindow,document,this, method call, arrow function, template literal ornew. -
In handlers
$eventis a plain object withtype,key,code,detail,value,checkedand the modifier keys. It never holds an element or the window.
An expression that fails to parse fires ypy:signals:error and its attribute does nothing. The rest of the page keeps
working.
ypy-bind and its cadence
ypy-bind="name" keeps a form control and a signal equal.
| Control | Signal |
|---|---|
text, search, email, textarea, other input |
text, or a number if the signal was a number |
checkbox |
boolean |
radio |
the value of the checked radio (give the group the same ypy-bind) |
<select>, <select multiple> |
the selected value, or an array of values |
contenteditable |
the text content |
Without a modifier the field writes the signal on change, so typing does not run effects on every key.
| Modifier | The field writes the signal |
|---|---|
.live |
on every input |
.blur |
on blur only |
.debounce.300ms |
after a pause of 300 ms (.debounce alone means 300 ms) |
.throttle.300ms |
at most once per 300 ms, with the latest value |
A value typed and not yet written is written before a request starts, so the server never gets a stale field.
ypy-on
ypy-on:click="$count++; $open = !$open" runs statements when the event fires. ypy-on::before:request is the form for
ypy: events. Inside a scope (an element or an ancestor with one of the ypy-signals attributes) ypy-on belongs to
this extension and takes this language, so no JavaScript is compiled. Outside a scope the core's ypy-on is untouched.
Modifiers: .prevent, .stop, .once, .window (listen on window), .debounce.300ms and .throttle.300ms. The
listener runs in the capture phase on the element itself, so on an element that also starts a request the handler runs
first and the request sees the new values.
Signals in requests
A request whose element has signals in reach carries them as one JSON object in the parameter ypy-signals:
| Request | Where |
|---|---|
GET, DELETE |
query parameter ypy-signals=<url-encoded JSON> |
| other verbs | form field ypy-signals in the body, urlencoded or multipart |
The object holds the signals of every scope around the element (the inner scope wins on a clash), server-owned ones
included. Computed signals and any key starting with _ are left out. Signals go only to the same origin.
A GET puts signals in the URL, so they reach logs, proxies and, with ypy-push-url, the history entry. Keep secrets out
of signals, and use a POST or ypy-signals-send="false" for requests that must not expose them.
Updating from the server
A response with Content-Type: application/json is a JSON Merge Patch (RFC 7396)
applied to the signals around the request's element. It is not swapped into the page, whatever the status, so a 422 with
{"emailError":"taken"} works. Any other type is handled by the core.
{"count": 5, "user": {"name": "Bo", "age": null}, "tags": ["a"]}An object member merges recursively, null removes it, and an array or scalar replaces the value. A key goes to the
nearest scope that has it, and a new key to the outermost scope that reaches the element. Computed signals ignore a
patch. ypy:signals:patch fires first and can be cancelled. The stream event ypy-patch-signals uses the
same patch, and ypy.signals.patch(object, element, onlyIfMissing) applies one from code.
Server-owned signals
ypy-signals.server="plan:'free', planSig:'3fa9c1'" declares signals the client cannot write. An expression, binding or
handler that tries fires ypy:signals:readonly and the field shows the signal again. They change only when the server
patches them or renders the scope's markup again.
Read-only is a convenience of the UI and gives no security, because whoever controls the browser can send any value. The
protection is on the server: sign the values it owns, for example an HMAC of plan bound to the session, send the
signature in a server-owned signal, and verify it when it comes back.
Unsaved state
A scope is dirty while a client-owned signal differs from what was last saved. The saved value is the declared one, and it
moves when a 2xx response to a non-GET request from inside the scope arrives, or when the server patches the key. While
dirty, the scope gets the class ypy-dirty (rename it with ypy.config.classes.dirty), dirty in data-ypy-state, and
$_dirty is true.
Persistence
ypy-signals.local="draft:''" stores the signals in localStorage under ypy-signals:<id>, and ypy-signals.session
uses sessionStorage. The element needs an id. The stored value replaces the declared default only for keys the
markup declares. Server-owned signals are never persisted.
Swaps and morphs
The state of a scope lives with its element. A morph that keeps the element keeps the signals, and the extension runs the
effects of the swapped tree again, so signals win over what the markup said. A swap that replaces the scope element
creates a new scope from the declared values, so give it an id and persist it, or keep the scope above the swap target.
When an element leaves the page its effects, listeners and pending writes are dropped. ypy-ignore keeps the signal
attributes of a subtree inert.
Security
-
No text becomes code: no
eval, nonew Function. The language has no identifiers other than signals, literals and registered functions. - Reads use own properties only, and a write never mutates a foreign object.
ypy-textwrites text, andypy-attrrefuses event handlers,srcdoc,ypy-*and script URLs.- An expression is at most 1000 characters and 32 levels deep.
-
An attacker who can write markup can bind and display signals and call registered functions, but cannot run code or reach the network from an expression. Register only functions that are safe to call from any element.
JavaScript API and events
| Member | What it does |
|---|---|
ypy.signals.register(name, fn) |
Makes fn callable from expressions as name(...). |
ypy.signals.get(path, element) |
The value at "user.name", seen from element. |
ypy.signals.patch(object, element, onlyIfMissing) |
Applies a merge patch. |
ypy.signals.stats() |
{nodes, pending}: live nodes and uncommitted bindings. |
| Event | When |
|---|---|
ypy:signals:patch |
before a patch is applied; cancelable |
ypy:signals:readonly |
a write to a read-only signal was refused |
ypy:signals:error |
an expression did not parse, or a handler, effect or patch failed |
Limits
The extension is 6,009 bytes min+gzip, which leaves 135 of its 6,144-byte budget. Dependencies are tracked per top-level
signal, so an effect that reads $user.name runs when anything in user changes. ypy-on inside a scope cannot run
JavaScript, so put such an element outside the scope or register a function. $event.target is not available by design.
Checkbox groups into one array are not provided, so use one boolean per checkbox or select multiple.