feat: reinstating the attribute events

These had been dropped in the fork, but upcoming features warrant their
reintroduction.

src/saxes.ts

@@ -180,6 +180,7 @@ export const EVENTS = [
   "doctype",
   "comment",
   "opentagstart",
+  "attribute",
   "opentag",
   "closetag",
   "cdata",
@@ -194,6 +195,7 @@ const EVENT_NAME_TO_HANDLER_NAME: Record<EventName, string> = {
   doctype: "doctypeHandler",
   comment: "commentHandler",
   opentagstart: "openTagStartHandler",
+  attribute: "attributeHandler",
   opentag: "openTagHandler",
   closetag: "closeTagHandler",
   cdata: "cdataHandler",
@@ -241,6 +243,17 @@ export type CommentHandler = (comment: string) => void;
  */
 export type OpenTagStartHandler<O> = (tag: StartTagForOptions<O>) => void;
 
+export type AttributeEventForOptions<O extends SaxesOptions> =
+  O extends { xmlns: true } ? SaxesAttributeNSIncomplete :
+    O extends { xmlns?: false | undefined } ? SaxesAttributePlain :
+      SaxesAttribute;
+
+/**
+ * Event handler for attributes.
+ */
+export type AttributeHandler<O> =
+  (attribute: AttributeEventForOptions<O>) => void;
+
 /**
  * Event handler for an open tag. This is called when the open tag is
  * complete. (We've encountered the ">" that ends the open tag.) The default
@@ -294,6 +307,7 @@ export type EventNameToHandler<O, N extends EventName> = {
   "doctype": DoctypeHandler;
   "comment": CommentHandler;
   "opentagstart": OpenTagStartHandler<O>;
+  "attribute": AttributeHandler<O>;
   "opentag": OpenTagHandler<O>;
   "closetag": CloseTagHandler<O>;
   "cdata": CDataHandler;
@@ -333,20 +347,17 @@ export interface SaxesAttributeNS {
 }
 
 /**
- * This is an alias for SaxesAttributeNS which will eventually be removed in a
- * future major version.
- *
- * @deprecated
+ * This is an attribute, as recorded by a parser which parses namespaces but
+ * prior to the URI being resolvable. This is what is passed to the attribute
+ * event handler.
  */
-export type SaxesAttribute = SaxesAttributeNS;
+export type SaxesAttributeNSIncomplete =  Exclude<SaxesAttributeNS, "uri">;
 
 /**
  * This interface defines the structure of attributes when the parser is
  * NOT processing namespaces (created with ``xmlns: false``).
- *
- * This is not exported because this structure is used only internally.
  */
-interface SaxesAttributePlain {
+export interface SaxesAttributePlain {
   /**
    * The attribute's name.
    */
@@ -356,6 +367,11 @@ interface SaxesAttributePlain {
   value: string;
 }
 
+/**
+ * A saxes attribute, with or without namespace information.
+ */
+export type SaxesAttribute = SaxesAttributeNS | SaxesAttributePlain;
+
 /**
  * This are the fields that MAY be present on a complete tag.
  */
@@ -544,7 +560,7 @@ export type TagForOptions<O extends SaxesOptions> =
 
 export type StartTagForOptions<O extends SaxesOptions> =
   O extends { xmlns: true } ? SaxesStartTagNS :
-    O extends { xmlns: false | undefined } ? SaxesStartTagPlain :
+    O extends { xmlns?: false | undefined } ? SaxesStartTagPlain :
       SaxesStartTag;
 
 export class SaxesParser<O extends SaxesOptions = {}> {
@@ -582,7 +598,7 @@ export class SaxesParser<O extends SaxesOptions = {}> {
   private prevI!: number;
   private carriedFromPrevious?: string;
   private forbiddenState!: number;
-  private attribList!: (SaxesAttributeNS | SaxesAttributePlain)[];
+  private attribList!: (SaxesAttributeNSIncomplete | SaxesAttributePlain)[];
   private state!: number;
   private reportedTextBeforeRoot!: boolean;
   private reportedTextAfterRoot!: boolean;
@@ -611,6 +627,7 @@ export class SaxesParser<O extends SaxesOptions = {}> {
   private errorHandler?: ErrorHandler;
   private endHandler?: EndHandler;
   private readyHandler?: ReadyHandler;
+  private attributeHandler?: AttributeHandler<O>;
 
   /**
    * Indicates whether or not the parser is closed. If ``true``, wait for
@@ -2087,8 +2104,7 @@ export class SaxesParser<O extends SaxesOptions = {}> {
     let { i: start } = this;
     // eslint-disable-next-line no-constant-condition
     while (true) {
-      const code = this.getCode();
-      switch (code) {
+      switch (this.getCode()) {
         case q:
           this.pushAttrib(this.name,
                           this.text + chunk.slice(start, this.prevI));
@@ -2359,7 +2375,10 @@ export class SaxesParser<O extends SaxesOptions = {}> {
 
   private pushAttribNS(name: string, value: string): void {
     const { prefix, local } = this.qname(name);
-    this.attribList.push({ name, prefix, local, value, uri: undefined });
+    const attr = { name, prefix, local, value };
+    this.attribList.push(attr);
+    // eslint-disable-next-line no-unused-expressions
+    this.attributeHandler?.(attr as AttributeEventForOptions<O>);
     if (prefix === "xmlns") {
       const trimmed = value.trim();
       if (this.currentXMLVersion === "1.0" && trimmed === "") {
@@ -2376,7 +2395,10 @@ export class SaxesParser<O extends SaxesOptions = {}> {
   }
 
   private pushAttribPlain(name: string, value: string): void {
-    this.attribList.push({ name, value });
+    const attr = { name, value };
+    this.attribList.push(attr);
+    // eslint-disable-next-line no-unused-expressions
+    this.attributeHandler?.(attr as AttributeEventForOptions<O>);
   }
 
   /**
@@ -2493,7 +2515,7 @@ export class SaxesParser<O extends SaxesOptions = {}> {
     const seen = new Set();
     // Note: do not apply default ns to attributes:
     //   http://www.w3.org/TR/REC-xml-names/#defaulting
-    for (const attr of attribList as SaxesAttributeNS[]) {
+    for (const attr of attribList as SaxesAttributeNSIncomplete[]) {
       const { name, prefix, local } = attr;
       let uri;
       let eqname;

test/attribute-name.ts

@@ -5,6 +5,12 @@ test({
   xml: "<root length='12345'></root>",
   expect: [
     ["opentagstart", { name: "root", attributes: {}, ns: {} }],
+    ["attribute", {
+      name: "length",
+      value: "12345",
+      prefix: "",
+      local: "length",
+    }],
     [
       "opentag",
       {

test/attribute-no-space.ts

@@ -6,7 +6,15 @@ test({
   xml: "<root attr1=\"first\"attr2=\"second\"/>",
   expect: [
     ["opentagstart", { name: "root", attributes: {} }],
+    ["attribute", {
+      name: "attr1",
+      value: "first",
+    }],
     ["error", "1:20: no whitespace between attributes."],
+    ["attribute", {
+      name: "attr2",
+      value: "second",
+    }],
     ["opentag", {
       name: "root",
       attributes: {
@@ -35,6 +43,14 @@ test({
       name: "root",
       attributes: {},
     }],
+    ["attribute", {
+      name: "attr1",
+      value: "first",
+    }],
+    ["attribute", {
+      name: "attr2",
+      value: "second",
+    }],
     ["opentag", {
       name: "root",
       attributes: {
@@ -63,6 +79,14 @@ test({
       name: "root",
       attributes: {},
     }],
+    ["attribute", {
+      name: "attr1",
+      value: "first",
+    }],
+    ["attribute", {
+      name: "attr2",
+      value: "second",
+    }],
     ["opentag", {
       name: "root",
       attributes: {
@@ -91,6 +115,14 @@ test({
       name: "root",
       attributes: {},
     }],
+    ["attribute", {
+      name: "attr1",
+      value: "first",
+    }],
+    ["attribute", {
+      name: "attr2",
+      value: "second",
+    }],
     ["opentag", {
       name: "root",
       attributes: {

test/attribute-normalization.ts

@@ -11,6 +11,14 @@ test({
       name: "root",
       attributes: {},
     }],
+    ["attribute", {
+      name: "attr1",
+      value: "\r \n\t",
+    }],
+    ["attribute", {
+      name: "attr2",
+      value: "   a  b",
+    }],
     ["opentag", {
       name: "root",
       attributes: { attr1: "\r \n\t", attr2: "   a  b" },

test/attribute-unquoted.ts

@@ -7,6 +7,12 @@ test({
   expect: [
     ["opentagstart", { name: "root", attributes: {}, ns: {} }],
     ["error", "1:14: unquoted attribute value."],
+    ["attribute", {
+      name: "length",
+      value: "12345",
+      prefix: "",
+      local: "length",
+    }],
     ["opentag", {
       name: "root",
       attributes: {

test/bom.ts

@@ -17,6 +17,7 @@ test({
   xml: "\uFEFF<P BOM=\"\uFEFF\">\uFEFFStarts and ends with BOM\uFEFF</P>",
   expect: [
     ["opentagstart", { name: "P", attributes: {} }],
+    ["attribute", { name: "BOM", value: "\uFEFF" }],
     ["opentag", {
       name: "P",
       attributes: { BOM: "\uFEFF" },

test/cdata.ts

@@ -16,6 +16,7 @@ test({
   name: "cdata end in attribute",
   expect: [
     ["opentagstart", { name: "r", attributes: {} }],
+    ["attribute", { name: "foo", value: "]]>" }],
     ["opentag", {
       name: "r",
       attributes: {

test/duplicate-attribute.ts

@@ -8,6 +8,8 @@ test({
       name: "span",
       attributes: {},
     }],
+    ["attribute", { name: "id", value: "hello" }],
+    ["attribute", { name: "id", value: "there" }],
     ["error", "1:28: duplicate attribute: id."],
     ["opentag", {
       name: "span",

test/eol-handling.ts

@@ -22,6 +22,10 @@ describe("eol handling", () => {
     const expect = [
       ["text", "\n\n"],
       ["opentagstart", { name: "moo", attributes: {} }],
+      ["attribute", {
+        name: "a",
+        value: "12         3",
+      }],
       ["opentag", {
         name: "moo",
         attributes: {
@@ -142,6 +146,14 @@ SYSTEM
       ["processinginstruction", { target: "fnord", body: "" }],
       ["text", "\n"],
       ["opentagstart", { name: "moo", attributes: {} }],
+      ["attribute", {
+        name: "a",
+        value: "12         3",
+      }],
+      ["attribute", {
+        name: "b",
+        value: " z ",
+      }],
       ["opentag", {
         name: "moo",
         attributes: {
@@ -160,6 +172,10 @@ abc
       ["processinginstruction", { target: "fnord", body: "" }],
       ["text", "\n"],
       ["opentagstart", { name: "abc", attributes: {} }],
+      ["attribute", {
+        name: "a",
+        value: "bc",
+      }],
       ["opentag", {
         name: "abc",
         attributes: {

test/issue-47.ts

@@ -6,6 +6,7 @@ test({
   xml: "<a href=\"query.svc?x=1&amp;y=2&amp;z=3\"/>",
   expect: [
     ["opentagstart", { name: "a", attributes: {} }],
+    ["attribute", { name: "href", value: "query.svc?x=1&y=2&z=3" }],
     ["opentag", {
       name: "a",
       attributes: { href: "query.svc?x=1&y=2&z=3" },

test/opentagstart.ts

@@ -13,6 +13,15 @@ describe("openstarttag", () => {
           attributes: {},
         },
       ],
+      [
+        "attribute",
+        {
+          name: "length",
+          value: "12345",
+          prefix: "",
+          local: "length",
+        },
+      ],
       [
         "opentag",
         {
@@ -70,6 +79,13 @@ describe("openstarttag", () => {
           attributes: {},
         },
       ],
+      [
+        "attribute",
+        {
+          name: "length",
+          value: "12345",
+        },
+      ],
       [
         "opentag",
         {

test/testutil.ts

@@ -1,5 +1,6 @@
 import { expect } from "chai";
-import { EVENTS, SaxesOptions, SaxesParser } from "../build/dist/saxes";
+import { EventName, EVENTS, SaxesOptions,
+         SaxesParser } from "../build/dist/saxes";
 
 export interface TestOptions {
   xml?: string | string[];
@@ -8,14 +9,15 @@ export interface TestOptions {
   expect: any[];
   fn?: (parser: SaxesParser<{}>) => void;
   opt?: SaxesOptions;
+  events?: EventName[];
 }
 
 export function test(options: TestOptions): void {
-  const { xml, name, expect: expected, fn } = options;
+  const { xml, name, expect: expected, fn, events } = options;
   it(name, () => {
     const parser = new SaxesParser(options.opt);
     let expectedIx = 0;
-    for (const ev of EVENTS) {
+    for (const ev of events ?? EVENTS) {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any, no-loop-func
       parser.on(ev, (n: any) => {
         if (process.env.DEBUG !== undefined) {
@@ -49,9 +51,7 @@ export function test(options: TestOptions): void {
       }
     }
 
-    if (fn !== undefined) {
-      fn(parser);
-    }
+    fn?.(parser);
 
     expect(expectedIx).to.equal(expected.length);
   });

test/trailing-attribute-no-value.ts

@@ -6,6 +6,7 @@ test({
   expect: [
     ["opentagstart", { name: "root", attributes: {} }],
     ["error", "1:13: attribute without value."],
+    ["attribute", { name: "attrib", value: "attrib" }],
     ["opentag",
      { name: "root", attributes: { attrib: "attrib" }, isSelfClosing: false }],
     ["closetag",