xml-stream-editor 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 CHANGELOG
 ===
 
+0.2.1
+---
+
+Validate selector strings passed to `createXMLEditor` (for now, very basic.
+Just making sure there is only one space between element names in each
+selector).
+
+Fix issue where in some cases a selectors would match against the
+suffixes/endings of elements, and not always the full element name
+(e.g.,the selector `"steak"` would sometimes match elements like
+`<mistake>`).
+
 0.2.0
 ---
 

package/README.md

@@ -78,7 +78,6 @@ interface Options {
 
   // Options defined by the "saxes" library, and passed to the "saxes" parser
   //
-  // eslint-disable-next-line max-len
   // https://github.com/lddubeau/saxes/blob/4968bd09b5fd0270a989c69913614b0e640dae1b/src/saxes.ts#L557
   // https://www.npmjs.com/package/saxes
   saxes?: SaxesOptions
@@ -116,46 +115,43 @@ import { createReadStream } from 'node:fs'
 import { pipeline } from 'node:stream/promises'
 import { createXMLEditor, newElement } from 'xml-stream-editor'
 
-(async () => {
-    // The keys of this object are selector strings, and the
-    // values are functions that get called with matching elements.
-    const rules = {
-        "main character": (elm) => {
-            switch (elm.text) {
-                case "Marge Simpson":
-                    elm.attributes["hair"] = "blue"
-                    break
-                case "Homer Simpson":
-                    elm.text += " (Sr.)"
-                    break
-                case "Lisa Simpson":
-                    elm.text = ""
-
-                    // Create an <instrument> element and make it
-                    // a child element.
-                    const instrumentElm = newElement("instrument")
-                    instrumentElm.text = "saxophone"
-                    elm.children.push(instrumentElm)
-
-                    // Also create a new <name> element, and also make it
-                    // a child element.
-                    const nameElm = newElement("name")
-                    nameElm.text = "Lisa Simpson"
-                    elm.children.push(nameElm)
-                    break
-                case "Bart Simpson":
-                    // Remove the node by not returning an element.
-                    return
-            }
-            return elm
+// The keys of this object are selector strings, and the
+// values are functions that get called with matching elements.
+const rules = {
+    "main character": (elm) => {
+        switch (elm.text) {
+            case "Marge Simpson":
+                elm.attributes["hair"] = "blue"
+                break
+            case "Homer Simpson":
+                elm.text += " (Sr.)"
+                break
+            case "Lisa Simpson":
+                elm.text = ""
+
+                // Create an <instrument> element and make it a child element.
+                const instrumentElm = newElement("instrument")
+                instrumentElm.text = "saxophone"
+                elm.children.push(instrumentElm)
+
+                // Also create a new <name> element, and also make it a child
+                // element.
+                const nameElm = newElement("name")
+                nameElm.text = "Lisa Simpson"
+                elm.children.push(nameElm)
+                break
+            case "Bart Simpson":
+                // Remove the node by not returning an element.
+                return
         }
+        return elm
     }
-    await pipeline(
-        createReadStream("simpsons.xml"), // above example
-        createXMLEditor(rules),
-        process.stdout
-    )
-})()
+}
+await pipeline(
+    createReadStream("simpsons.xml"), // above example
+    createXMLEditor(rules),
+    process.stdout
+)
 ```
 
 And you'll find this printed to `STDOUT` (reformatted and annotated):
@@ -203,29 +199,31 @@ import { createReadStream } from 'node:fs'
 import { pipeline } from 'node:stream/promises'
 import { createXMLEditor, newElement } from 'xml-stream-editor'
 
-(async () => {
-    const rules = {
-        // This rule will match first, since the "main" element will be
-        // identified first during parsing.
-        "main character": (elm) => {
-            // editing goes here
-            return elm
-        },
-        // And as a result, this rule will never be applied during editing
-        // (since anytime "character" would match a <character> element,
-        // that <character> element will have already been matched by the
-        // above "main character" selector.
-        "character": (elm) => {
-            // this function would never be called in this document.
-            return elm
-        },
-    }
-    await pipeline(
-        createReadStream("simpsons.xml"), // above example
-        createXMLEditor(rules),
-        process.stdout
-    )
-})()
+const rules = {
+    // This rule will match first, since the "main" element will be
+    // identified first during parsing.
+    "main character": (elm) => {
+        // editing goes here
+        return elm
+    },
+    // And as a result, this rule will never match the "Disco Stu"
+    // or "Julius Hibbert" elements, since anytime the "character" selector
+    // would match a <character> element, that <character> element will
+    // have already been matched by the above "main character" selector.
+    //
+    // However, this selector would match (and so this function would
+    // be called with) the two <character> elements that are children
+    // of the <side> element.
+    "character": (elm) => {
+        // this function would never be called in this document.
+        return elm
+    },
+}
+await pipeline(
+    createReadStream("simpsons.xml"), // above example
+    createXMLEditor(rules),
+    process.stdout
+)
 ```
 
 ## Motivation

package/dist/element.js

@@ -0,0 +1,69 @@
+import xnv from 'xml-name-validator';
+const isValidName = xnv.qname;
+export class Element {
+    attributes;
+    children = [];
+    name;
+    text;
+    constructor(name, attributes) {
+        this.name = name;
+        this.attributes = attributes
+            ? JSON.parse(JSON.stringify(attributes))
+            : Object.create(null);
+    }
+    validate() {
+        if (typeof this.name !== 'string') {
+            return [false, new Error('No name provided for element')];
+        }
+        if (!isValidName(this.name)) {
+            return [false, new Error(`"${this.name}" is not a valid element name`)];
+        }
+        if (typeof this.attributes !== 'object' || this.attributes === null) {
+            return [false, new Error('"attributes" property is not an object')];
+        }
+        for (const attrName of Object.keys(this.attributes)) {
+            if (!isValidName(attrName)) {
+                return [false, new Error(`"${attrName}" is not a valid attribute name`)];
+            }
+        }
+        for (const child of this.children) {
+            const [isChildValid, childError] = child.validate();
+            if (!isChildValid) {
+                return [false, childError];
+            }
+        }
+        return [true, undefined];
+    }
+}
+export class ParsedElement extends Element {
+    children = [];
+    static fromSaxesNode(node) {
+        // Here we check if each attribute name is simple (and so just a
+        // string), or in the namespace representation the "saxes" library
+        // uses (in which case attrValue will be a SaxesAttributeNS
+        // object, that we have to unpack a bit)
+        const attributes = Object.create(null);
+        if (node.attributes) {
+            for (const [attrName, attrValue] of Object.entries(node.attributes)) {
+                if (typeof attrValue === 'string') {
+                    attributes[attrName] = attrValue;
+                    continue;
+                }
+                attributes[attrValue.name] = attrValue.value;
+            }
+        }
+        return new ParsedElement(node.name, attributes);
+    }
+    clone() {
+        const cloneElm = new ParsedElement(this.name, this.attributes);
+        cloneElm.text = this.text;
+        cloneElm.children = [];
+        for (const aChildElm of this.children) {
+            cloneElm.children.push(aChildElm.clone());
+        }
+        return cloneElm;
+    }
+}
+export const newElement = (name, attributes) => {
+    return new Element(name, attributes);
+};

package/dist/index.js

@@ -1,2 +1,2 @@
-import { createXMLEditor, newElement, } from './xml-stream-editor.js';
-export { createXMLEditor, newElement, };
+export { Element, newElement } from './element.js';
+export { createXMLEditor, } from './xml-stream-editor.js';

package/dist/markup.js

@@ -1,6 +1,4 @@
 import xmlescape from 'xml-escape';
-import xnv from 'xml-name-validator';
-export const isValidName = xnv.qname;
 export const toAttrValue = (value) => {
     return xmlescape(value);
 };

package/dist/selector.js

@@ -0,0 +1,60 @@
+// Represents the user provided selector strings, for defining which
+// XML elements in the XML document they want to edit.
+//
+// We modify the (simplified) XML paths used to i. allow user to define
+// which XML elements they want to edit, and ii. track the position of
+// each parsed XML element in the incoming XML document.
+//
+// This allows us to quickly check whether a user-provided "selector"
+// string matches the current XML parse stack with a simple .endsWith()
+// call (specifically pathToJustParsedXMLElement.endsWith(userProvidedSelector).
+import xnv from 'xml-name-validator';
+// Single character string that cannot appear in XML element names.
+const pathSeparator = '@';
+const process = (elementPath) => {
+    const collapsedWhiteSpace = elementPath.trim().replace(/ +/g, ' ');
+    return collapsedWhiteSpace.split(' ').map(x => pathSeparator + x).join('');
+};
+const validate = (selector) => {
+    for (const elmName of selector.split(' ')) {
+        if (xnv.name(elmName) === true) {
+            continue;
+        }
+        const msg = `Selector "${selector}" contains invalid name "${elmName}"`;
+        return [false, new Error(msg)];
+    }
+    return [true, undefined];
+};
+// Simple class used for tracking the path to an element in an XML document,
+// when parsing the XML document.
+//
+// Mostly this is just wrapping how we track the position of each element
+// in the XML document as we're parsing it, and annotating that path
+// in a way that makes it easy to check if a SelectorRule matches the
+// leaf-element in that path.
+export class ElementPath {
+    path;
+    pathForMatching;
+    constructor(path) {
+        this.path = path;
+        this.pathForMatching = process(path);
+    }
+    append(elmName) {
+        return new ElementPath(this.path + ' ' + elmName);
+    }
+    matches(selector) {
+        return this.pathForMatching.endsWith(selector.text);
+    }
+}
+export class SelectorRule {
+    text;
+    pathForMatching;
+    constructor(selector) {
+        const [isValid, err] = validate(selector);
+        if (!isValid) {
+            throw err;
+        }
+        this.text = process(selector);
+        this.pathForMatching = process(this.text);
+    }
+}

package/dist/xml-stream-editor.js

@@ -1,63 +1,9 @@
 import { strict as assert } from 'node:assert';
 import { Transform } from 'node:stream';
 import { SaxesParser } from 'saxes';
-import { isValidName, toAttrValue, toBodyText, toCloseTag, toOpenTag } from './markup.js';
-export const newElement = (name) => {
-    return {
-        name: name,
-        text: undefined,
-        attributes: Object.create(null),
-        children: [],
-    };
-};
-const throwOnInvalidElement = (elm) => {
-    if (typeof elm.name !== 'string') {
-        throw new Error('No name provided for element');
-    }
-    if (!isValidName(elm.name)) {
-        throw new Error(`"${elm.name}" is not a valid XML element name`);
-    }
-    if (typeof elm.attributes !== 'object' || elm.attributes === null) {
-        throw new Error('"attributes" property on element is not an object');
-    }
-    for (const attrName of Object.keys(elm.attributes)) {
-        if (!isValidName(attrName)) {
-            throw new Error(`"${attrName}" is not a valid XML attribute name`);
-        }
-    }
-    elm.children.forEach(throwOnInvalidElement);
-};
-const cloneElement = (elm) => {
-    const newElm = newElement(elm.name);
-    newElm.text = elm.text;
-    newElm.attributes = JSON.parse(JSON.stringify(elm.attributes));
-    newElm.children = elm.children.map(cloneElement);
-    return newElm;
-};
-const elementForNode = (node) => {
-    // Here we check if each attribute name is simple (and so just a
-    // string), or in the namespace representation the "saxes" library
-    // uses (in which case attrValue will be a SaxesAttributeNS
-    // object, that we have to unpack a bit)
-    const attributes = Object.create(null);
-    if (node.attributes) {
-        for (const [attrName, attrValue] of Object.entries(node.attributes)) {
-            if (typeof attrValue === 'string') {
-                attributes[attrName] = attrValue;
-                continue;
-            }
-            attributes[attrValue.name] = attrValue.value;
-        }
-    }
-    return elementForNameAndAttrs(node.name, attributes);
-};
-const elementForNameAndAttrs = (name, attrs) => {
-    const newElm = newElement(name);
-    if (attrs) {
-        newElm.attributes = attrs;
-    }
-    return newElm;
-};
+import { ParsedElement } from './element.js';
+import { toAttrValue, toBodyText, toCloseTag, toOpenTag } from './markup.js';
+import { ElementPath, SelectorRule } from './selector.js';
 class XMLStreamEditorTransformer extends Transform {
     // Default options, used if the caller doesn't provide any options (or
     // merged into the provided options if the user only sets some options).
@@ -71,9 +17,9 @@ class XMLStreamEditorTransformer extends Transform {
     // Used to track how deep in the XML tree the parser is, so that we can
     // check newly parsed elements against the passed editor rules.
     #parseStack = [];
-    // This is a map of (VERY) simple xpaths (i.e., only XML element names;
-    // no attributes, no name spaces, etc).
-    #editingRules;
+    // This is a map of objects that represent simple xpaths (i.e., only XML
+    // element names (no attributes, no name spaces, etc).
+    #rules;
     // Handle to the 'saxes' xml parser object.
     #xmlParser;
     // If set, tracks the current element in the parser stack that matches
@@ -85,9 +31,13 @@ class XMLStreamEditorTransformer extends Transform {
     #error;
     #pushParsedElementToStack(element) {
         const topOfStackElm = this.#parseStack.at(-1);
+        // We prefix every element name in the parse stack with '@' (a character
+        // that isn't valid in an XML element name) so that we can easily
+        // check if a selector matches the parse stack by just checking if
+        // the selector matches right end of the stack path.
         const pathToElement = topOfStackElm
-            ? topOfStackElm.path + ' ' + element.name
-            : element.name;
+            ? topOfStackElm.path.append(element.name)
+            : new ElementPath(element.name);
         this.#parseStack.push({
             element: element,
             path: pathToElement,
@@ -101,14 +51,13 @@ class XMLStreamEditorTransformer extends Transform {
         // This method is only called after pushing an element to the stack,
         // so this is guaranteed to be true
         assert(topOfStack);
-        const topOfStackPath = topOfStack.path;
-        for (const [selector, editorFunc] of Object.entries(this.#editingRules)) {
-            if (topOfStackPath.endsWith(selector)) {
+        for (const [selectorRule, editorFunc] of this.#rules.entries()) {
+            if (topOfStack.path.matches(selectorRule)) {
                 // The depth of the root of this subtree in the stack
                 const depth = this.#parseStack.length - 1;
                 assert(depth >= 0);
                 const elmToEdit = this.#parseStack[depth].element;
-                return { selector: selector, func: editorFunc, element: elmToEdit };
+                return { selector: selectorRule, func: editorFunc, element: elmToEdit };
             }
         }
         return null;
@@ -128,12 +77,16 @@ class XMLStreamEditorTransformer extends Transform {
     }
     #callUserFuncOnCompletedElementAndWriteToStream() {
         assert(this.#elmToEditInfo);
-        const clonedElm = cloneElement(this.#elmToEditInfo.element);
+        const clonedElm = this.#elmToEditInfo.element.clone();
+        const editElmFunc = this.#elmToEditInfo.func;
         try {
-            const editedElm = this.#elmToEditInfo.func(clonedElm);
+            const editedElm = editElmFunc(clonedElm);
             if (editedElm) {
                 if (this.#options.validate === true) {
-                    throwOnInvalidElement(editedElm);
+                    const [isValid, error] = editedElm.validate();
+                    if (!isValid) {
+                        throw error;
+                    }
                 }
                 this.#writeElementToStream(editedElm);
             }
@@ -155,7 +108,7 @@ class XMLStreamEditorTransformer extends Transform {
             //    and append ourselves to the stack.
             // 3. We are NOT the root of a subtree to be edited, in which case
             //    we just add ourselves to the stack.
-            const newElement = elementForNode(node);
+            const newElement = ParsedElement.fromSaxesNode(node);
             this.#pushParsedElementToStack(newElement);
             // Check for case one
             if (this.#isInSubtreeToBeEdited()) {
@@ -246,7 +199,13 @@ class XMLStreamEditorTransformer extends Transform {
             saxes: options?.saxes ?? defaultOptions.saxes,
         };
         this.#options = mergedOptions;
-        this.#editingRules = editingRules;
+        this.#rules = new Map();
+        for (const [selector, editFunc] of Object.entries(editingRules)) {
+            // This will throw if one of the user-provided selectors
+            // is invalid.
+            const parsedSelector = new SelectorRule(selector);
+            this.#rules.set(parsedSelector, editFunc);
+        }
         this.#xmlParser = new SaxesParser(this.#options.saxes);
         this.#configureParserCallbacks();
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xml-stream-editor",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "A streaming xml editor.",
   "main": "dist/index.js",
   "files": [

package/src/types.d.ts

@@ -2,11 +2,12 @@ import { Transform } from 'node:stream'
 
 import { SaxesOptions } from 'saxes'
 
-export declare interface Element {
-  name: string
-  text?: string
+export declare class Element {
+  constructor (name: string, attributes?: Record<string, string>)
   attributes: Record<string, string>
   children: Element[]
+  name: string
+  text?: string
 }
 
 export declare interface Options {
@@ -34,6 +35,8 @@ export declare interface Options {
 export type Selector = string
 export type EditorFunc = (elm: Element) => Element | undefined
 export type EditingRules = Record<Selector, EditorFunc>
+// Just wrapper for `new Element(name)`, mostly a remnant of a previous
+// implementation approach.
 export declare const newElement: (name: string) => Element
 export declare const createXMLEditor: (
   editingRules: EditingRules, options?: Options) => Transform