Listeners are special proxy objects that can trigger (one or several) callbacks when any of its properties are set.
- listener
- target ⟶ proxy
- nil ⟶ proxy
This code uses a listener proxy to represent a User so it can respond whenever the user gets updated.
The proxy object will override the following two properties of the target object:
listener.listen(<prop>, <callback>)
listener.listen(null, <callback>)
listener.listen(<prop>|null, <callback>, {once: true})
listener.forget(<prop>, <callback>)
listener.forget(<prop>)
listener.forget(null[, <callback>])
- callback
- new, old, prop ⟶ nil
- prop
- string
Note that callbacks will run regardless of whether the new and old values are actually different. It is up to the user to compare the new value to the old one and possibly only take action when there is a meaningful difference.
Callbacks are internally stored as a map from property name to a set of callbacks. Therefore, registering the same callback on the same property more than once will have no effect; the callback will only be called once for every property change.
Note that one-time callbacks registered with {once: true}
will generate
a new wrapper function that removes itself before calling the actual callback.
This has two implications:
Additionally, the listener
factory itself has the following method:
- listener.raw
- proxy → target
Note that callbacks will only trigger when the property is set via the proxy object. Changing the raw object directly will not trigger any callbacks as javascript provides no mechanism to detect such property changes on plain objects.