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.
Contents
Types
Functions
- Reactive.AddError
- Reactive.AddErrorOptional
- Reactive.Binding
- Reactive.Branches
- Reactive.Create
- Reactive.Dereference
- Reactive.Each
- Reactive.GetObjectField
- Reactive.HasError
- Reactive.HasRetryFlag
- Reactive.If
- Reactive.IsLocked
- Reactive.Loading
- Reactive.Lock
- Reactive.Mount
- Reactive.OptionalErrorMessage
- Reactive.OptionalRetryFlag
- Reactive.Reference
- Reactive.Reverse
- Reactive.Set
- Reactive.StableId
- Reactive.StableKey
- Reactive.State
- Reactive.Value
- Reactive.WithLockFrom
Types
ReactiveArray
A reactive sequence of keyed elements: the shape Each iterates over.
Fields
| Field | Type | Description |
|---|---|---|
elements | ReactiveArrayElement[] | 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
| Field | Type | Description |
|---|---|---|
key | string | A unique, stable key, kept for the element's lifetime. |
value | any | The element's value. |
ReactiveError
The error carried by a lock: a message, and optionally a flag you can set to retry.
Fields
| Field | Type | Description |
|---|---|---|
message | string | The error message. |
optionalRetryFlagId | number? | 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
| Field | Type | Description |
|---|---|---|
value | any | The native value held. |
optionalLock | ReactiveLock? | 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
| Field | Type | Description |
|---|---|---|
optionalError | ReactiveError? | 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
| Field | Type | Description |
|---|---|---|
callback | function | The code to run; it takes zero arguments and returns void. |
rootScopeItems | ReactiveScopeItem[] | 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
| Field | Type | Description |
|---|---|---|
forwardProcess | ReactiveProcess | The main program execution. |
reverseProcesses | Map | Settable id → the reverse process to run when that value is set. |
values | Map | Persisted 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
| Field | Type | Description |
|---|---|---|
id | number | Stable id for this call-site position. |
branches | Map | Named 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
| Field | Type | Description |
|---|---|---|
id | number | Stable settable id: its identity across runs. |
optionalNativeReverseCallback | function? | 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
| Field | Type | Description |
|---|---|---|
optionalGettable | ReactiveGettable? | The readable half. Present when the value can be read; a write-only value omits it. |
optionalSettable | ReactiveSettable? | 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
| Name | Type | Description |
|---|---|---|
value | any | The value to attach the error to. |
errorMessage | string | The message. |
optionalRetryFlagId | number | A 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
| Name | Type | Description |
|---|---|---|
value | any | The value to conditionally attach an error to. |
optionalErrorMessage | any | An 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
| Name | Type | Description |
|---|---|---|
gettable | ReactiveValue | The readable side, usually a value derived from a module operation. |
settable | ReactiveValue | The writable side, usually a Reverse. |
optionalDependencies | ReactiveValue[] | Extra values whose locks should also apply. Default []. |
Returns
A gettable-and-settable ReactiveValue.
Example
const fahrenheit = Reactive.Binding(reading, writing);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
| Name | Type | Description |
|---|---|---|
branchCallback | function | Receives 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
| Name | Type | Description |
|---|---|---|
type | Type | The type of the state. Use Reactive.Any to stay loosely typed. |
initialValue | any | The 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);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
| Name | Type | Description |
|---|---|---|
value | any | A 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
| Name | Type | Description |
|---|---|---|
settableId | number | A 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
| Name | Type | Description |
|---|---|---|
reactiveArray | ReactiveArray | The array to iterate. |
itemCallback | function | Called once per element with the element's reactive value. |
Example
Reactive.Each(items, (item) => {
// … render item …
});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
| Name | Type | Description |
|---|---|---|
object | any | The data object, raw or reactive. |
rawFieldGetterFunction | function | (object) => fieldValue. |
rawFieldChangerFunction | function | (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
| Name | Type | Description |
|---|---|---|
value | any | Raw or reactive. |
Returns
A boolean.
Reactive.HasRetryFlag
Whether a value's error carries a retry flag.
Parameters
| Name | Type | Description |
|---|---|---|
value | any | Raw 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
| Name | Type | Description |
|---|---|---|
condition | any | Reactive or plain; the callback runs when it is truthy. |
onTrue | function | What to describe while the condition holds. |
Example
Reactive.If(open, () => {
// … shown only while `open` is true …
});Reactive.IsLocked
Whether a value is locked: pending, whether loading or errored. Raw values always read as unlocked.
Parameters
| Name | Type | Description |
|---|---|---|
value | any | Raw 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
| Name | Type | Description |
|---|---|---|
value | any | Raw or reactive. |
locked | any | Whether 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
| Name | Type | Description |
|---|---|---|
value | any | Raw 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
| Name | Type | Description |
|---|---|---|
value | any | Raw 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
| Name | Type | Description |
|---|---|---|
contentCallback | function | Describes the program and returns the driven outputs, such as { content }. |
driverConfig | object | Where 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') } });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
| Name | Type | Description |
|---|---|---|
settable | ReactiveValue | A 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
| Name | Type | Description |
|---|---|---|
reverseCallback | function | Runs 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));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
| Name | Type | Description |
|---|---|---|
reactiveValue | ReactiveValue | A settable value: state, a reverse, or a binding. |
newValueOrReactiveValue | any | The new value. |
Example
Reactive.Set(count, count.value + 1);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
| Name | Type | Description |
|---|---|---|
optionalPrefix | string | Prepended 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
| Name | Type | Description |
|---|---|---|
type | Type | The type of the state. Use Reactive.Any to stay loosely typed. |
initialValue | any | The value on the first run, passed to the returned function. |
Returns
A gettable-and-settable ReactiveValue.
Example
const count = Reactive.State(Reactive.Any)(0);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
| Name | Type | Description |
|---|---|---|
valueOrReactiveValue | any | A 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
| Name | Type | Description |
|---|---|---|
value | any | The value to return, possibly with a merged lock. |
lockSource | any | The value whose lock is merged in. |
Returns
A ReactiveValue with the merged lock.