@fuaran-ui/ops
Canonical-JSON codec (encoder + structural decoder) and tree-op apply engine for
the Fuaran UI wire format — a conformant TypeScript host of the
language-neutral contract specified in
fuaran-dotnet/docs/WIRE_FORMAT.md, sibling to the
F# host. Built on the typed shapes from
@fuaran-ui/schema (a peer dependency).
npm install @fuaran-ui/ops @fuaran-ui/schema
What it is
The correctness layer of the TypeScript reference implementation. @fuaran-ui/schema
gives you the typed tree; this package makes a TS-authored tree wire-conformant —
it can be serialised, persisted, replayed, and exchanged with the F# tier
byte-for-byte. Verified end-to-end against the workspace
wire-format-fixtures/ corpus: every valid fixture
round-trips byte-identically to the F# encoder, and every reject fixture surfaces
the same DecodeErrorCode at the same JSON path.
API
import { encodeNode, decodeNode, encodeOp, decodeOp, apply } from '@fuaran-ui/ops';
import type { TreeOp, DecodeError, ApplyError } from '@fuaran-ui/ops';
// Encode (typed tree → canonical JSON string)
const json: string = encodeNode(node);
// Decode (canonical JSON string → storage-shape Node<unknown> | DecodeError)
const decoded = decodeNode(json); // Result<Node<unknown>, DecodeError>
if (decoded.ok) {
/* decoded.value : Node<unknown> */
}
// TreeOp codec
const opJson = encodeOp(op);
const op = decodeOp(opJson); // Result<TreeOp<unknown>, DecodeError>
// Apply a tree-op (→ new tree + telemetry | ApplyError)
const result = apply(tree, op); // ApplyResult<TMsg>
if (result.ok) {
/* result.value.newTree, result.value.emittedTelemetry */
}
Three modules
| Module | Role |
|---|---|
encode | Symmetric port of the F# CanonicalJson encoder. Deterministic, byte-stable output. |
decode | Port of the F# JsonDecode decoder. Structural, Result-returning, six error codes. |
apply | Port of the F# apply engine. Atomic (Batch), revert-on-error, emits telemetry. |
DecodeError codes (WIRE_FORMAT.md §6)
INVALID_JSON, MISSING_FIELD, WRONG_TYPE, UNKNOWN_DU_CASE, WRONG_NODE_KIND,
EMPTY_NODE_ID — byte-identical to the F# decoder's codes, surfaced at a $-rooted
dotted path.
Placement helpers
placeOp / moveOp / nudgeOp / canPlace (plus the clone verbs
duplicateOp / pasteOp and their …With variants taking an injectable
fresh-id strategy) derive the ops that put a node at a stated position —
first, last, before or after a named sibling — from the positionless op
vocabulary.
import { placeOp, moveOp, nudgeOp, canPlace, apply } from '@fuaran-ui/ops';
// Insert `child` immediately before sibling "b" under parent "left".
const r = placeOp(tree, child, {
parentId: 'left',
placement: { kind: 'Before', anchor: 'b' },
}); // Result<TreeOp, PlaceError>
if (r.ok) apply(tree, r.value);
These helpers emit only existing TreeOp shapes — a bare InsertChild /
MoveNode when appending already yields the wanted order, otherwise
Batch [InsertChild|MoveNode, ReorderChildren], and ReorderChildren alone
for a nudge. There is no new op case and no wire-format change; anything
they emit encodes, decodes, and applies exactly as if a consumer had assembled
it by hand. Pre-checks mirror the apply engine's own rejections (absent or
childless parent, move-into-self, move-into-descendant, duplicate id), so a
helper refusal and an apply refusal always agree; an anchor that is not among
the destination's children is refused (UnknownAnchor) rather than silently
appended. The clone verbs remap colliding ids across the whole traversal
surface before insert, so a duplicate or paste never trips the tree-wide
duplicate-id check.
Storage-shape erasure
Decode is storage-shape erased: it always yields Node<unknown> / TreeOp<unknown>,
because the wire carries no typed-'Msg information (every 'Msg payload and every
closure encodes as the "<closure>" sentinel). Opaque Binding.Static payloads the
encoder couldn't decompose decode to the literal string "<opaque>". Both placeholders
re-encode to the same sentinel, so the round-trip stays byte-stable; typed re-attachment
of the erased payloads is the host's responsibility.
Conformance is the stability contract
Per the wire-format forward-coupling rule
(WIRE_FORMAT.md §11), adding a NodeKind / Spec
/ TreeOp / Binding / Action case updates the F# encoder + decoder + the corpus
and this TS codec + @fuaran-ui/schema in the same commit. Byte-equality against the
corpus — not just API non-breakage — is the contract.
Licence
Apache-2.0. See STABILITY.md for the per-surface stability
declaration.