data-context

Watch data changes in the browser and node.js

📚 Table of contents

✨ Features
📋 Description
📦 Installation
🧪 Testing
🚀 Usage
📖 API Reference
📜 License

✨ Features

Create a context from the data.
Listen for change events.
Update the context.
Parse JSON data to the context.
Stringify changes to JSON.
Used extended JSON data format. Metadata and comments are supported.

📋 Description

The 'data-context' module provides a way to create a data context that can watch for changes in the data.

It is a simple and easy-to-use library that can be used in the browser or in node.js. You can create a context from the data, then listen for change events and stringify changes. Included event-emitter functions. Automatically detects changes in the data and emits events. Designed for module 'data-context-binding' for binding data to the DOM and for module 'fs-broker' for working with files. Using a single-page application (SPA) with the 'data-context-binding' module gives very good results. This module is part of the 'conextra' framework, which is a simple and easy-to-use single-page application (SPA) framework. You have to try it! A different solution than MVC (model–view–controller).

Please note, this version is not backward compatible with version 1.x
Please note that JSON string is not 100% compatible.
It has been extended to allow for incremental updates of JSON files.
Added the ability to include metadata and comments.
Parsing of JSON files is enabled.

The code in 'data-context' provides a robust mechanism for creating data contexts that can track changes, emit events, and support serialization/deserialization. It leverages JavaScript proxies to intercept and manage property operations, making it a powerful tool for managing state in complex applications.

The data context library implemented in 'data-context' can be used in various scenarios where tracking changes to data, emitting events, and managing state are essential. Here are some potential use cases:

1. State Management in Single Page Applications (SPAs)

Description: Manage the state of an application by creating data contexts for different parts of the state.
Example: Use the library to track changes in user data, application settings, or UI state, and automatically update the UI when changes occur.

2. Data Binding

Description: Bind data to the DOM and automatically update the DOM when the data changes.
Example: Use the library in conjunction with a data-binding library like data-context-binding to create dynamic and responsive web applications.

3. Form Handling

Description: Track changes to form inputs and validate data in real-time.
Example: Create a data context for form data, listen for changes to input fields, and validate the data or provide instant feedback to the user.

4. Real-time Collaboration

Description: Enable real-time collaboration features by synchronizing data changes across multiple clients.
Example: Use the library to track changes to a shared document or project, and emit events to notify other clients of the changes.

5. Undo/Redo Functionality

Description: Implement undo and redo functionality by tracking changes to data and allowing users to revert to previous states.
Example: Use the library to maintain a history of changes and provide undo/redo capabilities in applications like text editors or drawing tools.

6. Data Synchronization

Description: Synchronize data between different parts of an application or between client and server.
Example: Use the library to track changes to local data and synchronize those changes with a remote server or other clients.

7. Configuration Management

Description: Manage application configuration settings and track changes to those settings.
Example: Create a data context for configuration settings, listen for changes, and update the application behavior accordingly.

8. Logging and Auditing

Description: Log changes to data for auditing purposes.
Example: Use the library to track changes to sensitive data and log those changes for security audits or compliance purposes.

9. Testing and Debugging

Description: Facilitate testing and debugging by tracking changes to data and emitting events.
Example: Use the library to create test cases that verify the correct behavior of data changes and event emissions.

10. Incremental JSON Updates

Description: Handle incremental updates to JSON data, including metadata and comments.
Example: Use the library to parse, modify, and serialize JSON data with support for incremental updates and metadata.

📦 Installation

Available on npm

nodejs:

npm install data-context

browser:

or use CDN (for an HTML page hosted on the server):

<script src="./node_modules/data-context/borwser.js" type="text/javascript"></script>

or use CDN (for a standalone HTML page):

<script src="https://cdn.jsdelivr.net/npm/data-context" type="text/javascript"></script>

or use 'tiny-https-server':

<script async src="node_modules/data-context@2"></script>

🧪 Testing

You can test data-context on your system using this command:

node ./node_modules/data-context/index.test

or in the data-context project directory:

npm test

or open in your browser:

./node_modules/data-context/index.test.html

🚀 Usage

nodejs example:

'use strict';

//Import the required modules.
const { createDataContext, parse } = require('data-context');
//import { createDataContext, parse } from "data-context";

//Create a JSON string.
var strJSON = `{
    "count": 0
}`;

//Interval id.
var intervalId = null;

//Create data context.
const context = parse(
    //Parse the JSON string.
    strJSON,
    //Reviver function. Create data context.
    createDataContext
);

//Listen to the count property.
context.on('count', (event) => {

    console.log('event:', event);

    if (event.newValue > 10) {

        console.log('I am dead.');
        clearInterval(intervalId);

        //I am dead. Remove listener.
        return false;
    }

    //I am live. Continue listening.
    return true;
});

context.on('-change', (event) => {

    //Stringify the changes.
    var str = context.stringifyChanges(
        //Reviver function. Default is null.
        null,
        //Indentation. Default is 0.
        4,
        //Include only modified data. Default is true.
        true,
        //Set data to unmodified after stringification. Default is true.
        true
    );
    console.log('changes:', str);

    //I am live. Continue listening.
    return true;
});

//Start the interval.
intervalId = setInterval(() => {

    //Increment the count property.
    context.count++;
}, 1000);

browser example:

