data-context

Watch data changes in the browser and node.js

📚 Table of contents

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

Back to top ↑

---

✨ 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.

Back to top ↑

---

📋 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.

Back to top ↑

---

📦 Installation

Available on npm

$3

``bash
npm install data-context
`

$3

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

`
or use CDN (for a standalone HTML page):
`html

`
or use 'tiny-https-server':
`html

`

Back to top ↑

---

🧪 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

Back to top ↑

---

🚀 Usage

$3

`javascript
'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);
`

$3

`html

Example 'data-context'

Press F12. Console results.

`

📖 API Reference

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

Back to top ↑

$3

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 ↑

Back to top ↑

---

$3

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 {MapEventListener>} - 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 ↑

Back to top ↑

---

$3

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 ↑

Back to top ↑

---

$3

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 ↑

Back to top ↑

---

$3

The property name.

Type: string

Back to API Reference ↑

Back to top ↑

---

$3

The reviver function.

Type: reviver
or createDataContext or null`

Back to API Reference ↑

Back to top ↑

---

📜 License

This project is licensed under the MIT License.

Copyright © Manuel Lõhmus

Back to top ↑

---