cx-tag-engine v0.3.5

Tag Engine

Introduction

Tag Engine is a powerful library that facilitates the management of tags and their associated values. It provides functionalities for storing tag values in memory and LevelDB, as well as emitting events to notify subscribers when tag values are updated.

Features

• Support for storing tag values in memory and LevelDB.
• Event-driven architecture for emitting events to subscribers when tag values change.
• Ability to set and retrieve tag values programmatically.
• Support for asynchronous operations, allowing for seamless integration into Node.js applications.

Installation

You can install the Tag Engine library via npm:

npm install cx-tag-engine

Key Components

Tag

properties:

• group: a group where the tag belongs, also known as path of the tag;
• tagName: name of the tag;
• cached:
  • value: current value of the tag, accepts string | number | boolean | null;
  • prevValue: previous value of the tag;
  • ts: timestamp of the detected change, can be set by setter if detected externally; it would not change if forcedEmit is used;
  • prevTs: previous timestamp of the tag;
  • metadata: key/value persistent data;
• savePeriod: a number in milliseconds to check for a value change and save in the persistent database;
• tagStorage: a location of the persistent database;
• tagSaver: a method of saving the tag into persistent database;

Key Methods

Retrieves a tag by its group name and tag name.

static getTag(groupName: string, tagName: string): Tag | undefined

Sets a tag's value and returns the previous value.

static setTag(groupName: string, tagName: string, value: TagValue, ts = Date.now(), forceEmit = false): TagValue

setValue method:

setValue(value: TagValue, ts = Date.now(), forceEmit = false): boolean

1. sets value to memory if changed;
2. sets timestamp of the changed value at moment of the change detection;
3. passed ts argument used only when the change is detected by the external means, such as an edge device sending data over MQTT;
4. tracks the previous value and previous timestamp;
5. is able to emit the value without a change, known as forcedEmit. When forced no change to tag properties must be made. A isForced flag must be added when emitted by forcedEmit. The subscriber is responsible for creating a timestamp (if needed) when received a forced emit.

Tag Group

Key Methods

Gets an existing group or creates a new one.

static getOrCreateGroupByName(name: string): TagGroup

The constructor of TagGroup is private. This ensures that each group with the same name is a singleton, maintaining a single instance for every group name.

Subscribe to group creation and deletion.

static subGroupCreation(cb: (group: TagGroup) => void): () => void
static subGroupDeletion(cb: (group: TagGroup) => void): () => void

Subscribes to changes for all tags in the group

subAll(cb: (tags: Tag[], collection: TagCollection, forceMap: {[tagName: string]: boolean}) => void)

forceMap is a map of tags that were emitted by forcedEmit

Event emit

emit(tagName: string, tag: Tag, isForced = false)

1. Immediate individual updates: Each tag change is emitted immediately.
2. Efficient bulk updates: Multiple changes within the same event loop are batched together.
3. Debouncing: Rapid successive changes result in a single bulk update, reducing unnecessary processing.

Tag Saver

CheckTimeTagSaver

It saves tag values periodically based on tag's savePeriod Property.

The false value will not be saved to LevelDb when toggling a boolean in 250ms but the savePeriod of this tag is 1000ms.

Tag Server

This class is responsible for managing real-time tag subscriptions and updates using Socket.IO.

Authentication

If passwordProtected is true, the server uses JWT for authentication:

• Skips authentication for localhost connections
• Verifies JWT token and user agent
• Attaches decoded token data to the socket

Usage

To use the Tag Engine library in your Node.js application, you can import the necessary classes and functions as follows:

import { Tag, TagEngine } from 'cx-tag-engine';

// subscribe to tag updates
const group = TagGroup.getOrCreateGroupByName('group_1');
group.sub('voltage', (tag) => {
    console.log('voltage ' + tag.value);
});

// set tag value
Tag.set('group_1', 'voltage', 'tag value');

Tag UI

Tag UI is a web interface for managing tags. It can be initialized with an existing express app or a new express app. All tag groups and tags will be displayed in this web interface. And you can also delete tags and tag groups.

import { TagUI } from 'cx-tag-engine';
import bcryptjs from "bcryptjs";

TagUI.init(8080, [{ username: "admin", password: bcrypt.hashSync("admin") }], {
  origin: "*",
});; // Initialize the TagUI with new express app

TagUI.initWithExpress(app, server) // or existing express _app and server