feat: formal method for setting event listeners

saxes now require the use of formal methods for setting event listeners.

BREAKING CHANGE: The individually named event handlers no longer exist. You now
must use the methods `on` and `off` to set handlers. Upcoming features require
that saxes know when handlers are added and removed, and it may be necessary in
the future to qualify how to add or remove a handler. Getters/setters are too
restrictives so we bite the bullet now and move to actual methods.

README.md

@@ -93,18 +93,18 @@ you may assume incorrectly.
 var saxes = require("./lib/saxes"),
   parser = new saxes.SaxesParser();
 
-parser.onerror = function (e) {
+parser.on("error", function (e) {
   // an error happened.
-};
-parser.ontext = function (t) {
+});
+parser.on("text", function (t) {
   // got some text.  t is the string of text.
-};
-parser.onopentag = function (node) {
+});
+parser.on("opentag", function (node) {
   // opened a tag.  node has "name" and "attributes"
-};
-parser.onend = function () {
+});
+parser.on("end", function () {
   // parser stream is done, and ready to have more stuff written to it.
-};
+});
 
 parser.write('<xml>Hello, <who name="world">world</who>!</xml>').close();
 ```
@@ -273,6 +273,11 @@ no point in setting these options.
   you should do it. (Obviously, feeding all the data at once with a single write
   is fastest.)
 
+* Don't set event handlers you don't need. Saxes has always aimed to avoid doing
+  work that will just be tossed away but future improvements hope to do this
+  more aggressively. One way saxes knows whether or not some data is needed is
+  by checking whether a handler has been set for a specific event.
+
 ## FAQ
 
 Q. Why has saxes dropped support for limiting the size of data chunks passed to

examples/dump-events.js

@@ -10,12 +10,12 @@ const start = Date.now();
 const parser = new saxes.SaxesParser({ xmlns: true });
 
 for (const ev of saxes.EVENTS) {
-  parser[`on${ev}`] = console.log.bind(undefined, ev);
+  parser.on(ev, console.log.bind(console.log, ev));
 }
 
-parser.onerror = err => {
+parser.on("error", err => {
   console.error(err);
-};
+});
 
 parser.write(xml);
 parser.close();

examples/example.js

@@ -8,21 +8,18 @@ const saxes = require("../build/dist/saxes");
 
 const parser = new saxes.SaxesParser();
 
-function inspector(ev) {
-  return function handler(data) {
-    // eslint-disable-next-line no-invalid-this
-    console.error("%s %s %j", `${this.line}:${this.column}`, ev, data);
-  };
-}
+const inspector = ev => function handler(data) {
+  console.error("%s %s %j", `${parser.line}:${parser.column}`, ev, data);
+};
 
 saxes.EVENTS.forEach(ev => {
-  parser[`on${ev}`] = inspector(ev);
+  parser.on(ev, inspector(ev));
 });
 
-parser.onend = () => {
+parser.on("end", () => {
   console.error("end");
   console.error(parser);
-};
+});
 
 let xml = fs.readFileSync(path.join(__dirname, "test.xml"), "utf8");
 function processChunk() {

examples/null-parser.js

@@ -22,9 +22,9 @@ if (bs === undefined) {
   const xml = fs.readFileSync(filePath);
   const start = Date.now();
   const parser = new saxes.SaxesParser({ xmlns: true });
-  parser.onerror = err => {
+  parser.on("error", err => {
     console.error(err);
-  };
+  });
 
   parser.write(xml);
   parser.close();
@@ -34,9 +34,9 @@ else {
   const input = fs.createReadStream(filePath);
   const start = Date.now();
   const parser = new saxes.SaxesParser({ xmlns: true });
-  parser.onerror = err => {
+  parser.on("error", err => {
     console.error(err);
-  };
+  });
 
   input.on("readable", () => {
     // eslint-disable-next-line no-constant-condition