xml-twig 1.7.13 → 1.9.0

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

@@ -156,6 +156,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)
@@ -249,7 +251,8 @@ Purges the current, typically used after element has been processed.<br>The root
 <a name="Twig+purgeUpTo"></a>
 
 ### twig.purgeUpTo
-Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.<br>
+Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.<br>
+The `elt` object is not purged. If you like to purge including `elt`, use `.purgeUpTo(elt.previous())`
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 
@@ -271,7 +274,8 @@ Escapes special XML characters. According W3C specification these are only `&, <
 <a name="Twig+isEmpty"></a>
 
 ### twig.isEmpty ⇒ <code>boolean</code>
-Returns `true` if the element is empty, otherwise `false`.
+Returns `true` if the element is empty, otherwise `false`.
+An empty element has no text nor any child elements, however empty elements can have attributes.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>boolean</code> - true if empty element  
@@ -306,7 +310,8 @@ The position in `#children` array. For root object 0
 <a name="Twig+path"></a>
 
 ### twig.path ⇒ <code>string</code>
-The X-Path position of the element
+The X-Path position of the element
+NOTE: Applies only to currently loaded elements.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - X-Path  
@@ -406,7 +411,8 @@ Creates xml-writer from current element
 <a name="Twig+attr"></a>
 
 ### twig.attr ⇒ <code>string</code> \| <code>number</code> \| <code>object</code>
-Returns attribute value or `null` if not found.<br>
+Returns attribute value or `null` if not found.<br>
+If more than one  matches the condition, then it returns object as [attribute()](#attribute)
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> \| <code>number</code> \| <code>object</code> - - The value of the attribute or `null` if the  does not exist  
@@ -449,7 +455,10 @@ Retrieve or update XML attribute. For update, the condition must be a string, i.
 
 **Example**  
 ```js
-attribute((name, val) => { return name === 'age' && val > 50})
+attribute((name, val) => { return name === 'age' && val > 50})
+attribute((name) => { return ['firstName', 'lastName'].includes(name) })
+attribute('firstName')
+attribute(/name/i)
 ```
 <a name="Twig+deleteAttribute"></a>
 
@@ -492,6 +501,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)
@@ -712,7 +743,8 @@ Deletes the current element from tree, same as `purge()`. The root object cannot
 <a name="Twig+setRoot"></a>
 
 ### twig.setRoot(name) ℗
-Sets the name of root element. In some cases the root is created before the XML-Root element is available<br>
+Sets the name of root element. In some cases the root is created before the XML-Root element is available<br>
+Used internally!
 
 **Kind**: instance method of [<code>Twig</code>](#Twig)  
 **Access**: private  
@@ -790,6 +822,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)
@@ -883,7 +917,8 @@ Purges the current, typically used after element has been processed.<br>The root
 <a name="Twig+purgeUpTo"></a>
 
 ### twig.purgeUpTo
-Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.<br>
+Purges up to the elt element. This allows you to keep part of the tree in memory when you purge.<br>
+The `elt` object is not purged. If you like to purge including `elt`, use `.purgeUpTo(elt.previous())`
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 
@@ -905,7 +940,8 @@ Escapes special XML characters. According W3C specification these are only `&, <
 <a name="Twig+isEmpty"></a>
 
 ### twig.isEmpty ⇒ <code>boolean</code>
-Returns `true` if the element is empty, otherwise `false`.
+Returns `true` if the element is empty, otherwise `false`.
+An empty element has no text nor any child elements, however empty elements can have attributes.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>boolean</code> - true if empty element  
@@ -940,7 +976,8 @@ The position in `#children` array. For root object 0
 <a name="Twig+path"></a>
 
 ### twig.path ⇒ <code>string</code>
-The X-Path position of the element
+The X-Path position of the element
+NOTE: Applies only to currently loaded elements.
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> - X-Path  
@@ -1040,7 +1077,8 @@ Creates xml-writer from current element
 <a name="Twig+attr"></a>
 
 ### twig.attr ⇒ <code>string</code> \| <code>number</code> \| <code>object</code>
