Modules · Core

Reactive

The reactive core: the primitives every other module is built on. A small set of data types describe what a reactive value is made of; a set of functions create and combine those values, covering state, reverses and bindings, control flow, and mounting a program's update loop.

This reference lists the full surface, drawn from the reactive runtime. It will be refined down to the everyday core; the deeper types and helpers are here for completeness.

Contents

Types

Functions

Types

ReactiveArray

A reactive sequence of keyed elements: the shape Each iterates over.

Fields

FieldTypeDescription
elementsReactiveArrayElement[]The elements, in order, each with a stable key.

ReactiveArrayElement

One element of a ReactiveArray: a value paired with a stable key so a view stays bound to it across inserts, removals and reorders.

Fields

FieldTypeDescription
keystringA unique, stable key, kept for the element's lifetime.
valueanyThe element's value.

ReactiveError

The error carried by a lock: a message, and optionally a flag you can set to retry.

Fields

FieldTypeDescription
messagestringThe error message.
optionalRetryFlagIdnumber?A settable id; Set it to true to trigger a retry. Recover the settable with Dereference.

ReactiveGettable

The readable half of a value: its current native value, and whether it is locked (not ready).

Fields

FieldTypeDescription
valueanyThe native value held.
optionalLockReactiveLock?Present when the value is locked, whether in flight or errored; the value is available while it is omitted.

ReactiveLock

Marks a value as pending: loading, or failed. Its presence propagates through calculations; while it is omitted, the value is available.

Fields

FieldTypeDescription
optionalErrorReactiveError?Present when the lock is an error; a plain loading state omits it.

ReactiveProcess

A callback plus the root scope items that give its state and emissions stable identity across runs.

Fields

FieldTypeDescription
callbackfunctionThe code to run; it takes zero arguments and returns void.
rootScopeItemsReactiveScopeItem[]The root scope items, carried between runs so identity is stable.

ReactiveProgram

A program together with its persisted state and reverse processes: the value the runtime carries and returns each cycle.

Fields

FieldTypeDescription
forwardProcessReactiveProcessThe main program execution.
reverseProcessesMapSettable id → the reverse process to run when that value is set.
valuesMapPersisted settable values from the last run: the program's memory across cycles.

ReactiveScopeItem

One call-site position within a run, with any named branch scopes beneath it. This is how state and emissions keep the same identity from one run to the next.

Fields

FieldTypeDescription
idnumberStable id for this call-site position.
branchesMapNamed branch scopes; each is the scope items list for one branch of a conditional or one row of an iteration.

ReactiveSettable

The writable half of a value: a stable identity, and an optional reverse to run when it is Set.

Fields

FieldTypeDescription
idnumberStable settable id: its identity across runs.
optionalNativeReverseCallbackfunction?The reverse. When present, Set runs it; otherwise the value is a source and Set stores against its id.

ReactiveValue

A value in the reactive graph. It is made of two optional halves: a gettable (readable) and a settable (writable); which halves are present decides whether it can be read, written, or both.

Fields

FieldTypeDescription
optionalGettableReactiveGettable?The readable half. Present when the value can be read; a write-only value omits it.
optionalSettableReactiveSettable?The writable half. Present when the value can be set; a read-only value omits it.

Functions

Reactive.AddError

Returns a value locked with an error appended. The optional retry flag id can be Set to true to trigger a retry.

Parameters

NameTypeDescription
valueanyThe value to attach the error to.
errorMessagestringThe message.
optionalRetryFlagIdnumberA settable retry-flag id.

Returns

A locked ReactiveValue carrying the error.

Reactive.AddErrorOptional

Note: not confirmed in the current Reactive.* surface. Left in place pending review.

Attaches an error to a value only when a message is present; otherwise returns it unchanged. Useful for errors that are themselves reactive or conditional.

Parameters

NameTypeDescription
valueanyThe value to conditionally attach an error to.
optionalErrorMessageanyAn optional message, plain or reactive; a missing message leaves the value unchanged.

