ws-realtime API Documentation

Overview

The ws-realtime API provides a WebSocket-based system for real-time data updates. Clients can subscribe to specific datamodels and receive notifications when data changes. The library is designed for use in scenarios such as real-time dashboards and event-driven applications.

Installation

To install the library via NPM:

npm install ws-realtime-backend

WebSocket Server Initialization

The WebSocket server manages client connections and handles communication between the clients and the server.

initWebSocketServer(port, route) Initializes the WebSocket server on the specified port and route.

Arguments:

1. port (number): The port on which the WebSocket server will listen.
2. route (string): The WebSocket route or endpoint.

Example:

const { initWebSocketServer } = require('ws-realtime');

const port = 3002;
const route = '/realtime';

initWebSocketServer(port, route);

Datamodel Initialization

Datamodels represent the data structures that clients can subscribe to for real-time updates. Each datamodel is associated with a source, such as a database or an in-memory state.

initializeDatamodels(models) Initializes the datamodels based on the provided object. Each datamodel should be defined in a ${name}.datamodel.js file.

Arguments:

1. models (object): An object containing datamodel declarations.

Example:

const { initializeDatamodels } = require('ws-realtime');

const models = {
  Chargers: require('./datamodels/Chargers.datamodel'),
  Connectors: require('./datamodels/Connectors.datamodel')
};

initializeDatamodels(models);

Source Initialization and Event Handling

Sources represent the origins of data, such as databases or state management systems. The API allows you to emit and listen to events related to changes in the data.

initializeSources(sources) Initializes event listeners for the specified sources. Each source should correspond to a system that manages a datamodel (e.g., a database).

Arguments:

1. sources (array): An array of source names as strings.

Example:

const { initializeSources } = require('ws-realtime');

const sources = ['database', 'state'];


initializeSources(sources);

EventEmitter Functions

emitEvent(source, event, ...args) Emits an event for a specific datamodel or source.

Arguments:

1. source (string): The name of the source emitting the event
2. event (string): The name of the event.
3. ...args: Additional arguments passed to the event.

Example:

const { emitEvent } = require('ws-realtime');

// Emit a 'Create' event for the 'Chargers' datamodel
emitEvent('database', 'Create', 'Chargers', 5152, {
  ChargerID: '5152',
  Connected: true
});

onEvent(event, listener)

Adds an event listener for a specific event.

Arguments:

1. event (string): The name of the event to listen for.
2. listener (function): A callback function that will be invoked when the event is emitted.

Example:

const { onEvent, emitEvent } = require('ws-realtime');

function initializeDatabaseSource() {
  // Listen for 'requestInitialData' events
  onEvent('requestInitialData', async (datamodel, clientUUID) => {
    try {
      // Retrieve Sequelize models
      const models = getModels();
      const model = models[datamodel];

      if (model) {
        // Fetch all entries from the database for the requested datamodel
        const entries = await model.findAll();
        const data = {};

        // Format the entries to send to the client
        entries.forEach(entry => {
          const primaryKey = entry[model.primaryKeyAttribute];
          data[primaryKey] = entry.toJSON();
        });

        // Emit 'provideInitialData' to send the data back to the client
        emitEvent('provideInitialData', datamodel, clientUUID, data);
      } else {
        console.error(`Model ${datamodel} not found.`);
      }
    } catch (error) {
      console.error(`Error fetching initial data for ${datamodel}:`, error);
      // Optionally, send an error to the client
      // emitEvent('initialDataError', datamodel, clientUUID, error.message);
    }
  });

  console.log('Database source initialized and listening for initial data requests.');
}

The above example demonstrates the requestInitialData event listener, and how it should be handled.

Valid Events:

Currently, onEvent only has the following valid events that it can receive:

1. requestInitialData (event): Passes the datamodel and clientUUID values. Event that requests all entries within a given Datamodel be sent to the given clientUUID. Used for passing the 'intial' data to a client. Typically followed by an emitEvent('provideInitialData') emitter.

Declaration of requestInitialData:

Ideally, the onEvent('requestInitialData') listener is implemented within a source declaration, named as ${source name}.source.js. This file should, at the very least, declare a listener for the requestInitialData that reciprocates the given Datamodel to the provideInitialData emitEvent function. This listener function/source file should be initialized before the initWebSocketServer initialization function is called.

Accessing Internal Maps

The library maintains three main Maps: uuidToWSMap, uuidToObjectMap, and datamodelToObjectMap. These Maps track WebSocket connections, client subscriptions, and datamodel information.

getWebSocket(uuid)

Retrieves the WebSocket object associated with a specific UUID.

Arguments:

1. uuid (string): The UUID of the client.

Example:

const { getWebSocket } = require('ws-realtime');

const ws = getWebSocket('client-uuid');

getClientSubscriptions(uuid)

Retrieves the list of datamodels a client is subscribed to.

Arguments:

1. uuid (string): The UUID of the client.

Example:

const { getClientSubscriptions } = require('ws-realtime');

const subscriptions = getClientSubscriptions('client-uuid');
console.log(subscriptions); // Output: { datamodels: ['Chargers', 'Connectors'] }

getDatamodelInfo(datamodel)

Retrieves metadata about a specific datamodel.

Arguments:

1. datamodel (string): The name of the datamodel.

Example:

const { getDatamodelInfo } = require('ws-realtime');

const datamodelInfo = getDatamodelInfo('Chargers');
console.log(datamodelInfo);

getAllDatamodels()

Retrieves an array of all registered datamodels.

Example:

const { getAllDatamodels } = require('ws-realtime');

const datamodels = getAllDatamodels();
console.log(datamodels); // Output: ['Chargers', 'Connectors']

Event-Handling Conventions

ICUD Events

The system sends and receives ICUD (Initial, Create, Update, Delete) messages for changes in datamodels. These events trigger updates to clients subscribed to specific datamodels.

Example of a Create Event:

emitEvent('Create', 'Chargers', '5152', {
  ChargerID: '5152',
  Connected: true,
  connectors: 3,
  OCPP_version: '1.6'
});

Event Listener Example:

onEvent('Create', (modelName, primaryKey, data) => {
  console.log(`New entry added to ${modelName}:`, data);
});

Message Structure

For each event, the following message structure is used:

{
  "Chargers": [
    {
      "mode": "Create",
      "data": {
        "5152": {
          "ChargerID": "5152",
          "Connected": true,
          "connectors": 3,
          "OCPP_version": "1.6"
        }
      }
    }
  ]
}

Conclusion

This documentation covers all of the publicly accessible functions and variables provided by the ws-realtime API.

Final Thoughts

The Public.md documentation now provides comprehensive and structured information about the ws-realtime API. It covers all publicly available functions, examples, and conventions, making it easy for developers to use the library in their own projects.