live.delete()
The live.delete() helper is a relatively low-level way to delete a live variable from its parent object, similar to the delete operator.
Instead of using live.delete() to delete a live variable from its parent object, consider instead using the traditional deletion syntax like delete $.key. The main use for live.delete() is when there is no reference to the parent object available, which happens mostly in custom utility functions.
Syntax
live.delete($live);
Parameters
- $live
- A live variable to delete from its parent object.
Return value
A boolean, indicating whether or not the deletion was successful, similar to how delete expressions evaluate to a boolean. If the $live argument is not live, false is returned. Likewise, if the live variable does not have a parent object (for example, when the value of the parent is null), then false is returned. Like delete, attempting to delete a non-configurable property also fails and returns false.
When the deletion is successful, live.delete() returns true.
Details
Deleting a live variable off the parent object does not add it or its parent to the monitored context of type "live", since the value is not read.
It is possible to delete the root variable, that is, the one created by a live() call. This variable has a parent, but it is entirely internal, and as such, deleting it is equivalent to setting its value to undefined. Since its deletion might be confusing, it is advised to use live.set() instead, explicitly setting it to undefined or null.
Examples
Resulting events
When deleting a key off of a parent object, both the value under that key changes (unless it was already undefined), but the parent also loses the key as per the Object.keys() function. To see this in action, consider the following:
const $object = live({ foo: 23, bar: 10 });
when($object).keychanges().then(() => {
console.log('keychange!');
});
when($object.$foo).changes().then(() => {
console.log('foo changed!');
});
live.delete($object.$foo); // "foo changed!" "keychange!"
We may also delete $object.foo, which is functionally identical and should be preferred for readability. However, when writing utility functions that need to delete a variable, but don't have a reference to the parent, live.delete() is the only way to delete a key off of the parent.
See also