-Returns attribute value or `null` if not found.<br>
+Returns attribute value or `null` if not found.<br>
+If more than one  matches the condition, then it returns object as [attribute()](#attribute)
 
 **Kind**: instance property of [<code>Twig</code>](#Twig)  
 **Returns**: <code>string</code> \| <code>number</code> \| <code>object</code> - - The value of the attribute or `null` if the  does not exist  
@@ -1083,7 +1121,10 @@ Retrieve or update XML attribute. For update, the condition must be a string, i.
 
 **Example**  
 ```js
-attribute((name, val) => { return name === 'age' && val > 50})
+attribute((name, val) => { return name === 'age' && val > 50})
+attribute((name) => { return ['firstName', 'lastName'].includes(name) })
+attribute('firstName')
+attribute(/name/i)
 ```
 <a name="Twig+deleteAttribute"></a>
 
@@ -1126,6 +1167,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)
@@ -1346,7 +1409,8 @@ Deletes the current element from tree, same as `purge()`. The root object cannot
 <a name="Twig+setRoot"></a>
 
 ### twig.setRoot(name) ℗
-Sets the name of root element. In some cases the root is created before the XML-Root element is available<br>
+Sets the name of root element. In some cases the root is created before the XML-Root element is available<br>
+Used internally!
 
 **Kind**: instance method of [<code>Twig</code>](#Twig)  
 **Access**: private  
@@ -1446,7 +1510,7 @@ Generic error for unsupported condition
 
 ## SAX
 **Kind**: global constant  
-**Version:**: 1.7.12  
+**Version:**: 1.9.0  
 **Author:**: Wernfried Domscheit  
 **Copyright:**: Copyright (c) 2025 Wernfried Domscheit. All rights reserved.  
 **Website:**: https://www.npmjs.com/package/xml-twig  
@@ -1529,7 +1593,9 @@ Optional settings for the Twig parser
 <a name="TwigHandler"></a>
 
 ## TwigHandler
-Reference to handler functions for Twig objects.<br> 
+Reference to handler functions for Twig objects.<br> 
+Element can be specified as string, Regular Expression, custom function, `Twig.Root` or `Twig.Any`<br> 
+You can specify a `function` or a `event` name
 
 **Kind**: global typedef  
 **Properties**
@@ -1543,7 +1609,13 @@ Reference to handler functions for Twig objects.<br>
 <a name="HandlerCondition"></a>
 
 ## HandlerCondition : <code>string</code> \| <code>Array.&lt;string&gt;</code> \| <code>RegExp</code> \| [<code>HandlerConditionFilter</code>](#HandlerConditionFilter) \| [<code>Root</code>](#Root) \| [<code>Any</code>](#Any)
-Condition to specify when handler shall be called<br> 
- If `string` then the element name must be equal to the string
- If `string[]` then the element name must be included in string array
- If `RegExp` then the element name must match the Regular Expression
- If [HandlerConditionFilter](#HandlerConditionFilter) then function must return `true`
- Use `Twig.Root` to call the handler on root element, i.e. when the end of document is reached
- Use `Twig.Any` to call the handler on every element
+Condition to specify when handler shall be called<br> 
+- If `string` then the element name must be equal to the string
+- If `string[]` then the element name must be included in string array
+- If `RegExp` then the element name must match the Regular Expression
+- If [HandlerConditionFilter](#HandlerConditionFilter) then function must return `true`
+- Use `Twig.Root` to call the handler on root element, i.e. when the end of document is reached
+- Use `Twig.Any` to call the handler on every element
 
 **Kind**: global typedef  
 <a name="HandlerFunction"></a>
@@ -1572,7 +1644,12 @@ Custom filter function to specify when handler shall be called
 <a name="ElementCondition"></a>
 
 ## ElementCondition : <code>string</code> \| <code>RegExp</code> \| [<code>ElementConditionFilter</code>](#ElementConditionFilter) \| [<code>Twig</code>](#Twig) \| <code>undefined</code>
-Optional condition to get elements<br> 
- If `undefined`, then all elements are returned.<br> 
- If `string` then the element name must be equal to the string
- If `RegExp` then the element name must match the Regular Expression
- If [ElementConditionFilter](#ElementConditionFilter) then function must return `true`
- Use [Twig](#Twig) object to find a specific element
+Optional condition to get elements<br> 
+- If `undefined`, then all elements are returned.<br> 
+- If `string` then the element name must be equal to the string
+- If `RegExp` then the element name must match the Regular Expression
+- If [ElementConditionFilter](#ElementConditionFilter) then function must return `true`
+- Use [Twig](#Twig) object to find a specific element
 
 **Kind**: global typedef  
 <a name="ElementConditionFilter"></a>
@@ -1606,7 +1683,11 @@ Custom filter function to select desired elements
 <a name="AttributeCondition"></a>
 
 ## AttributeCondition : <code>string</code> \| <code>RegExp</code> \| [<code>AttributeConditionFilter</code>](#AttributeConditionFilter)
-Optional condition to get attributes<br> 
- If `undefined`, then all attributes are returned.<br> 
- If `string` then the attribute name must be equal to the string
- If `RegExp` then the attribute name must match the Regular Expression
- If [AttributeConditionFilter](#AttributeConditionFilter) then the attribute must filter function
+Optional condition to get attributes<br> 
+- If `undefined`, then all attributes are returned.<br> 
+- If `string` then the attribute name must be equal to the string
+- If `RegExp` then the attribute name must match the Regular Expression
+- If [AttributeConditionFilter](#AttributeConditionFilter) then the attribute must filter function
 
 **Kind**: global typedef  
 <a name="AttributeConditionFilter"></a>

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.0",
   "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.0
 * @author: Wernfried Domscheit
 * @copyright: Copyright (c) 2025 Wernfried Domscheit. All rights reserved.
 * @website: https://www.npmjs.com/package/xml-twig
@@ -958,6 +958,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