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-connector

Usage

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:

Event

(Not Yet) Supported Events

Near future should bring support for following classes:

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, because Blob‘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 always true (Event.preventDefault()
called inside an event listener changes it to false).
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]