The type of the data held in the model.
The type of the data's keys.
The type of the data's ID.
The type of instances managed by attached observers.
The type of data associated with each observer instance.
The type of the data held in the model.
The type of the data's keys.
The type of the data's ID.
The type of instances managed by attached observers.
The type of data associated with each observer instance.
Optionalproperties: GradumModelProperties = {}
Optional initialization properties.
Static ReadonlyALLSymbol used in nestAll, makeSignals, and generateObserver to target all entries at a certain level inside the data.
The default constructor used to create nested GradumModel instances.
The default constructor used to create nested GradumModel instances.
The default constructor used to create GradumObserver instances via generateObserver.
The default constructor used to create GradumObserver instances via generateObserver.
ReadonlyonReadonlyonHook invoked by GradumModel.fireCallback. Assign it to route named callbacks from the model out to whatever owns it.
ProtectedisWhether GradumModel.initialize has already run on this model.
Protected ReadonlychangeProtected ReadonlynestedProtectednestedAll values in the model, in the order of GradumModel.keys.
StaticfromFunction
from
The type of the data to wrap.
The type of the data's ID.
The proxied data.
StaticcreateFunction
create
The class create was called on.
Optionalproperties: GradumModelProperties = {}
Optional initialization properties.
The created model, typed as the class this was called on.
Instantiate a model, then optionally initialize it and make its signals. The return type
follows the class it is called on, so GradumYModel.create(...) yields a GradumYModel with its
Y-specific members intact.
Note: the callee is read through this["prototype"] rather than InstanceType<this>. The latter
instantiates this class' generics with their constraints (object, KeyType, unknown) instead of
their any defaults, which breaks inference at every call site.
ProtectedsetupProtectedgetProtected Function
getAction
The container to read from.
The key to read.
The value at the key, or undefined if not found.
Function
get
The key to read.
The stored value, or undefined if not found.
Function
get
Ordered path from outermost to innermost key.
The stored value, or undefined if not found.
Function
getFlat
A flat key produced by flattenKey.
Optionaldepth: number
Required when flatKey is a numeric index. The depth of the key path.
The stored value, or undefined if not found.
Function
getKey
The value to locate.
The key path, or undefined if not found.
Function
getFlatKey
The value to query.
The flat key, or undefined if not found.
Function
getFlatKeys
The value to query.
Array of flat keys.
ProtectedsetProtected Function
setAction
The container to write to.
The value to set.
The key to write.
ProtectedinternalProtected Function
internalSet
The owning model (used for nested model lookup and change notification),
or undefined if operating on a non-root container.
The container to write to.
The value to set.
The key to write.
Write a value at a key, propagating the change to a nested model if one exists, and firing keyChanged if the value actually changed.
Function
set
The value to set.
The key to write.
Function
set
The value to set.
Ordered path from outermost to innermost key.
Function
setFlat
The value to set.
A flat key produced by flattenKey.
Optionaldepth: number
Required when flatKey is a numeric index. The depth of the key path.
ProtectedinternalProtected Function
internalAdd
The owning model for change notification, or undefined for non-root containers.
The container to insert into.
The value to insert.
The target index or key.
The index or key where the value was stored.
Insert a value into a container via addAction and fire keyChanged.
ProtectedaddProtected Function
addAction
The owning model.
The container to insert into.
The value to insert.
The target index or key. Clamped to valid array bounds for array containers.
The index or key where the value was stored.
Function
add
The value to insert.
The index where the value was stored.
Push a value to the end of an array-backed model. For non-array models, forwards to set.
Function
add
The value to insert.
Optionalkey: DataKeyType
The index to insert at. If omitted, the value is pushed to the end.
The index where the value was stored.
Insert a value into an array-backed model at the given index, or push it if no index is given. For non-array models, forwards to set.
Function
add
The value to insert.
Key path to the target node, with the last key as the insertion index.
The index or key where the value was stored.
Insert a value at the given key path. For array-backed nodes, the last key is the insertion index. For non-array models, forwards to set.
Function
addFlat
The value to insert.
A flat key produced by flattenKey.
Optionaldepth: number
Required when flatKey is a numeric index. The depth of the key path.
The index or key where the value was stored.
ProtectedhasProtected Function
hasAction
The container to check.
The key to check.
true if the key is present.
Function
has
Ordered path from outermost to innermost key.
true if the entry exists.
Function
hasFlat
A flat key produced by flattenKey.
Optionaldepth: number
Required when flatKey is a numeric index. The depth of the key path.
true if an entry exists at that flat key.
ProtecteddeleteProtected Function
å
deleteAction
The container to remove from.
The key to remove.
ProtectedinternalProtected Function
internalDelete
The owning model for nested model cleanup and change notification,
or undefined for non-root containers.
The container to remove from.
The key to remove.
Remove a key from a container, clearing any associated nested model, and firing keyChanged. No-op if the key does not exist.
Function
delete
Ordered path from outermost to innermost key.
Function
deleteFlat
A flat key produced by flattenKey.
Optionaldepth: number
Required when flatKey is a numeric index. The depth of the key path.
ProtectedgetProtecteddiffProtected Function
diffCheck
true if the swap can be done in place.
Whether two data containers are similar enough to be swapped in place by GradumModel.diffAction rather than triggering a full clear and re-initialize. True for two plain objects, two arrays, or two Maps.
ProtecteddiffProtected Function
diffAction
Swap in new data while keeping existing nested models and signals alive, re-pointing each child at its counterpart in the new data instead of tearing the tree down. Only called when GradumModel.diffCheck accepts the pair.
Function
forEach
Called with the value, key, and model.
OptionalthisArg: any
Value to use as this when calling the callback.
Function
makeSignal
The type of the signal's value.
The key to create a signal for.
The signal for that key. Reading or writing it keeps the model's data in sync.
Function
makeSignals
The type of the signals' values.
Key path to the signal targets. Use ALL at any level to target all entries there.
One signal per key at that path, in the order the keys appear.
Return reactive SignalBox instances for multiple keys at the given path. Pass GradumModel.ALL at any level of the path to expand all entries at that level.
Function
getSignal
The key whose signal to retrieve.
The existing signal, or undefined if the key has none.
Retrieve an existing SignalBox for the given key, or undefined if none exists.
Function
getSignal
Key path, with the last key as the signal target.
The existing signal, or undefined if the key path has none.
Retrieve an existing SignalBox for the given key path, or undefined if none exists.
The last key in the path is the signal's target; preceding keys navigate to the parent nested model.
Function
nestAll
This model, wrapped in an array so the result matches the other overloads.
Function
nestAll
Key path to the subtree to expand.
Array of nested models.
Create or retrieve nested GradumModel instances at each entry under the given key path. Use GradumModel.ALL in the path to expand all entries at that level.
Function
nestAll
Key path followed by optional properties.
Array of nested models.
Create or retrieve nested GradumModel instances at each entry under the given key path, with custom initialization properties for the nested models. Use GradumModel.ALL in the path to expand all entries at that level.
Function
nest
The key of the nested model.
The nested model at that key, created on first access and reused after.
Create or retrieve a single nested GradumModel at the given key.
Function
nest
Ordered path from outermost to innermost key.
The nested model at that key path, created on first access and reused after.
Create or retrieve a single nested GradumModel at the given key path.
Function
nest
Key path followed by optional properties.
The nested model at that key path, created on first access and reused after.
Create or retrieve a single nested GradumModel at the given key path, with custom initialization properties.
Function
getNested
The key of the nested model.
The nested model, or undefined if that key was never nested.
Function
getNested
Ordered path from outermost to innermost key.
The nested model, or undefined if that path was never nested.
Function
generateObserver
Optionalproperties: GradumObserverProperties<DataEntryType, ComponentType, DataKeyType> = {}
Observer options and lifecycle callbacks.
Optional key path to the nested model(s) to observe. Use ALL at
any level to process all entries there.
The attached observer. Keep the reference to read its instances or destroy it later.
Create and attach a GradumObserver to this model. If a key path is provided, the observer is attached to the nested model(s) at that path instead. Pass GradumModel.ALL at any level of the path to process all entries at that level, allowing a single observer to track multiple subtrees simultaneously.
Function
generateDeepObserver
Optionalproperties: GradumObserverProperties<DataEntryType, ComponentType, DataKeyType> = {}
Observer options and lifecycle callbacks.
Optional key path to the nested model(s) to observe.
The attached observer. Keep the reference to read its instances or destroy it later.
Like generateObserver, but fires for the registered depth and all deeper levels.
Whereas generateObserver(..., GradumModel.ALL) only notifies at depth-2, generateDeepObserver(..., GradumModel.ALL)
also notifies for depth-3, depth-4, etc. — passing the full key path to onAdded/onUpdated/onDeleted.
Use when you need to react to any nested change regardless of depth.
ProtectedinitializeProtected Function
initializeObserverOnPath
The data to walk.
The observer to notify.
The remaining key path to walk.
The path already walked, passed back to the observer.
Walk the data along an observer's key path and report every existing entry to it, so an observer attached to already-populated data still sees what is there. Paths containing GradumModel.ALL fan out across every entry at that level.
ProtectedkeyProtected Function
keyChanged
The key path that changed.
Optionalvalue: unknown = ...
The new value. Defaults to the current value at the key.
Optionaldeleted: boolean = false
Whether the entry was removed.
Called internally whenever an entry is added, updated, or deleted. Emits signals, fires onKeyChanged, and notifies attached observers.
Function
flattenKey
The key path to serialize.
The flat key: a number for a fully numeric path, otherwise a "k0|k1" string.
Function
scopeKey
The flat string key to convert.
The key path the flat key was built from.
Convert a flat string key back into a key path. Reverses the string form of flattenKey.
Segments starting with "@@" are decoded back to symbols.
Function
scopeKey
The numeric index to convert.
The depth of the key path to reconstruct.
The numeric key path that global index maps to at the given depth.
Convert a numeric global index back into a numeric key path. Reverses the numeric form of flattenKey.
Function
getHandler
The handler's key.
The handler registered under that key, or undefined if there is none.
Function
addHandler
The handler instance to register.
Function
setDataWithoutInitializing
The data to adopt.
Point the model at new data without running GradumModel.initialize on it, so
observers and signals are not re-created. Use it when the caller will initialize at a moment of its
own choosing; prefer assigning data otherwise.
Function
fireCallback
The name of the callback to fire.
Arguments forwarded to the hook.
Fire a named callback through GradumModel.fireCallbackHook. Does nothing if no hook has been assigned.
GradumModel
Description
Wrapper around a plain JS container (object, Array, or Map) that exposes a consistent API for reads/writes, signals, and GradumObservers.