@webqit/observer

    1.5.10 • Public • Published

    The Observer API

    NPM version NPM downloads

    Overview

    Take a one-minute rundown of the Observer API.

    Observe

    Observe operations on any object or array...

    let obj = {};

    ...using the Observer.observe() method.

    Observer.observe(obj, mutations => {
        mutations.forEach(mutation => {
            console.log(mutation.type, mutation.name, mutation.path, mutation.value, mutation.oldValue);
        });
    });

    Now changes will be delivered synchronously - as they happen.

    Mutate

    Programmatically make reactive changes using the Reflect-like set of operators...

    // A single set operation
    Observer.set(obj, 'prop1', 'value1');
    // A batch set operation
    Observer.set(obj, {
        prop2: 'value2',
        prop3: 'value3',
    });

    ...or switch to using object accessors - using the Observer.accessorize() method...

    // Accessorize all (existing) properties
    Observer.accessorize(obj);
    // Accessorize specific properties (existing or new)
    Observer.accessorize(obj, ['prop1', 'prop5', 'prop9']);
    // Make reactive operations
    obj.prop1 = 'value1';
    obj.prop5 = 'value5';
    obj.prop9 = 'value9';

    ...or even go with a reactive Proxy of your object, and imply properties on the fly.

    // Obtain a reactive Proxy
    let _obj = Observer.proxy(obj);
    // Make reactive operations
    _obj.prop1 = 'value1';
    _obj.prop4 = 'value4';
    _obj.prop8 = 'value8';

    And no problem if you inadvertently cascade the approaches. No bizzare behaviours.

    // Accessorized properties are already reactive
    Observer.accessorize(obj, ['prop1', 'prop6', 'prop10']);
    
    // But no problem if you inadvertently proxy an accessorized object
    let _obj = Observer.proxy(obj);
    
    // And yet no problem if you inadvertently made a programmatic call over an already reactive Proxy
    Observer.set(_obj, 'prop1', 'value1');

    Intercept

    How about some level of indirection - the ability to hook into operators like Observer.set() and Observer.deleteProperty() to repurpose their operation? That's all possible using the Observer.intercept() method!

    Below, we catch any attempt to set an HTTP URL and force it to an HTTPS URL.

    Observer.intercept(obj, 'set', (action, previous, next) => {
        if (action.name === 'url' && action.value.startsWith('http:')) {
            return next(action.value.replace('http:', 'https:'));
        }
        return next();
    });

    Now, only the first of the following will fly as-is.

    Observer.set(obj, 'url', 'https://webqit.io');
    Observer.set(obj, 'url', 'http://webqit.io');

    Pass Some Detail to Observers

    Operators, like Observer.set(), can pass arbitrary value to observers via a params.detail property.

    // A set operation with detail
    Observer.set(obj, {
        prop2: 'value2',
        prop3: 'value3',
    }, { detail: 'Certain detail' });

    Observers will recieve this value in a mutation.detail property.

    // An observer with detail
    Observer.observe(obj, 'prop1', mutation => {
        console.log('An operation has been made with detail:' + mutation.detail);
    });

    Negotiate with Observers

    Observers can access and act on a special object called the Response Object.

    // An observer and the response object
    Observer.observe(obj, 'prop1', (mutation, event) => {
        if (1) {
            event.preventDefault(); // Or return false
        } else if (2) {
            event.stopPropagation(); // Or return false
        } else if (3) {
            event.waitUntil(new Promise); // Or return new Promise
        }
    });

    Operators can access and honour the event's state.

    // A set operation that returns the eventTypeReturn
    let event = Observer.set(obj, {
        prop2: 'value2',
        prop3: 'value3',
    }, { eventTypeReturn: true });
    if (event.defaultPrevented) {
        // event.preventDefault() was called
    } else if (event.propagationStopped) {
        // event.stopPropagation() was called
    } else if (event.promises) {
        // event.waitUntil() was called
        event.promises.then(() => {
    
        });
    }

    Learn more about negotiation here

    Clean Up Anytime

    Need to undo certain bindings? There are the methods for that!

    The End?

    Certainly not! But this rundown should be a good start. Next:

    Issues

    To report bugs or request features, please submit an issue.

    License

    MIT.

    Install

    npm i @webqit/observer

    DownloadsWeekly Downloads

    150

    Version

    1.5.10

    License

    MIT

    Unpacked Size

    196 kB

    Total Files

    41

    Last publish

    Collaborators

    • avatar