Watcher
Defined in: watcher.ts:203
Watcher for tracking changes to observable properties
- Automatically tracks
@observableproperties - Supports
@watchand@watch.refannotations for what@observabledoes not cover, such as@computedproperties - Can track nested objects
- Provides change detection at both property and path levels
- Can be temporarily disabled via
unwatch()
Static Members
Section titled “Static Members”isWatching
Section titled “isWatching”Get Signature
Section titled “Get Signature”get
staticisWatching():boolean
Defined in: watcher.ts:267
Whether a change made right now would be detected
unwatch() turns it off for as long as its function runs, and on again as soon as the function returns.
Remarks
Section titled “Remarks”A watcher processes the changes of a transaction when the outermost one ends, so while it is doing that, this
reads false for the changes that unwatch() made in the transaction.
Returns
Section titled “Returns”boolean
staticget<T>(target):Watcher
Defined in: watcher.ts:230
Get a watcher instance for the target object.
Type Parameters
Section titled “Type Parameters”T extends object
Parameters
Section titled “Parameters”target
Section titled “target”T
Returns
Section titled “Returns”Watcher
Remarks
Section titled “Remarks”- Returns existing instance if one exists for the target
- Creates new instance if none exists
- Instances are cached by the identity of the target, so an object inheriting from a watched one gets its own
- Nothing is written to the target, so frozen, sealed and non-extensible objects are supported
- Instances are garbage collected with the target, unless they observe a
@computedof the target, such as one marked with@watch, that reads state outliving the target
Throws
Section titled “Throws”TypeError if the target is not an object.
getSafe()
Section titled “getSafe()”
staticgetSafe(target):Watcher|null
Defined in: watcher.ts:241
Get a watcher instance for the target object.
Same as Watcher.get but returns null instead of throwing an error.
Parameters
Section titled “Parameters”target
Section titled “target”any
Returns
Section titled “Returns”Watcher | null
Members
Section titled “Members”
readonlyid:string
Defined in: watcher.ts:204
changed
Section titled “changed”Get Signature
Section titled “Get Signature”get changed():
boolean
Defined in: watcher.ts:307
Whether changes have been made
Returns
Section titled “Returns”boolean
@computed
changedKeyPaths
Section titled “changedKeyPaths”Get Signature
Section titled “Get Signature”get changedKeyPaths():
ReadonlySet<KeyPath>
Defined in: watcher.ts:355
The key paths that have changed
A best-effort debugging aid, like changedKeys: it tells you where a change came from, and two keys that spell the same (private members of a class and of its subclass, for instance) are not told apart.
Remarks
Section titled “Remarks”Keys of nested objects are included, except for the ones excluded with @unwatch.
Returns
Section titled “Returns”ReadonlySet<KeyPath>
@computed
changedKeys
Section titled “changedKeys”Get Signature
Section titled “Get Signature”get changedKeys():
ReadonlySet<KeyPath>
Defined in: watcher.ts:341
The keys that have changed
A best-effort debugging aid: use it to find out why a watcher reports a change, not as a record of what changed. changed and changedTick are the contract; which key a change is filed under is not.
Remarks
Section titled “Remarks”- Does not include keys of nested objects
- Cleared when reset() is called
- Updated when properties are modified
Returns
Section titled “Returns”ReadonlySet<KeyPath>
@computed
changedTick
Section titled “changedTick”Get Signature
Section titled “Get Signature”get changedTick():
bigint
Defined in: watcher.ts:301
The total number of changes processed
Observe this value to react to changes.
Remarks
Section titled “Remarks”- Incremented for each change and each affected key
- Incremented for each
@nestedkey that a change below it reaches - Not affected by assumeChanged() on this watcher, although an assumed change of a nested watcher reaches it like a recorded one
- Reset to 0 when reset() is called
Returns
Section titled “Returns”bigint
nested
Section titled “nested”Get Signature
Section titled “Get Signature”get nested():
Generator<StandardNestedFetcher.Entry<Watcher>,void,unknown>
Defined in: watcher.ts:379
Nested watchers
Remarks
Section titled “Remarks”A fresh iterator over the @nested entries, in annotation order and then in collection order. Each entry
carries the name of the annotated member in key ("items"), the address of the nested object in keyPath
("items.0") and its watcher in data.
Each read starts a new iteration, and an iterator is consumed once, so a second pass needs a second read.
There is no lookup by name: entries are not unique by key path. To reach the watcher of one nested object, go
through the property — Watcher.get(target.child) is cached per subject, so it is the very instance yielded
here — or iterate and match entry.key, which is KeyPath.Self for a @nested.hoist member rather
than the name it is declared with.
Returns
Section titled “Returns”Generator<StandardNestedFetcher.Entry<Watcher>, void, unknown>
assumeChanged()
Section titled “assumeChanged()”assumeChanged():
void
Defined in: watcher.ts:409
@action
Assume some changes have been made
It only changes changed to true and does not increment changedTick.
Returns
Section titled “Returns”void
reset()
Section titled “reset()”reset():
void
Defined in: watcher.ts:393
@action
Reset the changed state
Returns
Section titled “Returns”void
Remarks
Section titled “Remarks”- Clears all changed keys
- Resets changedTick to 0
- Clears assumeChanged flag
- Resets all nested watchers