dataws v1.0.0

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.

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

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
• resource
• property

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 complicated linked properties, some synergy with mongor is available

Ex//

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

SERVER - Node

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);

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

datawsServer.registerRoute([MESSAGE_TYPE], [PATH], [HANDLER])

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 (pathData, options, data) where the data parameter may be null depending on what type of message it is handling. pathData parameter is a javascript object containing the parsed information from the actual route sent to this handler. Note that this is relevant 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

datawsServer.notify([MESSAGE_TYPE], [PATH], [SOURCE], [OPTIONS])

Manually raise a NOTIFY event to all clients (except the source) so they can react to it and update their UI accordingly. This is essentially a pub/sub messaging format so there is no response and no requirement on the client side to listen or respond in any particular way Note that this event is AUTOMATICALLY generated by the DataWS server upon receiving valid UPDATE, CREATE, and DELETE messages. In this way all clients can remain in sync in 'real time' as long as they subscribe to and properly respond to the NOTIFY messages. Note that NOTIFY messages don't contain the data relevant to the event they are notifying about, just the notification and path SOURCE here is the socket that generated the action that the server is now notifying other clients about. The NOTIFY message will be sent to all clients except for SOURCE

CLIENT - 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('NOTIFY', (data) => [FUNCTION]);

Subscribe to NOTIFY events raised by the server
Data will be a javascript object containing the NOTIFY message data: path: PATH_DATA, MID: MID, data: { method: METHOD, source: source ? SOURCE_ID : null }, options: OPTIONS Note that when responding to the NOTIFY message, if the client wants to update something based on this notification, they will typically need to send an dataws.get(...) command to get the actual data, as NOTIFY messages don't contain the actual data relevant to the change being notified about

• 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

LAST UPDATE 2020/03/29 23:55 STAGE Initial Prototype

see this project in action at our website.