@vendedsolutions/dataws

DataWS

Data transport via WebSockets for data-centric web apps

DataWS facilitates communication related to data transfer between the browser and server using WebSocketsfor low-latency, low-overhead communication. This replaces and closely emulates traditional RESTful HTTP API architecture. The sibling browser library is available at dataws-browser. It currently relies on socket.io as the web socket communication abstraction, so that it can focus on its single purpose, to faciliate data-transfer communication between server-client.

Installation

npm install dataws

Basic Usage (node server)

Initialization typically follows this pattern:

1. Create HTTP Server
2. Use HTTP Server to initialize socket.io
3. Use socket.io to initialize DataWS
4. Register routes to handle incoming requests

const io = require("socket-io")(http);
const { DataWS } = require("./dataws/dataws.js");

datawsServer = new DataWS(io);

datawsServer.registerRoute({ ... })
datawsServer.registerRoute({ ... })
// ... etc 

Constructor

datawsServer = new DataWS(io);

Constructor. Initializes the DataWS class and will immediately begin accepting client connections

datawsServer.registerRoute([MESSAGE_TYPE], [PATH], [HANDLER])
// Example
datawsServer.registerRoute(MessageType.GET, 'data.accounts', (route, options, data) => { ... })

Used to register handler functions for GET, CREATE, UPDATE, and DELETE messages.

The [PATH] parameter requires a dot notation resource path targeting the collection (route) the server wants to expose an endpoint for

The [HANDLER] method follows format (route, options, data), described in the next section

Route Handler Function

• route parameter is a javascript object containing the parsed information from the actual route sent to this handler. This is essential because when registering a route handler, the server only targets a general collection route, within that handler it still needs to be aware of the [ID] and [PROPERTY] elements of the Path, if present
• options parameter is used for application-specific options associated with the request. This may be complex depending on the requirements of the server, or unused entirely
• data parameter contains the requested data for GET messages, and null depending for other messages

// Example 'route' data object when the client's dot notation path is core.accounts[12a87bd35f12fa937].name
{
    nodes: ['core', 'accounts'],
    targetType: 'PROPERTY',
    collection: 'accounts',
    collectionPath: 'core.accounts',
    id: '12a87bd35f12fa937',
    property: 'name',
    raw: 'core.accounts[12a87bd35f12fa937]'
}

Dot Notation Resource Path

Instead of using URLs to identify data locations, DataWS uses Dot Notation Resource Paths alongside JSON data to provide all the necessary information to communicate requests across WebSockets. These Paths can point to three different types of targets:

• collection Essentially a MongoDB 'collection' or a SQL 'table', technically can be used as a more broad definition of grouped data that can handle CRUD operations

• resource This targets a specific data 'object' or 'row', more broadly a specific piece of data identified by the collection alongside an id

• property Targets a specific 'property' or 'value' on a RESOURCE within a COLLECTION. Basic concept is to limit packet size when we are only interested in a single property of a resource so we don't have to pull the whole object from the server. Second use case is when pulling referentially linked properties, if supported by the server and database architecture

Examples

• collection core.accounts
• resource core.accounts[1b121b]
• property core.accounts[1b121b].permissionSet

The initial collection path that is present on all valid Paths can be considered flexible. It could closely match a URL structure like in a RESTful style API, or be used to query data across multiple data sources such as a MongoDB collection at core.[COLLECTION], a SQL table at sql.[TABLE] or even a more abstract data source like clientSource.[CLIENT_ID].files[FILE_UID] for more real-time type data sources

Keep in mind the purpose of DataWS is to only facilitate the data flow across web sockets, the server can implement handlers in a variety of structures, and the client simply sends requests and responds to NOTIFY messages to update the UI

Client Usage (note the browser library is in a different repo, dataws-browser)

Initialization typically follows this pattern:

import { DataWSClient } from "./dataws.js";
let engine = io();

let dataws = DataWSClient(engine);

Constructor. Initializes the DataWSClient object using the socket.io engine object. It will immediately attempt connection to the server using WebSockets

dataws.on(MessageType.NOTIFY, (data) => { ... });

• Subscribe to NOTIFY events raised by the server
• Data will be a javascript object containing the NOTIFY message data:

// Example
{
    path: { ... }, // pathData object as described above
    MID: 1234,
    data: { method: 'DELETE', source: { ... } },
    options: { ... }
}

dataws.get(collectionRoute, id, property = null, options = {}) dataws.create(collectionRoute, data, options) dataws.update(collectionRoute, id, data, property = null, options = {}) dataws.delete(collectionRoute, id, options = {})

The above functions operate pretty much how you would expect them to, similar to RESTful structure, but keeping in mind this module is only responsible for communicating the messages themselves, not the implementation (handlers) of their intent

collectionRoute is a string containing the dot notation resource path pointing to the collection of interest, the id and property fields are automatically appended to the dot notation path so the client code doesn't need to do the string concatenation themselves.

These functions all return Promise objects as expected in the ES6 world

See dataws.js inline documentation on server and client sections for more information