xml-twig 1.7.13 → 1.9.1

package/README.md

@@ -4,27 +4,29 @@ Node module for processing huge XML documents in tree mode
 Inspired by Perl module [XML::Twig](https://metacpan.org/pod/XML::Twig)
 
 
-## When should I use this, motivation of this module
-When you need to read a XML file, then you have two principles:
+## When to Use This Module and Its Motivation
+When you need to read an XML file, there are two primary approaches:
 
-* The **Document Object Model (DOM)** style. These parser read the entire XML document into memory. Usually they provide easy methods to navigate in the document tree or make modifications. 
+1. **The Document Object Model (DOM) Style**
 
-   DOM parsers are perfect for rather small files, for example configuration files or (X-)HTML pages. However, for bigger XML files you may run into memory limits. When you parse a XML-File as DOM, then the footprint in RAM can be easily 10-20 times the size of the raw XML-String. If the XML-File is greater than [Buffer.constants.MAX_STRING_LENGTH](https://nodejs.org/api/buffer.html#bufferconstantsmax_string_length) (typically 512 MiB), then a DOM parser may throw error "Cannot create a string longer than 0x1fffffe8 characters".
+   These parsers read the entire XML document into memory. They usually provide convenient methods for navigating the document tree or making modifications. DOM parsers are ideal for smaller files, such as configuration files or (X-)HTML pages. However, for larger XML files, you may run into memory limitations. Parsing an XML file using the DOM method can cause memory usage to increase by 10-20 times the size of the raw XML string. If the XML file exceeds the size of [Buffer.constants.MAX_STRING_LENGTH](https://nodejs.org/api/buffer.html#bufferconstantsmax_string_length) (typically 512 MB), the DOM parser may throw an error: "Cannot create a string longer than 0x1fffffe8 characters."
 
-* The **stream** or **event** based parsers. These parser read the XML file "line by line". The biggest advantage of such a parser is, there is no limit in the size of the XML file. You can read XML files having a size of many terabytes, because you read always just a single node. 
+1. **Stream or Event-Based Parsers**
 
-   The backside: By default you cannot navigate in the document tree, you know only the current node.
+   These parsers read the XML file "line by line" or node by node. The main advantage of this approach is that there is no size limitation for the XML file. You can read XML files of several terabytes because only a single node is read into memory at a time.
+   
+   The downside is that, by default, you cannot navigate the document tree - you can only access the current node.
 
-This module tries to combine both principles. The XML document can be read in chunks and within a chunk you have all the nice features and functions you know from a DOM based parser.
+This module aims to combine both approaches. It reads the XML document in chunks, and within each chunk, you can utilize the familiar features and functions of a DOM-based parser.
 
 ## Dependencies
-XML documents are read either with [sax](https://www.npmjs.com/package/sax) or [node-expat](https://www.npmjs.com/package/node-expat) parser. More parser may be added in future releases. By default the `sax` parser is used. However, I clearly recommend using the `node-expat` parser. All other parsers I tested, are not compliant to XML standards.
+XML documents are parsed using either the [sax](https://www.npmjs.com/package/sax) or [node-expat](https://www.npmjs.com/package/node-expat) parser. parsers. Additional parsers may be added in future releases. By default, the `sax` parser is used. However, I strongly recommend using the `node-expat` parser, as other parsers I tested are not fully compliant with XML standards.
 
-**NOTE: The `node-expat` module is not automatically installed with this module. Install the parser by yourself, if you like to use it**
+**NOTE: The `node-expat` module is not automatically installed with this module. If you wish to use it, you must install it manually.**
 
 ## Installation
 
-Install module like any other node module and optionally `node-expat`:
+To install the module, use the standard Node.js installation process. Optionally, you can also install the `node-expat` parser:
 ```bash
 npm install xml-twig
 
@@ -32,7 +34,7 @@ npm install xml-twig
 npm install node-expat
 
 ```
-In my tests I parsed a 900 MB big XML file, the `node-expat` is faster than `sax` (node-expat: around 2:30 Minutes, sax: around 3:40 Minutes). However, you may run into problems when you try to install the `node-expat` parser. That's the reason why `node-expat` parser is not installed automatically.
+In my tests, I parsed a 900 MB XML file, and the `node-expat`t parser was faster than `sax` (`node-expat`: around 2:30 minutes, `sax`: around 3:40 minutes). However, you may encounter issues when installing the `node-expat` parser, which is why it's not installed automatically.
 
 ## How to use it
 
@@ -72,10 +74,9 @@ API Documentation: see [Twig](./doc/twig.md)
 
 - **Read XML Document in chucks**
   
-  The key feature of this module is to read and process XML files in chunks. You need to create handler functions for elements you like to process.<br>
-  The most notable difference to other parsers is the `purge()` and `purgeUpTo()` method. The parser reads the element and you decide how long you need to keep it in the memory. 
-  In many cases you will purge it immediately after you have used it but in some cases you may keep the element for later use. The parser knows the element position in the XML-Tree. 
+   The key feature of this module is the ability to read and process XML files in chunks. You need to define handler functions for the elements you want to process.
 
+   A major difference compared to other parsers is the  `purge()` and `purgeUpTo()` methods. The parser reads an element, and you decide how long to keep it in memory. In many cases, you will purge the element immediately after processing it, but in some situations, you might want to retain it for later use. The parser keeps track of the element’s position within the XML tree.
 
    ```js
    function bookHandler(elt, parserObj) {
@@ -146,10 +147,6 @@ API Documentation: see [Twig](./doc/twig.md)
 
    ```
 
-Be aware if you run methods like `elt.followingSibling()`, `elt.descendant()`, `elt.next()`, etc. on the current element. Such calls return empty result, because following element are not yet read from the XML file. You must navigate to an earlier element, e.g.<br>
-`elt.root().children()[0].followingSibling()`
-
-
 - **Read only parts from XML Document**
 
    If you like to read only certain elements, use option `partial: true`. The `root` element is always read. 
@@ -294,6 +291,9 @@ Here are some examples the get attribute and values:
 
 `.writer(indented|xw)` - **XMLWriter**: Returns a [XMLWriter](https://www.npmjs.com/package/xml-writer) object you can use to print the currently loaded XML tree.<br>Instead of providing an indented parameter (`true`, `false` or indent character) you can also provide an `XMLWriter` object which adds more flexibility.
 
+Be aware if you call methods like `elt.followingSibling()`, `elt.descendant()`, `elt.next()`, etc. on the current element, they will return empty results. This is because the following elements have not yet been read from the XML file. To navigate to an earlier element, you can use a method like:<br>
+`elt.root().children()[0].followingSibling()`
+
 **condition** Parameter
 
 You can specify condition on above methods. You can filter elements by following conditions:

package/doc/twig.md

@@ -127,6 +127,7 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
     * [.children](#Twig+children) : [<code>Array.&lt;Twig&gt;</code>](#Twig) ℗
     * [.parent](#Twig+parent) : [<code>Twig</code>](#Twig) \| <code>undefined</code> ℗
     * [.pinned](#Twig+pinned) : <code>boolean</code> ℗
+    * [.trim](#Twig+trim) : <code>boolean</code> ℗
     * [.purge](#Twig+purge)
     * [.purgeUpTo](#Twig+purgeUpTo)
     * [.escapeEntity](#Twig+escapeEntity)
@@ -156,6 +157,8 @@ You can specify a <code>function</code> or a <code>event</code> name</p>
     * [.parent](#Twig+parent) ⇒ [<code>Twig</code>](#Twig)
     * [.self](#Twig+self) ⇒ [<code>Twig</code>](#Twig)
     * [.children](#Twig+children) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
+    * [.firstChild](#Twig+firstChild) ⇒ [<code>Twig</code>](#Twig)
+    * [.lastChild](#Twig+lastChild) ⇒ [<code>Twig</code>](#Twig)
     * [.next](#Twig+next) ⇒ [<code>Twig</code>](#Twig)
     * [.previous](#Twig+previous) ⇒ [<code>Twig</code>](#Twig)
     * [.first](#Twig+first) ⇒ [<code>Twig</code>](#Twig)
@@ -238,6 +241,13 @@ The parent object. Undefined on root element
 ### twig.pinned : <code>boolean</code> ℗
 Determines whether twig is needed in partial load
 
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+**Access**: private  
+<a name="Twig+trim"></a>
+
+### twig.trim : <code>boolean</code> ℗
+Determines whether text is trimmed
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
 <a name="Twig+purge"></a>
@@ -327,7 +337,7 @@ Returns the name of the element. Synonym for `twig.name`
 <a name="Twig+text"></a>
 
 ### twig.text ⇒ <code>string</code>
-The text of the element. No matter if given as text or CDATA entity
+The text of the element. No matter if given as text or CDATA entity.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - Element text or empty string  
@@ -492,6 +502,28 @@ All children, optionally matching `condition` of the current element or empty ar
 | --- | --- | --- |
 | condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
+<a name="Twig+firstChild"></a>
+
+### twig.firstChild ⇒ [<code>Twig</code>](#Twig)
+The first matching child, optionally matching `condition` of the current element or null
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+
+<a name="Twig+lastChild"></a>
+
+### twig.lastChild ⇒ [<code>Twig</code>](#Twig)
+The last matching child, optionally matching `condition` of the current element or null
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+
 <a name="Twig+next"></a>
 
 ### twig.next ⇒ [<code>Twig</code>](#Twig)
@@ -761,6 +793,7 @@ Common function to filter Twig element
     * [.children](#Twig+children) : [<code>Array.&lt;Twig&gt;</code>](#Twig) ℗
     * [.parent](#Twig+parent) : [<code>Twig</code>](#Twig) \| <code>undefined</code> ℗
     * [.pinned](#Twig+pinned) : <code>boolean</code> ℗
+    * [.trim](#Twig+trim) : <code>boolean</code> ℗
     * [.purge](#Twig+purge)
     * [.purgeUpTo](#Twig+purgeUpTo)
     * [.escapeEntity](#Twig+escapeEntity)
@@ -790,6 +823,8 @@ Common function to filter Twig element
     * [.parent](#Twig+parent) ⇒ [<code>Twig</code>](#Twig)
     * [.self](#Twig+self) ⇒ [<code>Twig</code>](#Twig)
     * [.children](#Twig+children) ⇒ [<code>Array.&lt;Twig&gt;</code>](#Twig)
+    * [.firstChild](#Twig+firstChild) ⇒ [<code>Twig</code>](#Twig)
+    * [.lastChild](#Twig+lastChild) ⇒ [<code>Twig</code>](#Twig)
     * [.next](#Twig+next) ⇒ [<code>Twig</code>](#Twig)
     * [.previous](#Twig+previous) ⇒ [<code>Twig</code>](#Twig)
     * [.first](#Twig+first) ⇒ [<code>Twig</code>](#Twig)
@@ -872,6 +907,13 @@ The parent object. Undefined on root element
 ### twig.pinned : <code>boolean</code> ℗
 Determines whether twig is needed in partial load
 
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+**Access**: private  
+<a name="Twig+trim"></a>
+
+### twig.trim : <code>boolean</code> ℗
+Determines whether text is trimmed
+
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Access**: private  
 <a name="Twig+purge"></a>
@@ -961,7 +1003,7 @@ Returns the name of the element. Synonym for `twig.name`
 <a name="Twig+text"></a>
 
 ### twig.text ⇒ <code>string</code>
-The text of the element. No matter if given as text or CDATA entity
+The text of the element. No matter if given as text or CDATA entity.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - Element text or empty string  
@@ -1126,6 +1168,28 @@ All children, optionally matching `condition` of the current element or empty ar
 | --- | --- | --- |
 | condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
 
+<a name="Twig+firstChild"></a>
+
+### twig.firstChild ⇒ [<code>Twig</code>](#Twig)
+The first matching child, optionally matching `condition` of the current element or null
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+
+<a name="Twig+lastChild"></a>
+
+### twig.lastChild ⇒ [<code>Twig</code>](#Twig)
+The last matching child, optionally matching `condition` of the current element or null
+
+**Kind**: instance property of [<code>Twig</code>](#Twig)  
+
+| Param | Type | Description |
+| --- | --- | --- |
+| condition | [<code>ElementCondition</code>](#ElementCondition) | Optional condition |
+
 <a name="Twig+next"></a>
 
 ### twig.next ⇒ [<code>Twig</code>](#Twig)
@@ -1446,7 +1510,7 @@ Generic error for unsupported condition
 
 ## SAX
 **Kind**: global constant  
-**Version:**: 1.7.12  
+**Version:**: 1.9.1  
 **Author:**: Wernfried Domscheit  
 **Copyright:**: Copyright (c) 2025 Wernfried Domscheit. All rights reserved.  
 **Website:**: https://www.npmjs.com/package/xml-twig  

package/package.json

@@ -5,7 +5,7 @@
   },
   "name": "xml-twig",
   "description": "Node module for processing huge XML documents in tree mode",
-  "version": "1.7.13",
+  "version": "1.9.1",
   "main": "twig.js",
   "directories": {
     "doc": "doc"
@@ -15,16 +15,15 @@
     "doc/*.md"
   ],
   "devDependencies": {
-    "jsdoc-to-markdown": "^9.0.0",
-    "luxon": "^3.5.0",
+    "jsdoc-to-markdown": "^9.1.1",
+    "luxon": "^3.6.1",
     "node-expat": "^2.4.1"
   },
   "scripts": {
     "test": "node demo.js",
-    "preversion": "jsdoc2md --private twig.js > doc/twig.md",
-    "postversion": "sed -i -e \"s/@version: .*/@version: %npm_package_version%/\" twig.js",
-    "prepack": "unix2dos twig.js doc/twig.md",
-    "prepare": "git commit -a -m \"Updated doc and version\""
+    "postversion": "sed -bi -e \"s/@version: .*/@version: %npm_package_version%/\" twig.js",
+    "prepare": "jsdoc2md --EOL win32 --private twig.js > doc/twig.md",
+    "postpack": "git commit -a -m \"Updated doc and version\""
   },
   "repository": {
     "type": "git",

package/twig.js

@@ -1,5 +1,5 @@
 /**
-* @version: 1.7.13
+* @version: 1.9.1
 * @author: Wernfried Domscheit
 * @copyright: Copyright (c) 2025 Wernfried Domscheit. All rights reserved.
 * @website: https://www.npmjs.com/package/xml-twig
@@ -278,6 +278,12 @@ function createParser(handler, options = {}) {
       enumerable: true
    });
 
+   Object.defineProperty(parser, 'trimText', {
+      value: options.trim,
+      writable: false,
+      enumerable: true
+   });
+
    if (options.file != null) {
       Object.defineProperty(parser, 'file', {
          value: options.file,
@@ -289,7 +295,7 @@ function createParser(handler, options = {}) {
    // Common events
    parser.on('text', function (str) {
       if (parser.twig.current === null) return;
-      parser.twig.current.text = options.trim ? str.trim() : str;
+      parser.twig.current.text = str;
    });
 
    parser.on("comment", function (str) {
@@ -513,6 +519,12 @@ class Twig {
    */
    #pinned = false;
 
+   /**
+    * Determines whether text is trimmed
+   * @type {boolean}
+   */
+   #trim = true;
+
    /**
    * Create a new Twig object
    * @param {Parser} parser - The main parser object
@@ -525,6 +537,7 @@ class Twig {
       if (index === undefined)
          parser.twig.current = this;
 
+      this.#trim = parser.trimText;
       if (name === null) {
          // Root element not available yet
          parser.twig.tree = this;
@@ -698,11 +711,15 @@ class Twig {
    }
 
    /**
-   * The text of the element. No matter if given as text or CDATA entity
+   * The text of the element. No matter if given as text or CDATA entity.
+   * If option `trim: true`, then whitespace from both ends of the string are removed
    * @returns {string} Element text or empty string
    */
    get text() {
-      return this.#text ?? '';
+      if (this.#text === null)
+         return ''
+      else
+         return this.#trim ? this.#text.trim() : this.#text;
    }
 
    /**
@@ -958,6 +975,26 @@ class Twig {
       return this.filterElements(this.#children, condition);
    };
 
+   /**
+   * The first matching child, optionally matching `condition` of the current element or null
+   * @param {ElementCondition} condition - Optional condition
+   * @returns {?Twig} 
+   */
+   firstChild = function (condition) {
+      let _children = this.children(condition);
+      return _children.length == 0 ? null : _children[0];
+   };
+
+   /**
+   * The last matching child, optionally matching `condition` of the current element or null
+   * @param {ElementCondition} condition - Optional condition
+   * @returns {?Twig} 
+   */
+   lastChild = function (condition) {
+      let _children = this.children(condition);
+      return _children.length == 0 ? null : _children[_children.length - 1];
+   };
+
    /**
    * Returns the next matching element. 
    * @param {ElementCondition} condition - Optional condition