On This Page
Creating
Reading
Writing
Teardown
Fine-grained reactivity over a plain object, at the granularity of a path. A reader of one path wakes only when that path’s value changes, where a Signal holding an object wakes every reader on any change.
Paths use the @semantic-ui/utils grammar: dotted keys (user.name), positional indices (list[0]), and keyed array segments (todos[#a3f].done). Cells are keyed by the literal path string, so address an element consistently. A reader of todos[#a3f].done is not woken by a positional write to todos[0].done that hits the same element.
Creating
reactiveObject
reactiveObject(initialValue, options);Creates a reactive wrapper over a plain object. initialValue defaults to {}.
Parameters
| Name | Type | Description |
|---|---|---|
| initialValue | object | The backing object |
| options | object | Optional configuration |
Options
| Name | Type | Default | Description |
|---|---|---|---|
| safety | 'clone' | 'reference' | 'none' |
'reference' |
Value-protection preset. clone copies on read and on inbound set/replace, none re-fires on every set. See Signal Options |
| equality | function | deep equality | Decides whether a written value differs from the value already at a path |
| clone | function | structured clone | Copies values under safety: 'clone' |
| version | number | 0 |
Seeds the change counter, for aligning with an external store’s revision |
Example
Reading
get
reactiveObject.get(path);Returns the value at path and subscribes the running reaction to that path alone, so a later write to a disjoint path will not re-fire it.
Parameters
| Name | Type | Description |
|---|---|---|
| path | string | The path to read |
Returns
The value at path, or undefined if absent.
peek
reactiveObject.peek();reactiveObject.peek(path);Untracked read that subscribes to nothing. With a path, the value there. Without one, the whole backing object.
Parameters
| Name | Type | Description |
|---|---|---|
| path | string | Optional path to read |
Returns
The value at path, or the whole backing object when no path is given.
hasDependents
reactiveObject.hasDependents();reactiveObject.hasDependents(path);Whether any live reaction subscribes to path, or to the whole object when no path is given.
Returns
true when a live subscriber exists.
depend
reactiveObject.depend(path);Subscribes the running reaction to path without reading its value, the path-scoped twin of a Signal’s depend. Use it when a reaction should re-run when a path changes but reads the value from elsewhere.
Parameters
| Name | Type | Description |
|---|---|---|
| path | string | The path to subscribe to |
Example
has
reactiveObject.has(path);Tracked existence check that distinguishes a stored undefined from a missing path, subscribing the running reaction to path. It wakes through the same cell as get, so removing or re-adding the key re-runs the reader.
Parameters
| Name | Type | Description |
|---|---|---|
| path | string | The path to test |
Returns
true when the path is present, even if its value is undefined.
Example
raw
reactiveObject.raw();reactiveObject.raw(path);Returns the live stored reference with no dependency tracking and no clone protection, even under safety: 'clone' where peek still copies. With a path, the value there. Without one, the whole backing object.
raw hands back the actual stored value, not a copy. Mutating it bypasses change detection, so pair it with notify to announce the change. Prefer peek unless you need the live reference.
raw hands back the actual stored value, not a copy. Mutating it bypasses change detection, so pair it with notify to announce the change. Prefer peek unless you need the live reference.
Parameters
| Name | Type | Description |
|---|---|---|
| path | string | Optional path to read |
Returns
The live stored value, or the whole backing object when no path is given.
clone
reactiveObject.clone(path);reactiveObject.clone();Returns a detached deep copy at path and subscribes the running reaction to it, so mutating the copy never touches the stored value while a later write still re-runs the reader. Always copies, even under safety: 'reference'. With no path, clones the whole backing object untracked, mirroring peek’s no-path form.
Parameters
| Name | Type | Description |
|---|---|---|
| path | string | Optional path to copy |
Returns
A detached copy of the value at path, or of the whole object when no path is given.
Example
version
reactiveObject.version;reactiveObject.version = revision;A monotonic integer that bumps on every wake-causing write: a set to a non-equal value, a successful remove, and every replace, clear, and notify. An equality-gated no-op set leaves it unchanged. Reading it does not subscribe the running reaction.
Assign to it to realign with an external store’s revision, and seed the starting value with the version option on reactiveObject.
Returns
The current change count, starting at 0.
Example
Writing
set
reactiveObject.set(path, value);Writes value at path, waking readers of that path, of its ancestors, and of any descendant whose resolved value changed.
Parameters
| Name | Type | Description |
|---|---|---|
| path | string | The path to write |
| value | any | The value to set |
Returns
true when the write changed the value, false for an equality-gated no-op or a write the backing object drops.
notify
reactiveObject.notify(path);Force-wakes path after an in-place mutation, the path-scoped twin of a Signal’s notify. It wakes the exact path, its ancestors, and every descendant under it, since with no before image there is nothing to diff. Pair it with raw when you mutate the stored object directly and readers need to know. Bumps version.
Parameters
| Name | Type | Description |
|---|---|---|
| path | string | The path whose subtree changed in place |
Example
remove
reactiveObject.remove(path);Removes path so the key leaves the object, reading back absent rather than undefined-valued. It keys on presence, so a key holding a stored undefined is still removable, and only an already-absent path is a no-op.
Parameters
| Name | Type | Description |
|---|---|---|
| path | string | The path to remove |
Returns
true when the removal changed the object.
replace
reactiveObject.replace(nextObject);Swaps the whole backing object and reseeds every live reader against the new one, waking only the paths whose value changed, including deep readers under a wholesale-replaced subtree. The path for fresh data arriving in bulk.
Parameters
| Name | Type | Description |
|---|---|---|
| nextObject | object | The replacement backing object |
clear
reactiveObject.clear();Replaces the backing object with an empty one.
Teardown
prune
reactiveObject.prune();Sweeps cells nobody subscribes to. replace and subtree writes sweep as they go, so this is the explicit hook for an instance driven only by set and remove.
stop
reactiveObject.stop();Drops every cell. Live subscribers stop receiving wakes and future reads mint fresh cells.