Returns

A ReactiveValue: errored when a message is present, unchanged otherwise.

Reactive.Binding

Joins a gettable value and a settable value into one that is both: a two-way value that reads forward and writes backward.

Parameters

NameTypeDescription
gettableReactiveValueThe readable side, usually a value derived from a module operation.
settableReactiveValueThe writable side, usually a Reverse.
optionalDependenciesReactiveValue[]Extra values whose locks should also apply. Default [].

Returns

A gettable-and-settable ReactiveValue.

Example

const fahrenheit = Reactive.Binding(reading, writing);
Binding a gettable and settable

Reactive.Branches

Note: not confirmed in the current Reactive.* surface. Left in place pending review.

Opens named child scopes at the current position: the low-level basis for conditionals and iteration. If and Each are built on it.

Parameters

NameTypeDescription
branchCallbackfunctionReceives a scope function for creating named child scopes.

Reactive.Loading

Creates a piece of state that starts locked (loading). Curried and typed like State: call it with a type, then with the initial value. Unlock it by Setting a ready value.

Parameters

NameTypeDescription
typeTypeThe type of the state. Use Reactive.Any to stay loosely typed.
initialValueanyThe value held while loading, passed to the returned function.

Returns

A gettable-and-settable ReactiveValue, locked until Set.

Example

const user = Reactive.Loading(Reactive.Any)(null);
State that starts locked and loading

Reactive.Create

Note: not confirmed in the current Reactive.* surface. Left in place pending review.

Wraps a raw value as a constant reactive value, or returns it unchanged if it is already reactive.

Parameters

NameTypeDescription
valueanyA plain value or a ReactiveValue.

Returns

A gettable-only ReactiveValue.

Reactive.Dereference

Note: not confirmed in the current Reactive.* surface. Left in place pending review.

Recovers the value a settable id refers to: the inverse of Reference.

Parameters

NameTypeDescription
settableIdnumberA settable id, as returned by Reference.

Returns

The ReactiveValue it refers to.

Reactive.Each

Iterates a ReactiveArray, running the callback once per element in its own branch scope so each row keeps its identity across inserts, removals and reorders.

Parameters

NameTypeDescription
reactiveArrayReactiveArrayThe array to iterate.
itemCallbackfunctionCalled once per element with the element's reactive value.

Example

Reactive.Each(items, (item) => {
  // … render item …
});
Iterating over a reactive array

Reactive.GetObjectField

Note: not confirmed in the current Reactive.* surface. Left in place pending review.

A reactive accessor for one field of an object, optionally two-way: it reads the field with a getter, and, when the object itself is settable, writes it back with a changer.

Parameters

NameTypeDescription
objectanyThe data object, raw or reactive.
rawFieldGetterFunctionfunction(object) => fieldValue.
rawFieldChangerFunctionfunction(object, newFieldValue) => updatedObject.

Returns

A gettable ReactiveValue, gettable-and-settable when the object is settable.

Reactive.HasError

Whether a value is locked with an error, distinct from a plain loading state.

Parameters

NameTypeDescription
valueanyRaw or reactive.

Returns

A boolean.

Reactive.HasRetryFlag

Whether a value's error carries a retry flag.

Parameters

NameTypeDescription
valueanyRaw or reactive.

Returns

A boolean.

Reactive.If

Runs the callback only when the condition is truthy, in its own scope so what it describes appears and disappears cleanly.

Parameters

NameTypeDescription
conditionanyReactive or plain; the callback runs when it is truthy.
onTruefunctionWhat to describe while the condition holds.

Example

Reactive.If(open, () => {
  // … shown only while `open` is true …
});
Rendering only while a condition is true

Reactive.IsLocked

Whether a value is locked: pending, whether loading or errored. Raw values always read as unlocked.

Parameters

NameTypeDescription
valueanyRaw or reactive.

Returns

A boolean.

Reactive.Lock

