Introduction

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.

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.

Installation

nodejs:

npm install data-context

browser:

<script src="https://cdn.jsdelivr.net/npm/data-context@2" ></script>

Using tiny-https-server router:

or use 'tiny-https-server' router: <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:

1'use strict';
2
3//Import the required modules.
4const { createDataContext, parse } = require('data-context');
5//import { createDataContext, parse } from "data-context";
6
7//Create a JSON string.
8var strJSON = `{
9    "count": 0
10}`;
11
12//Interval id.
13var intervalId = null;
14
15//Create data context.
16const context = parse(
17    //Parse the JSON string.
18    strJSON,
19    //Reviver function. Create data context.
20    createDataContext
21);
22
23//Listen to the count property.
24context.on('count', (event) => {
25
26    console.log('event:', event);
27
28    if (event.newValue > 10) {
29
30        console.log('I am dead.');
31        clearInterval(intervalId);
32
33        //I am dead. Remove listener.
34        return false;
35    }
36
37    //I am live. Continue listening.
38    return true;
39});
40
41context.on('-change', (event) => {
42
43    //Stringify the changes.
44    var str = context.stringifyChanges(
45        //Reviver function. Default is null.
46        null,
47        //Indentation. Default is 0.
48        4,
49        //Include only modified data. Default is true.
50        true,
51        //Set data to unmodified after stringification. Default is true.
52        true
53    );
54    console.log('changes:', str);
55
56    //I am live. Continue listening.
57    return true;
58});
59
60//Start the interval.
61intervalId = setInterval(() => {
62
63    //Increment the count property.
64    context.count++;
65}, 1000);

browser example:

1<!DOCTYPE html>
2<html>
3<head>
4    <meta charset="utf-8" />
5    <title>data-context</title>
6    <!-- STEP 1. Import the module. Import for an HTML page hosted on the server. -->
7    <script type="text/javascript" src="./index.js"></script>
8    <!-- STEP 1. Import the module. Import for a standalone HTML page. -->
9    <!--<script src="https://cdn.jsdelivr.net/npm/data-context"></script>-->
10    <script>
11
12        'use strict';
13
14        // STEP 3. Import the module.
15        importModules(['data-context'], function (DC) {
16
17            var { createDataContext, parse } = DC;
18
19            //Create a JSON string.
20            var strJSON = `{
21                "count": 0
22            }`;
23
24            //Interval id.
25            var intervalId = null;
26
27            //Create data context.
28            const context = parse(
29                //Parse the JSON string.
30                strJSON,
31                //Reviver function. Create data context.
32                createDataContext
33            );
34
35            //Listen to the count property.
36            context.on('count', (event) => {
37
38                console.log('event:', event);
39
40                if (event.newValue > 10) {
41
42                    console.log('I am dead.');
43                    clearInterval(intervalId);
44
45                    //I am dead. Remove listener.
46                    return false;
47                }
48
49                //I am live. Continue listening.
50                return true;
51            });
52
53            context.on('-change', (event) => {
54
55                //Stringify the changes.
56                var str = context.stringifyChanges(
57                    //Reviver function. Default is null.
58                    null,
59                    //Indentation. Default is 0.
60                    4,
61                    //Include only modified data. Default is true.
62                    true,
63                    //Set data to unmodified after stringification. Default is true.
64                    true
65                );
66                console.log('changes:', str);
67
68                //I am live. Continue listening.
69                return true;
70            });
71
72            //Start the interval.
73            intervalId = setInterval(() => {
74
75                //Increment the count property.
76                context.count++;
77            }, 1000);
78        });
79
80        // STEP 2. Add module import function.
81        /**
82         * Module import function.
83         * @param {string[]} importIdentifierArray Modules to import.
84         * @param {(...importModules:any[]) => void} callback Callback function.
85         */
86        function importModules(importIdentifierArray, callback) {
87
88            var thisScope = "undefined" != typeof globalThis
89                ? globalThis
90                : "undefined" != typeof window
91                    ? window
92                    : "undefined" != typeof global
93                        ? global : "undefined" != typeof self
94                            ? self
95                            : {};
96
97            if (!thisScope.modules) { thisScope.modules = {}; }
98
99            waitModules();
100
101
102            function waitModules() {
103
104                if (importIdentifierArray.length) {
105
106                    for (let i = 0; i < importIdentifierArray.length; i++) {
107
108                        if (!thisScope.modules[importIdentifierArray[i]]) { return setTimeout(waitModules, 10); }
109                    }
110                }
111
112                callback.call(thisScope, ...importIdentifierArray.map(function (id) { return thisScope.modules[id]; }));
113            }
114        }
115    </script>
116</head>
117<body>
118    <h3>Example 'data-context'</h3>
119    <p>Press F12. Console results.</p>
120</body>
121</html>

References

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.

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.

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.

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.

PropertyName

The property name.

Type: string

Reviver

The reviver function.

Type: reviver or createDataContext or null

License

This project is licensed under the MIT License.

Copyright © Manuel Lõhmus

Donations are welcome and will go towards further development of this project.