<!DOCTYPE html>
<html>
<head>
    <meta charset="utf-8" />
    <title>data-context</title>
    <!-- STEP 1. Import the module. Import for an HTML page hosted on the server. -->
    <script type="text/javascript" src="./index.js"></script>
    <!-- STEP 1. Import the module. Import for a standalone HTML page. -->
    <!--<script src="https://cdn.jsdelivr.net/npm/data-context"></script>-->
    <script>

        'use strict';

        // STEP 3. Import the module.
        importModules(['data-context'], function (DC) {

            var { createDataContext, parse } = DC;

            //Create a JSON string.
            var strJSON = `{
                "count": 0
            }`;

            //Interval id.
            var intervalId = null;

            //Create data context.
            const context = parse(
                //Parse the JSON string.
                strJSON,
                //Reviver function. Create data context.
                createDataContext
            );

            //Listen to the count property.
            context.on('count', (event) => {

                console.log('event:', event);

                if (event.newValue > 10) {

                    console.log('I am dead.');
                    clearInterval(intervalId);

                    //I am dead. Remove listener.
                    return false;
                }

                //I am live. Continue listening.
                return true;
            });

            context.on('-change', (event) => {

                //Stringify the changes.
                var str = context.stringifyChanges(
                    //Reviver function. Default is null.
                    null,
                    //Indentation. Default is 0.
                    4,
                    //Include only modified data. Default is true.
                    true,
                    //Set data to unmodified after stringification. Default is true.
                    true
                );
                console.log('changes:', str);

                //I am live. Continue listening.
                return true;
            });

            //Start the interval.
            intervalId = setInterval(() => {

                //Increment the count property.
                context.count++;
            }, 1000);
        });

        // STEP 2. Add module import function.
        /**
         * Module import function.
         * @param {string[]} importIdentifierArray Modules to import.
         * @param {(...importModules:any[]) => void} callback Callback function.
         */
        function importModules(importIdentifierArray, callback) {

            var thisScope = "undefined" != typeof globalThis
                ? globalThis
                : "undefined" != typeof window
                    ? window
                    : "undefined" != typeof global
                        ? global : "undefined" != typeof self
                            ? self
                            : {};

            if (!thisScope.modules) { thisScope.modules = {}; }

            waitModules();


            function waitModules() {

                if (importIdentifierArray.length) {

                    for (let i = 0; i < importIdentifierArray.length; i++) {

                        if (!thisScope.modules[importIdentifierArray[i]]) { return setTimeout(waitModules, 10); }
                    }
                }

                callback.call(thisScope, ...importIdentifierArray.map(function (id) { return thisScope.modules[id]; }));
            }
        }
    </script>
</head>
<body>
    <h3>Example 'data-context'</h3>
    <p>Press F12. Console results.</p>
</body>
</html>

📖 API Reference

createDataContext(data, propertyName, parent)
DataContext
EventListener(event)
EventObject
PropertyName
Reviver

createDataContext(data, propertyName, parent)

Create a data context from the data.

Type: function

Parameters:

data {any} - The data object.
propertyName {string} - The property name where the data is located. Default is null.
parent {DataContext} - The parent data context. Default is null.

Returns:

{DataContext} - The data context.

Static Properties:

ignoreMetadata {boolean} - Global flag to ignore metadata and comments. Default is false.
createDataContext {(data: any, propertyName?: string, parent?: DataContext) => DataContext} - Create a data context from the data.
parse {(str: string, reviver?: Reviver) => DataContext} - Parse JSON string to the data context.
stringify {(data: any, replacer?: Replacer, space?: number) => string} - Stringify the data to JSON string.

Back to API Reference ↑

DataContext

The data context Proxy object.

Type: Proxy

Properties:

_isDataContext {boolean} - The flag that indicates that the object is a data context. Default is true.
_isModified {boolean} - The flag that indicates that the object is modified. Default is false.
_modified {Array<PropertyName>} - The array of modified properties.
_propertyName {string} - The property name where the data is located. Default is null.
_parent {DataContext} - The parent data context. Default is null.
_events {Map<string, EventListener>} - The map of event listeners.
isChanged {boolean} - The flag that indicates that the object is changed.

Methods:

resetChanges {() => void} - Set the current and child objects to status - unmodified. Must be used to start tracking changes again.
once {(propertyName: PropertyName, listener: EventListener) => void} - Add an event listener that will be called only once.
on {(propertyName: PropertyName, listener: EventListener) => void} - Add an event listener.
emit {(eventName: string, event: EventObject) => void} - Emit an event.
emitToParent {(eventName: string, event: EventObject) => void} - Emit an event to the parent.
toString {() => string} - Returns the string representation of the data context.
overwritingData {(text: string, reviver?: Reviver ) => void} - Overwrite the data.
stringifyChanges {(reviver?: Reviver, space?: number|string, onlyModified?: boolean, setUnmodified?: boolean) => string} - Stringify the changes.

Back to API Reference ↑

EventListener(event)

The event listener function.

Type: function

Parameters:

event {EventObject} - The event object.

Returns:

{boolean} - The flag that indicates that the listener is alive.

Back to API Reference ↑

EventObject

The event object.

Type: object

Properties:

eventName {string} - The event name. 'new' | 'set' | 'delete' | 'reposition' | '-change'
- 'new' It happens when a new property is added to the data context.
- 'set' It happens when an existing property is updated.
- 'delete' It happens when a property is removed from the data context.
- 'reposition' It happens when the position of an item in an array changes.
- 'change' It happens when any change occurs in the data context.
target {DataContext} - The target data context.
propertyPath {Array} - The property path in array format.
parent {DataContext} - The parent data context.
oldValue {any} - The old value.
newValue {any} - The new value.

Back to API Reference ↑

PropertyName

The property name.

Type: string

Back to API Reference ↑

Reviver

The reviver function.

Type: reviver or createDataContext or null

Back to API Reference ↑

data-context

📚 Table of contents

✨ Features

📋 Description

📦 Installation

nodejs:

browser:

🧪 Testing

🚀 Usage

nodejs example:

browser example:

📖 API Reference

createDataContext(data, propertyName, parent)

DataContext

EventListener(event)

EventObject

PropertyName

Reviver

📜 License