# data-context
Watch data changes in the browser and node.js
## π Table of contents
- [β¨ Features](#-features)
- [π Description](#-description)
- [π¦ Installation](#-installation)
- [π§ͺ Testing](#-testing)
- [π Usage](#-usage)
- [π API Reference](#-api-reference)
- [π License - MIT](#-license)
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'](https://www.npmjs.com/package/data-context-binding) module gives very good results.
This module is part of the ['conextra'](https://www.npmjs.com/package/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](https://www.npmjs.com/package/data-context)
### nodejs:
```bash
npm install data-context
```
### browser:
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
### nodejs example:
```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);
```
### browser example:
```html
data-context
Example 'data-context'
Press F12. Console results.
```
## π API Reference
- [createDataContext(data, propertyName, parent)](#createdatacontextdata-propertyname-parent)
- [DataContext](#datacontext)
- [EventListener(event)](#eventlistenerevent)
- [EventObject](#eventobject)
- [PropertyName](#propertyname)
- [Reviver](#reviver)
Back to top β
### *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](#datacontext)} - The parent data context. Default is null.
**Returns:**
- {[DataContext](#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)) => [DataContext](#datacontext)} - Create a data context from the data.
- `parse` {(str: string, reviver?: [Reviver](#reviver)) => [DataContext](#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 β
---
### *DataContext*
The data context Proxy object.
**Type:** [`Proxy`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](#propertyname)>} - The array of modified properties.
- `_propertyName` {string} - The property name where the data is located. Default is null.
- `_parent` {[DataContext](#datacontext)} - The parent data context. Default is null.
- `_events` {Map} - 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](#propertyname), listener: [EventListener](#eventlistenerevent)) => void} - Add an event listener that will be called only once.
- `on` {(propertyName: [PropertyName](#propertyname), listener: [EventListener](#eventlistenerevent)) => void} - Add an event listener.
- `emit` {(eventName: string, event: [EventObject](#eventobject)) => void} - Emit an event.
- `emitToParent` {(eventName: string, event: [EventObject](#eventobject)) => void} - Emit an event to the parent.
- `toString` {() => string} - Returns the string representation of the data context.
- `overwritingData` {(text: string, reviver?: [Reviver](#reviver) ) => void} - Overwrite the data.
- `stringifyChanges` {(reviver?: [Reviver](#reviver), space?: number|string, onlyModified?: boolean, setUnmodified?: boolean) => string} - Stringify the changes.
Back to API Reference β
Back to top β
---
### *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 β
Back to top β
---
### *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 β
Back to top β
---
### *PropertyName*
The property name.
**Type:** `string`
Back to API Reference β
Back to top β
---
### *Reviver*
The reviver function.
**Type:** [`reviver`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse#reviver)
or [`createDataContext`](#createdatacontextdata-propertyname-parent) 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 β
---