set.md

Observer.set()

This method is used to set the value of an object's property. It corresponds to the JavaScript's Reflect.set() function, which is itself the programmatic alternative to the assignment expression – obj.property = value.

Observer.set() brings the added benefit of triggering observers and interceptors.

• Syntax
• Usage
• Usage as a Trap's "set" Handler
• Usage with Property Setters
• Intercepting Observer.set()
• Related Methods

Syntax

// Set or modify a specific property
Observer.set(obj, propertyName, value);

// Set or modify a list of properties with the same value
Observer.set(obj, propertyNames, value);

// Perform multiple key/value assignments
Observer.set(obj, keyValueMap);

Parameters

• obj - an object or array.
• propertyNames/propertyName - the list of properties, or a property, to modify.
• value - the value to set.
• keyValueMap - an object of key/value pairs.

Return Value

Boolean

Usage

Assigning On a Specific Property

// On an object
Observer.set(obj, 'fruit', 'orange');
// On an array
Observer.set(arr, 0, 'orange');

Assigning On a List of Propertieskeys

// On an object
Observer.set(obj, ['fruit', 'brand'], 'apple');
// On an array
Observer.set(arr, [0, 3], 'apple');

Multiple Key/Value Assignment

// On an object
Observer.set(obj, {
    fruit:'apple',
    brand:'apple'
});

// On an array
// Provide key/value as an object
Observer.set(arr, {
    0:'apple',
    3:'apple'
});

Usage as a Trap's "set" Handler

Observer.set() can be used as the "set" handler in Proxy traps.

let _obj = new Proxy(obj, {set: Observer.set});
let _arr = new Proxy(arr, {set: Observer.set});

Assignment operations will now be forwarded to Observer.set() and observers and interceptors that may be bound to the object will continue to respond.

_obj.fruit = 'apple';
_arr[2] = 'Item 3';

Usage with Property Setters

It is possible to implement property setters that use Observer.set() behind the scene. This gives us the benefit of using JavaScript's assignment syntax while still driving observers and interceptors.

This is automatically done by the Observer.init() support function.

// Virtualize a property or multiple properties
Observer.init(obj, 'fruit');
Observer.init(obj, ['fruit', 'brand']);

// Now we can do without Observer.set
obj.fruit = 'apple';
obj.brand = 'apple';

We could follow the pattern above for arrays; we could even init an array's prototype methods instead. The specific keys modified after calling these methods will be announced to observers.

// Virtualize the arr.push() and arr.splice() methods
Observer.init(arr, ['push', 'splice']);

// Now we can do without Observer.set
arr.push('Item 1');
arr.push('Item 2');
arr.splice(1);

Intercepting Observer.set()

Using Observer.intercept(), it is possible to intercept calls to Observer.set(). When a "set" operation triggers an interceptor, the interceptor will receive an event object containing the property name and the assignable value.

Observer.intercept(obj, 'set', (event, recieved, next) => {
    // What we recieved...
    console.log(event.name, event.value);
    // The assignment operation
    obj[event.name] = event.value;
    // The return value - Boolean
    return true;
});

Observer.set(obj, 'fruit', 'orange');

When the "set" operation is of multiple key/value assignments, the interceptor gets fired for each pair while also recieving the total list of properties as a hint - via event.related.

Observer.intercept(obj, 'set', (event, recieved, next) => {
    // What we recieved...
    console.log(event.name, event.value, event.related);
    // The assignment operation
    obj[event.name] = event.value;
    // The return value - Boolean
    return true;
});

Observer.set(obj, {fruit: 'orange', brand:'apple'});

The above should trigger our interceptor twice with event.related being ['fruit', 'brand'].

The interceptor is expected to return true when the operation is successful; false otherwise.

Related Methods

• Observer.observe()
• Observer.intercept()