Locks a value when the flag is true, marking it pending (a loading state); returns it unchanged otherwise.

Parameters

NameTypeDescription
valueanyRaw or reactive.
lockedanyWhether to lock, as a raw or reactive boolean.

Returns

A ReactiveValue, locked or unchanged.

Reactive.OptionalErrorMessage

The error message on a value, or undefined when the value is clear.

Parameters

NameTypeDescription
valueanyRaw or reactive.

Returns

A string, or undefined.

Reactive.OptionalRetryFlag

The retry flag carried by a value's error, or undefined. Set it to true to trigger a retry.

Parameters

NameTypeDescription
valueanyRaw or reactive.

Returns

A settable ReactiveValue, or undefined.

Reactive.Mount

The entry point. Runs a content callback and drives its output into a target, running the update loop for you. For the DOM, point the content driver at a root element.

Parameters

NameTypeDescription
contentCallbackfunctionDescribes the program and returns the driven outputs, such as { content }.
driverConfigobjectWhere each output is driven, such as { content: { root } } for the DOM.

Example

Reactive.Mount(() => {
  const ui = Dom(() => {
    // … describe the view …
  });
  return { content: ui.content };
}, { content: { root: document.getElementById('app') } });
Mounting a program onto the DOM

Reactive.Reference

Note: not confirmed in the current Reactive.* surface. Left in place pending review.

The settable's stable id: pass a settable through code (like a stored field) that would otherwise unwrap it. Reverse it with Dereference.

Parameters

NameTypeDescription
settableReactiveValueA settable value.

Returns

A number: the settable id.

Reactive.Reverse

Creates a settable-only value whose callback runs when it is Set: the write-only half you join to a forward calculation to make a two-way value.

Parameters

NameTypeDescription
reverseCallbackfunctionRuns when the value is Set, receiving the new value; typically Sets its own sources.

Returns

A settable-only ReactiveValue.

Example

const writing = Reactive.Reverse((f) => Reactive.Set(celsius, (f - 32) * 5 / 9));
Creating a reverse that writes backward

Reactive.Set

Writes to a value. State stores the value directly; a value that carries a reverse runs that reverse, cascading the change backward toward plain state.

Parameters

NameTypeDescription
reactiveValueReactiveValueA settable value: state, a reverse, or a binding.
newValueOrReactiveValueanyThe new value.

Example

Reactive.Set(count, count.value + 1);
Setting a new value

Reactive.StableId

Note: not confirmed in the current Reactive.* surface. Left in place pending review.

The stable id for the current call-site position: the same value on every run, which is how state persists.

Returns

A number.

Reactive.StableKey

Note: not confirmed in the current Reactive.* surface. Left in place pending review.

A stable string key for the current position, for use in collections and contexts.

Parameters

NameTypeDescription
optionalPrefixstringPrepended to the id, if given.

Returns

A string.

Reactive.State

Creates a piece of mutable reactive state, both readable and settable. Curried and typed: call it with a type, then with the initial value. It persists across runs by its stable position in the program.

Parameters

NameTypeDescription
typeTypeThe type of the state. Use Reactive.Any to stay loosely typed.
initialValueanyThe value on the first run, passed to the returned function.

Returns

A gettable-and-settable ReactiveValue.

Example

const count = Reactive.State(Reactive.Any)(0);
Creating a piece of state

Reactive.Value

Reads the native value out of a reactive value (or passes a raw value straight through). Used inside a reverse or driver callback to unwrap a reactive to its raw value.

Parameters

NameTypeDescription
valueOrReactiveValueanyA reactive value to unwrap, or a raw value to return as-is.

Returns

The native value.

Reactive.WithLockFrom

Returns a value carrying the lock from another: a way to propagate pending state from one value onto another by hand.

Parameters

NameTypeDescription
valueanyThe value to return, possibly with a merged lock.
lockSourceanyThe value whose lock is merged in.

Returns

A ReactiveValue with the merged lock.