@mdaemon/observable, A function for observing values

The observable function provides methods for setting, getting, observing, and stopping observation of any of the following value types: object, array, boolean, string, and number.

Install

$ npm install @mdaemon/observable --save

Node.js (CommonJS)

    // Resolves via the "exports" field in package.json
    const observe = require("@mdaemon/observable");

    // Or load the explicit CJS build
    const observe = require("@mdaemon/observable/dist/observable.cjs");

Node.js / Bundler (ES Modules)

    import observe from "@mdaemon/observable";

    // Or load the explicit ESM build
    import observe from "@mdaemon/observable/dist/observable.mjs";

Note: Bundlers (Rollup, webpack, Vite, etc.) and Node.js resolve the exports field in package.json and will use the appropriate build automatically.

Browser (UMD)

    <script src="/path_to_modules/@mdaemon/observable/dist/observable.umd.js"></script>
    <script>
      // The library is exposed as the global variable `observable`
      const observe = window.observable;
    </script>

observe

You can use observe to keep track of a value from multiple contexts

Export observables

    import observe from "@mdaemon/observable/dist/observable.mjs";

    // observeTheseValues.js
    const observedNumber = observe("numberName", 20);
    export observedNumber;

    // note that objects are clones, so this object will not be changed by changes to the observedObject
    const obj = {};
    const observedObject = observe("objectName", obj);
    export observedObject;

    const observedArray = observe("arrayName", []);
    export observedArray;

    const observedBoolean = observe("boolName", true);
    export observedBoolean;

    const observedString = observe("stringName","test");
    export observedString;

Import observables

    // index.js
    import { 
        observedNumber, observedObject, 
        observedArray, observedBoolean, 
        observedString 
    } from "observeTheseValues.js";

    // change the value and return changed true/false
    let changed = observedNumber(30);
    console.log(changed); // true

    console.log(observedNumber(30)); // false
    
    // get the value
    console.log(observedNumber() === 30); // true

    // watch for value changes
    const stopObservingValue = observedNumber((newValue, oldValue) => {
      console.log("new", newValue);
      console.log("old", oldValue);
      console.log(newValue === oldValue);
    });

    // change the value for observation
    observedNumber(3);
    // new 3
    // old 30
    // false

    // stop observing changes
    stopObservingValue();

    // change the value again
    observedNumber(60); // nothing logged

    // observe also finds changes that are part of objects
    const stopObservingObject = observedObject((newValue, oldValue) => {
      console.log("new", newValue);
    });

    console.log(observedObject({ test: 10 })); // true
    // { test: 10 }

    // to remove a property from an object, set it to undefined
    observedObject({ test: undefined });
    // { }

    // from 2.0 you can also get an already observed value using the name of the value passed to the original

    const str = observe("stringName");

    console.log(str()); // "test"
    

Destroying an Observable

You can destroy an observable instance by passing a special string to the observe function. This will remove the observable from the internal list, allowing it to be garbage collected if there are no other references to it.

    // Destroy the observable instance
    str("destroy-observable-stringName");

    // Attempting to get the value of the destroyed observable will now return undefined
    const str = observe("stringName");
    console.log(str()); // undefined

License

Published under the LGPL-2.1 license.

Changelog

See CHANGELOG.md for release history.

Published by MDaemon Technologies, Ltd. Simple Secure Email https://www.mdaemon.com