README- UCtx
- UObj
- URequestOpts
- UValue
marianoguerra/tutuca/core does not have a README file
Ctx
pub(open) trait Ctx {
fn path(Self) -> DispatchPath = _
fn target_path(Self) -> DispatchPath = _
fn name(Self) -> String? = _
fn send(Self, name : String, args : Array[Value]) -> Unit = _
fn bubble(Self, name : String, args : Array[Value]) -> Unit = _
fn send_at_path(Self, path : DispatchPath, name : String, args : Array[Value]) -> Unit = _
fn bubble_at_path(Self, path : DispatchPath, name : String, args : Array[Value]) -> Unit = _
fn request(Self, name : String, args : Array[Value], opts : RequestOpts) -> Unit = _
fn stop_propagation(Self) -> Unit = _
fn at(Self) -> PathChanges = _
fn walk_path(Self, callback : (Int, Value) -> Bool) -> Unit = _
}What a handler can do besides transforming its leaf (JS EventContext).
Defined here so Handler can carry it without depending on the transactor;
every method defaults to a no-op so tests and Path::update can run
handlers without a dispatcher. The transactor implements the real thing.
Fields
pub(open) trait Fields {
fn schema() -> SchemaInfo
fn encode(Self) -> Map[String, Value]
fn decode(Map[String, Value]) -> Self?
}What a typed state struct states about itself: its declared schema and its
conversion to and from the fields map the render and path layers read.
A generic BOUND, not a trait object — schema and decode are facts about
the TYPE, and Value::Obj already carries the object-safe half of the
protocol (Obj). Nothing ever needs a &Fields.
Three methods, all of them things only the author (or the generator reading
the author's WIT) knows. There is no fourth: every dynamic operation OVER
the result — typed reads, defaults, sizes, item lookup, method calls, field
enumeration — is a free function in this package, written once rather than
implemented per type.
Obj
pub(open) trait Obj {
fn component_id(Self) -> Int? = _
fn obj_field(Self, name : String) -> Value? = _
fn obj_with_field(Self, name : String, v : Value) -> Value? = _
fn obj_item(Self, key : PathKey) -> Value? = _
fn obj_with_item(Self, key : PathKey, v : Value) -> Value? = _
fn obj_seq_entries(Self) -> Array[(PathKey, Value)]? = _
fn obj_callable(Self, name : String, ns : HandlerNamespace) -> Value? = _
fn obj_handler(Self, bucket : HandlerBucket, name : String) -> Handler? = _
fn obj_schema(Self) -> SchemaInfo? = _
fn obj_size(Self) -> Int? = _
fn obj_eq(Self, other : &Obj) -> Bool = _
fn obj_debug(Self) -> String = _
}Component-instance protocol (the port of JS's runtime Records tagged with
a hidden component symbol). ONE trait serves both hybrid representations:
the Value-backed Instance (component package) and user-defined typed
structs. Instances live INSIDE Value so they flow through every
Value-typed seam (binds, handler args, dynamic lookups, iterated seqs).
Fns returned by obj_field / obj_callable and the Handler returned
by obj_handler are SELF-PRE-BOUND (they close over the concrete Self —
the no-downcast analogue of JS late this) and ignore args element 0.
Every method defaults to an empty/None answer.
Stack
pub(open) trait Stack {
fn lookup_name(Self, String) -> Value = _
fn lookup_bind(Self, String) -> Value = _
fn lookup_dynamic(Self, String) -> Value = _
fn lookup_field_raw(Self, String) -> Value = _
fn lookup_method(Self, String) -> Value = _
fn get_handler_for(Self, String, HandlerNamespace) -> Value = _
}Evaluation environment (JS stack). Every method defaults to Null so
implementations (and test mocks) provide only the lookups they use.
lookup_method returns the RESULT of the no-arg call — the stack invokes.
get_handler_for returns Null when no handler is registered.
DispatchPath
A path that still knows which component contributed each hop. Bubbling
pops one hop per component; converting to a transaction Path teleports
every Dyn marker so mutations land on the data's real location.
DispatchPath::concat
DispatchPath::to_transaction_path
DispatchStep
One hop of a dispatch path — the component-boundary projection of an event
path. Plain wraps an addressing step with its origin (the id of the
component that contributed it — teleport provenance); Dyn marks a dynamic
variable (*dyn) used as a render target: the rendered data lives at the
PRODUCER component (where the dynamic was defined), not at the consumer
that wrote <x render="*dyn">, so interior lists the component ids
crossed between producer and consumer, and steps is the producer's own
path to the data. key is set when the dynamic is ITERATED (the item lives
at the producer's sequence field under that key) — the one thing that used
to be a whole second variant, DynEach, which differed in nothing else and
so was matched alongside Dyn everywhere except the one line that reads
the key.
FieldInfo
One declared field of a component's state.
Two parts, where there were six. The WIT spelling, the runtime kind, a
collection's element type, a slot's component and a closed set's members are
all FUNCTIONS of the type (ty_info.mbt), so they are asked rather than
stored — which is what stops them from contradicting each other, and what
lets a reader descend into list<card> instead of receiving the string
"card" and having nowhere to take it.
FieldInfo::kind
The runtime kind this field carries — a projection of its type, never a
second statement about it.
FieldKind
What a field carries at runtime. DECLARED, never inferred: reading the kind
off a seed value is what used to make FInt vs FFloat depend on whether
a double happened to be integral.
FComp fields hold a child component instance created through the
registration scope; FSet/FOMap are the Map-backed set / ordered-map
refinements.
Handler
A leaf-update handler, resolved ON the leaf so self is pre-bound (the JS
handler.apply(instance, args) binds this at call time; binding at
resolution time is equivalent — same instance either way). Receives its
args and the dispatch Ctx (JS appends ctx as the last handler argument).
Returns the new leaf, or None for "no change" (the port of the JS
newLeaf !== curLeaf identity check — answering None lets the traversal
skip the spine rebuild without comparing anything).
HandlerBucket
Dispatch buckets a handler can live in (semantics.md §6). Alter is
render-time only and never dispatched, so it is not a bucket here.
HandlerNamespace
Handler namespaces are a fixed enumeration (JS passes "input"/"alter" strings)
HandlerParse
Handler reference plus parsed args for @on.
Issue
A parse issue, collected on the ParseCtx (JS px.onParseIssue callback)
IssueKind
JS onParseIssue kind — only "bad-value" occurs in value.js; other kinds
(x-op, x-attr, …) join this enum when their modules are ported.
IssueRole
What was malformed (JS info.role)
Lit
Literal constant payload (JS ConstVal.val: string | number | boolean | null)
NullCtx
pub(all) struct NullCtx {
}NullStack
pub(all) struct NullStack {
}ParseCtx
Path
An address into the component/state tree: a sequence of steps root→leaf.
Path::field
Path::new().field("rows").index("rows", 2) — the absolute twin of the
relative PathChanges builder, which delegates to these so the two spell
a step the same way. Each returns a fresh Path, so a base is reusable.
Path::index
A positional item of a sequence FIELD. There is no bare-index step: a Path
addresses field-then-key, so a nested .a[0][1] is not expressible and the
value-level item/index are what read one.
Path::key
A keyed item of a sequence field.
Path::to_label
The addressing steps as readable text.
Over to_keys, so the frame-only steps (which address nothing) are absent
and a seq-access step shows as its field.
PathChanges
PathChanges::bubble
Bubble name from the built path (JS PathChanges.bubble: skipSelf + bubbles).
PathChanges::build_path
The absolute dispatch path this builder addresses: the ctx's path with the
accumulated steps appended (JS PathChanges.buildPath).
PathChanges::field
Descend into field name (JS PathBuilder.field).
PathChanges::index
Descend into element i of sequence field name (JS PathBuilder.index).
PathChanges::key
Descend into keyed element key of map field name (JS PathBuilder.key).
PathChanges::send
Send name at the built path (JS PathChanges.send).
PathKey
A concrete sequence key: list index or map key (JS SeqStep.key is int|string)
PathKey::to_label
A key as its addressing text: 2 or title.
Pred
RequestOpts
Options for Ctx::request (JS pushRequest opts): response-handler routing
(on_ok_name / on_error_name / on_res_name) and live_path, which opts out
of pinning field-resolved keys at request time.
RequestOpts::new
fn RequestOpts::new(on_ok_name? : String, on_error_name? : String, on_res_name? : String, live_path? : Bool) -> RequestOptsSchemaInfo
What a component declares, as static metadata.
inputs is the one that matters most: the names update answers are
UNKNOWABLE at runtime (it is one opaque pattern match), so introspection
could only ever report THAT an update exists. The generator knows them.
SchemaInfo::field
Linear over fields, which is the right shape at these sizes: a component
has a handful of them and the array preserves declaration order, which the
callers below read as much as they read the entries themselves.
SchemaInfo::new
fn SchemaInfo::new(name? : String, fingerprint~ : String, fields? : Array[FieldInfo], inputs? : Array[String], receives? : Array[String], bubbles? : Array[String], responses? : Array[String], methods? : Array[String], ids? : Array[String], view_names? : Array[String], init_names? : Array[String]) -> SchemaInfoStep
pub(all) enum Step {
FieldStep(String)
SeqStep(field~ : String, key~ : PathKey)
SeqAccessStep(seq_field~ : String, key_field~ : String)
EachRenderItStep(field~ : String, key~ : PathKey)
BindStep(binds~ : Map[String, Value])
ScopeBindStep(val~ : Val)
EachBindStep(val~ : Val, when_val~ : Val?, enrich_with_val~ : Val?, loop_with_val~ : Val?, key~ : PathKey)
} derive(Eq, Debug)Path steps (src/path.js). FieldStep/SeqAccessStep are what values address
(Val::to_path_item); SeqStep is a field + concrete key (also the pinned form
of SeqAccessStep); EachRenderItStep is an iterated render target that
compacts to a SeqStep; Bind/ScopeBind/EachBind are frame-only (stack
rebuild). Dynamic-var markers live on DispatchStep in the path package.
StepKey
A generic {field, key?} descriptor of an addressing step (JS
Step.toKey), so tooling can introspect a path without matching on Step.
TyInfo
What a declared field carries.
TyInfo::elem
What this type CONTAINS, or None when it contains nothing.
Strict, and deliberately not the same question @statedef.StateTy::elem
answers. That one asks "may a view @each over this?", where any and a
child slot must both say yes — a dynamic value may turn out to be a list and
a component iterates its own entries, neither knowable at generation time.
Answering the two with one method put a meaningless elem: any on 117
fields of the corpus and showed it in the inspector, where the question is
the other one: what is in here?
TyInfo::kind
The runtime kind: how a value of this type is REPRESENTED, once the shape
that distinguishes it no longer matters.
A projection rather than a stored field, which is the point — the kind used
to be written beside the spelling and could contradict it.
TyInfo::members
A closed set's declared members. Empty for every other type, and for a set
with open membership — which is a real answer, not a missing one.
TyInfo::show_wit
How the author wrote it. The WIT spelling, because that is what is in the
file and what they will edit.
TyInfo::slot
The component a child slot holds, or None for a data field. Some("") is a
slot whose component the schema did not name.
TyInfo::zero
The empty value of this type, as the runtime carries it.
Type-directed, like the generated <T>State::zero() — which is the point:
a default is not an independent fact about a field, so storing one beside
the type would be a second thing to keep true. The one default a TYPE cannot
give is a child slot's construction arguments, and those are a value the
author chooses rather than anything the schema knows.
This is what an inspector shows in a field's "default" column, reachable
from a bare Value — it used to come off Component.specs, which a holder
of an instance and no registry could not get to.
Val
pub(all) enum Val {
Const(lit~ : Lit, from_macro~ : Bool)
StrTpl(Array[Val?])
Predicate(pred~ : Pred, args~ : Array[Val])
Name(String)
HandlerName(name~ : String, ns~ : HandlerNamespace)
TypeName(String)
Bind(String)
BindMember(name~ : String, prop~ : String)
Dyn(String)
Field(String)
Method(String)
SeqAccess(seq~ : String, key~ : String)
} derive(Eq, Debug)Parsed value AST. One variant per JS BaseVal subclass. from_macro ports
ConstVal.fromMacroVar: set when a ^name macro var resolves to a constant,
which makes an enclosing template non-literal. StrTpl parts alternate text
constants and placeholder expressions; a None part is a placeholder whose
inner expression failed to parse (JS keeps null there).
Value
Dynamic runtime value: what eval(stack) reads and returns.
Structural equality (immutable.js is over our Value shapes). NaN equals
NaN (Object.is); Fn values compare by reference.
The identity fast path is not just an optimization of the common case: the
runtime shares structure aggressively (copy-on-write spines, the value
stash restoring Obj/Fn by reference), so most comparisons of a rebuilt
tree against its predecessor meet the SAME object a level or two down.
Answering those in O(1) is what keeps an equality check over a 1000-item
list proportional to what actually changed. It agrees with the arms below
everywhere, NaN included.
Trait form of Value::from_json, total (never raises).
Value::as_key
This value AS a sequence key: a string keys a map, an integral number
indexes a list. None for everything else — including a non-integral number,
which is not an index and must not be rounded into one.
The bridge between the value world and the addressing world: it is how a
.seq[.key] read turns the key FIELD into the key it looks up, and how the
renderer names an iterated item in its §Each§ breadcrumb.
Value::at
The value at a path, or Null at the first step that does not resolve.
This is the composition, not a new primitive: one-hop reads stay
field/item, because building a one-element Path to replace a match
costs three allocations. Reach for a Path when the ADDRESS is the thing
being passed around — a transaction target, an observed change, a test's
assertion site.
Value::at_opt
The value at a path, distinguishing "no such place" from a Null stored
there — the one distinction at cannot express and no coercer can recover.
Value::call
Call a function value under the Fn convention: element 0 of the argument
array is the this slot, which self-pre-bound callees ignore. Null for a
non-function.
The convention was hand-rolled at every call site — match v { Fn(f) =>f([Null, x]) ... } — with the dummy slot spelled out each time.
Value::call_field
Call a method OF this value, with this value in the this slot: the
$name read followed by the invocation, which is how a view calls one and
how a handler filters a list of instances it cannot downcast.
Value::entries
The ordered (key, value) entries of any container: a list keyed by index, a
map by name, a custom collection by whatever obj_seq_entries says. Empty
for anything that is not one (the JS unkIter default).
TOOLING and one-off use: this materializes. The renderer's @each keeps
indexing List and Map directly, because allocating a tuple per item on
every render is not what a convenience is for.
Value::field
Field access that works on Map values and Obj instances alike; Null for
anything else (including missing fields).
Value::field_info
The declared description of one field.
Value::field_names
Every field name: declaration order for a described instance, key order for
a Map, empty for anything else (including an instance that declares
nothing — "no schema" is not "no fields", and guessing is what the schema
work removed).
Value::field_opt
A field, or None when there is no such field. Map and Obj answer,
anything else has no fields.
Value::from_json
Build a Value from parsed JSON. Lossless: every JSON shape has a Value.
Value::handler
The handlers a value carries: component instances answer through the Obj
trait, pure data has none.
Value::index
v.index(2) — an item by position.
Value::is_truthy
JS truthiness: Null/false/0/NaN/"" are false; lists, maps and functions
are always true (like JS objects). The truthy? predicate differs on
purpose: it treats empty collections as falsy (see pred_truthy).
Value::item
An item by key, or the default.
Value::item_opt
An item by key: a list index, a map key, or whatever a custom collection
resolves through obj_item. None when there is no such item.
Value::key
v.key("id") — an item by name. Distinct from field: a Map answers
both, but a component instance keys its SEQUENCE here and its FIELDS there.
Value::list
The list payload; [] for non-lists (shared empty NOT returned — fresh).
Value::map
The map payload; empty for non-maps (fresh, like Value::list).
Value::schema
What this value DECLARES, when it is a component instance that says.
Value::size
How many items, or 0. The total form of size_of.
Value::snapshot
name -> value for every declared field, in declaration order.
What every consumer that wanted to SHOW an instance had been faking: the
inspector read the names off a Components registry, the example builder
took them as a parameter, the dyncomp host parsed them out of a JSON
projection.
Value::to_display_string
JS ${v} template-interpolation semantics. Approximations: List joins
elements with ","; Map and Fn render as opaque markers (JS
"[object Object]" / function source are not worth mirroring).
Value::to_json
Json shape of a Value.
A DESCRIBED instance projects to its declared fields, recursively — which
is what makes a state dump JSON rather than a debug string. It used to
flatten to null along with Fn, because nothing could enumerate an Obj;
the consequence was a state_json() that returned the Show rendering and
said so in a comment, and a dyncomp migration path that parsed a
__dyncomp_state_json pseudo-field instead.
An instance that declares nothing is still null: with no schema there is
no field list to project, and inventing one is what the schema work
removed. Fn stays null unconditionally (JS structured clone would throw
on a function too), so a method or an unrendered handler inside a described
instance projects as null rather than taking the whole object with it.
Value::with_at
Copy-on-write write at a path, total: the SAME value back when the path
does not resolve (Path::set_value's own contract).
Value::with_field
Copy-on-write field write, total: the value unchanged when the field cannot
be written.
Value::with_field_opt
Copy-on-write field write; None when there is no such field to write (no
such field on an instance, not a container at all). The partial form is
what step_put needs: a step that cannot be addressed must leave the whole
tree untouched rather than silently write nothing.
Value::with_item
Copy-on-write item write, total. Same identity contract as with_field.
mutator_name
fn mutator_name(verb : String, field : String) -> StringThe name of a field's generated mutator: count + set -> setCount.
The convention lives HERE, in one function, because two places have to agree
on it and neither can see the other. component() builds the mutators by
concatenating it, and the state editor — which holds a bare Value and calls
them by name through Obj::obj_field — reconstructed the same string from
its own copy. Two spellings of one convention, either of which could have
been changed alone.
size_of
JS sizeOf: .size (immutable collections) or .length (string/array).
A custom collection answers too, through obj_size. It used to be None —
so an instance @each iterated happily had no length, empty? was always
false for it and the generated xLen mutator returned Null. An instance
that is NOT a sequence still answers None, which is the honest reading: a
component has fields, not a size.
step_keys_label
Addressing steps as readable text: value.rows[1].title.
Over StepKey rather than Step, because that is the projection a
transaction is RECORDED as (ObserveRecord.path_keys) — so a log line and
a Path print the same way without the log having to keep the Path.
step_with_key
Key a step with the si/sk an §Each§ meta carried (JS Step.withIndex /
withKey, used by event reconstruction's applyKey): a plain field access
under a keyed meta addresses the keyed item. Steps that carry their own
key (or no field) are returned unchanged.
tokenize_value
The single value tokenizer: a $'…' template run, a plain '…' literal
(escapes kept in the token), or a maximal non-whitespace run. Quoted
alternatives win only at their start; an unterminated quote falls back to
the plain run (mirrors the JS regex alternation).
Install
Download zipMoonBit port of the tutuca UI framework (value language, templates, vdom, components, app runtime, lint, CLI)
uiframeworkvdomreactivemoonbit
MIT
Updated 2 months ago
532 downloads