wson-event-connector
WSON is a human-readable data-interchange format with support for cyclic structures. This module is an extension to wson that enables serializing DOM events to strings and parsing those strings back to DOM events.
Possible Use Cases
- Record DOM events to later simulate a user during automated test
(needs
wson-dom-connector), - Log DOM events just for debugging.
Installation
npm install --save wson wson-event-connectorUsage
It can be used in a web browser via browserify...
var WSON = require("wson").Wson;
var eventConnectors = require("wson-event-connector");
var wson = new WSON({
connectors: eventConnectors(window)
});
function logEvent(e) {
console.log(wson.stringify(e));
}
var events = [ 'load', 'error', 'focus', 'blur', 'resize', 'scroll', 'unload' ];
events.forEach(function(name) {
window.addEventListener(name, logEvent);
});...or in node with any standard-compliant DOM implementation (e.g. jsdom).
var WSON = require("wson").Wson;
var eventConnectors = require("wson-event-connector");
var domConnectors = require("wson-dom-connector");
var jsdom = require("jsdom");
var _ = require("underscore");
var window = jsdom.jsdom("<body></body>").defaultView;
var wson = new WSON({
connectors: _.extend(eventConnectors(window), domConnectors(window))
});
var body = window.document.body;
body.addEventListener('click', function(event) {
console.log(wson.stringify(event)));
}
body.dispatchEvent(new window.MouseEvent('click', {
screenX: 300,
screenY: 400,
clientX: 20,
clientY: 10,
button: 1,
buttons: 1,
});
// [:MouseEvent|click|#f|#f|#0|#0|#300|#400|#20|#10|#1|#1|#n|#n|[:HTMLBodyElement|/body`a1`e]]Above example uses connectors from wson-dom-connector module to serialize DOM nodes assigned to event properties.
Supported Events
Following events types are currently supported:
(Not Yet) Supported Events
Near future should bring support for following classes:
DragEventDeviceOrientationEventDeviceMotionEventErrorEventGamepadEventIDBVersionChangeEventProgressEventSensorReadingEventStorageEvent
Feel free to message me if you desperately need one of above.
Pull requests are also very welcome!
CONTRIBUTING GUIDELINES:
Please do not submit pull requests implementing non-standard vendor-specific events. For those, a separate module should be created (e.g.
wson-mozilla-connector), with this module as dependency (see API Reference).
Unsupported Events
Serialization of following event classes will not be implemented in this module:
-
BlobEvent, becauseBlob's content can't be fetched from JavaScript, - Websockets-related events (
MessageEvent,CloseEvent). - RTC-related events (
RTCPeerConnectionIceEvent,RTCPeerConnectionIceErrorEvent,RTCTrackEvent,RTCDataChannelEvent,RTCDTMFToneChangeEvent), - Service-workers-related event (
FetchEvent,ExtendableEvent,ExtendableMessageEvent). - Web-Audio-related events (
AudioProcessEvent,AudioWorkerNodeCreationEvent,OfflineAudioCompletionEvent), - SVG-related events (
TimeEvent,SVGZoomEvent), - WebGL-related events (
WebGLContextEvent).
Why are some properties not serialized?
Following properties are by default not serialized:
-
Event.defaultPrevented, because initial value of this property is alwaystrue(Event.preventDefault()called inside an event listener changes it tofalse). The whole point of event serialization is to be able to dispatch them on another instance of window containing the same HTML document. Properties need to be in initial (pre-dispatch) value for event listeners to work properly. - Properties, which contain meta-information about event and current
state of its propagation (
Event.currentTarget,Event.eventPhase,Event.timeStamp,Event.isTrusted). Values of these properties are changed by the browser during event dispatch and they cannot are be set from JavaScript. -
UIEvent.sourceCapabilities, because it's just ridiculous to pass the same information in each event. - Properties containing DOM nodes or Window instances
(
Event.target,UIEvent.view,MouseEvent.relatedTarget,Touch.target) are serialized when wson is created with connectors from wson-dom-connector module.
API Reference
This document describes API exported by this (wson-event-connector) module.
Please refer to wson's documentation for description of wson's API
and serialization algorithm.
All Connectors
exports = function(window, additionalFields = []) { ... }Creates WSON connectors for all event classes found in window namespace.
Created connectors will be extended to serialize fields passed
in additionalFields array. Function returns a map
(event class name => connector instance), which can be passed
as "connectors" option to WSON's constructor (see example below).
var WSON = require('wson').Wson;
var eventConnectors = require('wson-event-connector');
var wson = new WSON({ connectors: eventConnectors(window) });Event Connector
exports.Event = function(EventClass, additionalFields = []) { ... }Constructs a connector which is able to serialize instances of EventClass.
Passed class must be derived from or equal window.Event.
Returned connector serializes fields in following order: Event.bubbles,
Event.cancelable, additionalFields..., Event.target.
Event.target is not settable from JavaScript. Web browsers assign
its value inside EventTarget.dispatchEvent(event).
Events returned from wson.parse(string) are not yet dispatched, hence they
do not have Event.target set. Instead, target is deserialized into
non-standard Event.parsedTarget property (see example below).
var WSON = require('wson').Wson;
var eventConnectors = require('wson-event-connector');
var domConnectors = require('wson-dom-connector');
var wson = new WSON({ connectors: {
'Event': eventConnectors.Event(window.Event),
'HTMLBodyElement': domConnectors(window).HTMLBodyElement,
}});
var event = wson.parse('[:Event|load|#f|#t|[:HTMLBodyElement|/body`a1`e]]');
event.parsedTarget.dispatchEvent(event);Init Based Connector
exports.InitBased = function(Class, serializedFields) { ... }Constructs a connector which is able to serialize instances of Class. Class' constructor must accept single argument, which is a map containing initial values for properties of constructed object (init object pattern?). Constructed connector serializes fields of names and in order as passed in serializedFields array.
var WSON = require('wson').Wson;
var connectors = require('wson-event-connector');
var wson = new WSON({ connectors: {
'Weather': new connectors.InitBased(Weather, [ 'temperature', 'pressure', 'humidity', 'sky' ])
}});
var weather = new Weather({
temperature: '27C',
pressure: '1000HpA',
humidity: '75%',
sky: 'clear'
});
console.log(wson.stringify(weather));
// [:Weather|27C|1000Hpa|75%|clear]License
Copyright © 2016 - 2019 Maciej Chałapuk. Released under MIT license.